Arize-Instrumentation

# Arize Instrumentation Skill

Use this skill when the user wants to **add Arize AX tracing** to their application. Follow the **two-phase, agent-assisted flow** from the [Agent-Assisted Tracing Setup](https://arize.com/docs/ax/alyx/tracing-assistant) and the [Arize AX Tracing — Agent Setup Prompt](https://arize.com/docs/PROMPT.md).

Quick start (for the user)

If the user asks you to "set up tracing" or "instrument my app with Arize", you can start with:

> Follow the instructions from https://arize.com/docs/PROMPT.md and ask me questions as needed.

Then execute the two phases below.

Core principles

- **Prefer inspection over mutation** — understand the codebase before changing it.

- **Do not change business logic** — tracing is purely additive.

- **Use auto-instrumentation where available** — add manual spans only for custom logic not covered by integrations.

- **Follow existing code style** and project conventions.

- **Keep output concise and production-focused** — do not generate extra documentation or summary files.

- **NEVER embed literal credential values in generated code** — always reference environment variables (e.g., `os.environ["ARIZE_API_KEY"]`, `process.env.ARIZE_API_KEY`). This includes API keys, space IDs, and any other secrets. The user sets these in their own environment; the agent must never output raw secret values.

Phase 0: Environment preflight

Before changing code:

1. Confirm the repo/service scope is clear. For monorepos, do not assume the whole repo should be instrumented.

2. Identify the local runtime surface you will need for verification:

- package manager and app start command

- whether the app is long-running, server-based, or a short-lived CLI/script

- whether `ax` will be needed for post-change verification

3. Do NOT proactively check `ax` installation or version. If `ax` is needed for verification later, just run it when the time comes. If it fails, see references/ax-profiles.md.

4. Never silently replace a user-provided space ID, project name, or project ID. If the CLI, collector, and user input disagree, surface that mismatch as a concrete blocker.

Phase 1: Analysis (read-only)

**Do not write any code or create any files during this phase.**

Steps

1. **Check dependency manifests** to detect stack:

- Python: `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile`

- TypeScript/JavaScript: `package.json`

- Java: `pom.xml`, `build.gradle`, `build.gradle.kts`

- Go: `go.mod`

2. **Scan import statements** in source files to confirm what is actually used.

3. **Check for existing tracing/OTel** — look for `TracerProvider`, `register()`, `opentelemetry` imports, `ARIZE_*`, `OTEL_*`, `OTLP_*` env vars, or other observability config (Datadog, Honeycomb, etc.).

4. **Identify scope** — for monorepos or multi-service projects, ask which service(s) to instrument.

What to identify

| Item | Examples |

|------|----------|

| Language | Python, TypeScript/JavaScript, Java, Go |

| Package manager | pip/poetry/uv, npm/pnpm/yarn, maven/gradle, go modules |

| LLM providers | OpenAI, Anthropic, LiteLLM, Bedrock, etc. |

| Frameworks | LangChain, LangGraph, LlamaIndex, Vercel AI SDK, Mastra, etc. |

| Existing tracing | Any OTel or vendor setup |

| Tool/function use | LLM tool use, function calling, or custom tools the app executes (e.g. in an agent loop) |

**Key rule:** When a framework is detected alongside an LLM provider, inspect the framework-specific tracing docs first and prefer the framework-native integration path when it already captures the model and tool spans you need. Add separate provider instrumentation only when the framework docs require it or when the framework-native integration leaves obvious gaps. If the app runs tools and the framework integration does not emit tool spans, add manual TOOL spans so each invocation appears with input/output (see **Enriching traces** below).

Phase 1 output

Return a concise summary:

- Detected languag