Arize Instrumentation Skill

Add Arize AX tracing to an app for the first time: detect the stack → fetch the one matching integration doc → wire auto-instrumentation → verify a trace lands.

Route locally. Map the detected stack to a single doc page via references/integration-routing.md (exhaustive for tracing integrations) and fetch only that page. If the stack isn't listed there, it has no dedicated integration — use manual instrumentation. Never bulk-fetch the PROMPT.md/llms.txt aggregates.

Rules: inspect before mutating; tracing is additive, never change business logic; follow existing style; no secrets in code and never ask the user to paste secrets (API keys, tokens) into the chat — reference ARIZE_API_KEY/ARIZE_SPACE_ID env vars only, set by the user in their own .env/shell; ask before persistent local state (ax profiles, .zshrc, env vars) — see references/ax-profiles.md.

Phase 1: Analysis (read-only — no code/files)

Detect from manifests + imports: language, package manager, LLM providers, frameworks, existing tracing (TracerProvider, register(), ARIZE_*/OTEL_*, Datadog/Honeycomb), and whether the app runs tools / an agent loop (manual CHAIN/TOOL spans only if the matched framework instrumentor doesn't already cover them — decided in Phase 2). Confirm scope first — a monorepo, multiple services, or multiple frameworks needs a "which one?" question before touching anything; don't pick for the user.

Output a short summary (stack, proposed integration, existing tracing, scope). If the target is clear and the user asked to instrument now, continue; if ambiguous or analysis-only was requested, stop and confirm.

Phase 2: Implementation (after the target is confirmed)

1. Fetch the matched integration doc and follow its install + wiring verbatim.
2. Install with the detected package manager, before writing code — exact packages come from the matched doc. Python base: arize-otel (latest 0.13.0, verify on PyPI) + openinference-instrumentation-{name} (package hyphens, import underscores). TS/JS: @opentelemetry/sdk-trace-node + the matched @arizeai/openinference-* (or a first-party exporter, e.g. Mastra's @mastra/arize). Go has no integration doc — see references/go.md for install, wiring, flush, and manual spans.
3. Credentials — app needs an API key + Space. Inspect only the target app's own config; never scan sibling repos/shell files, surface secrets, or accept a pasted key. See references/credentials-and-config.md and references/ax-profiles.md.
4. Centralize init in one module, before any LLM client is created. Existing OTel → add Arize as an additional exporter; don't replace it.

Auto vs manual: prefer the auto-instrumentor — do not hand-roll spans it already covers (duplicates spans, drifts from semconv). Add manual spans only for logic no instrumentor sees, or when the stack has no instrumentor at all. The OpenAI and Anthropic SDK instrumentors capture the LLM call — including the model's tool-call request (name + args) — but NOT the tool's execution, its return value, or the agent/chain boundary. A raw-SDK app with its own tool-calling loop MUST add a TOOL span per execution (to capture the result) and a CHAIN (or AGENT) span to group the turn, or those never appear — do this with @tracer.tool/@tracer.chain decorators wherever the functions exist (they set kind, metadata, and status automatically); hand-roll spans only where no decoratable function does. Framework instrumentors (LangChain/LangGraph/OpenAI Agents SDK) typically cover tools and chains — verify in the matched doc before skipping manual spans. Keep register()/arize-otel-go for setup; see references/manual-spans.md and manual instrumentation.

Cross-cutting (every stack):

• Project name is required — missing it → HTTP 500 (service.name alone fails). Set as a resource attribute: Python register(project_name=…); TS SEMRESATTRS_PROJECT_NAME/model_id; Go Options{ProjectName} or openinference.project.name.
• Don't hand-roll a TracerProvider/exporter — use register()/arize-otel-go; raw OTel only when integrating an existing provider.
• Order: register tracer → instrumentors → clients.
• Prefer @tracer.* decorators over hand-rolled spans — they set kind, input.value/output.value, full TOOL metadata, and terminal status automatically, so they can't emit the UNSET/incomplete spans hand-rolled ones do. The decorator is on the function definition, so dynamic dispatch is no reason to hand-roll. See references/manual-spans.md.
• A hand-rolled span must set, before exit: openinference.span.kind, input.value/output.value, and for a TOOL span all of tool.name/tool.description/tool.parameters. Most-missed line: start_as_current_span records a raised exception as ERROR but never sets OK — so add span.set_status(Status(StatusCode.OK)) on the success path or the span exports UNSET and fails scoring. See references/manual-spans.md.
• Flush before exit (CLI/scripts/notebooks) or async exports drop: Python force_flush()+shutdown(), TS shutdown(), Go defer tp.Shutdown(ctx) (never log.Fatalf/os.Exit mid-span). See references/session-tracking.md.
• Sessions: for obvious multi-turn interactions (e.g. a multi-turn chatbot) or when the user asks, add session.id so turns group into one conversation — see references/session-tracking.md.
• Never silently override the app's project/space/IDs/endpoint — surface mismatches.

Verification

Done only when: app builds/typechecks, starts with tracing, emits ≥1 real request, and you confirm the trace in Arize or give a precise app-vs-Arize blocker. Trigger an LLM call, then use the arize-trace skill to confirm spans (kind, input.value/output.value, parent-child; CHAIN+TOOL if tools run). No traces → check ARIZE_SPACE_ID/ARIZE_API_KEY, init order, otlp.arize.com:443, exporter logs (GRPC_VERBOSITY=debug); common causes: missing project name (500), unflushed short-lived process, or export/verify credential-context mismatch (report it, don't rewrite config — references/credentials-and-config.md). For the deterministic trace-lookup sequence, blocker classification, and the post-arrival smoke check, follow references/verification.md.

After a confirmed trace

Emit milestones (install → wiring → run → export → verify); mark recovered errors resolved; end separating done from blockers. Then briefly offer the next step: arize-trace (inspect/debug), arize-dataset (curate), arize-evaluator (evals), arize-experiment (compare), arize-prompt-optimization (improve prompt). Quality issues → arize-trace first.

References

integration-routing (the router) · credentials-and-config · ax-profiles · manual-spans · go (Go — no doc page exists) · session-tracking · verification · tracing-assistant-mcp.