> ## Documentation Index > Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # PROMPT # Arize AX Tracing — Agent Setup Prompt You are helping a developer add **Arize AX tracing** to their application. Follow the two-phase approach below: first analyze, then implement. ## 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 * **Never hand-roll OpenTelemetry** — always configure the exporter via `arize-otel` (Python), `arize-otel-go` (Go), or the documented OpenInference setup (TS/Java). Do not construct a raw `TracerProvider` + OTLP exporter from scratch when a helper exists; that is the most common setup mistake. * **Pin packages correctly** — `arize-otel` (the Python tracing helper) is a **separate package on its own `0.x` line**; it is *not* the `arize` platform SDK (which is `7.x`/`8.x`). Install `arize-otel` unpinned (`pip install arize-otel`) and **never** pin it to a `7.x`/`8.x` version — those releases do not exist and the install will fail. The two are different packages with independent version lines. The OpenInference instrumentors (`openinference-instrumentation-*` / `@arizeai/openinference-*`) are also pre-`1.0`: install them unpinned too and never invent a version constraint (e.g. `openinference-instrumentation-langchain>=0.2.0`) — a guessed pin will fail to resolve and abort the install. * **Follow existing code style** and project conventions * **Keep output concise and production-focused** — do not generate extra documentation or summary files ### Reference links * **Arize AX Docs:** [https://arize.com/docs/ax](https://arize.com/docs/ax) * **Full integration list:** [https://arize.com/docs/ax/integrations](https://arize.com/docs/ax/integrations) * **llms.txt (doc discovery):** [https://arize.com/docs/llms.txt](https://arize.com/docs/llms.txt) — use this as a fallback if a routing table URL is unavailable or returns an error *** ## PHASE 1: ANALYSIS (read-only) Scan the codebase and identify the developer's stack. **Do not write any code or create any files during this phase.** ### How to scan 1. **Check dependency manifests first** — these are the most reliable signals: * Python: `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile` * TypeScript/JavaScript: `package.json` * Java: `pom.xml`, `build.gradle`, `build.gradle.kts` * Go: `go.mod` 2. **Then scan import statements** in source files to confirm what's actually used. 3. **Check for existing tracing/OTel setup** — look for: * `TracerProvider`, `register()`, `opentelemetry` imports * Environment variables: `ARIZE_*`, `OTEL_*`, `OTLP_*` * Config files for other observability vendors (Datadog, Honeycomb, New Relic, etc.) 4. **Identify the scope** — for monorepos or multi-service projects, ask the user which service(s) to instrument rather than guessing. ### What to identify 1. **Language** — Python, TypeScript/JavaScript, Java, or Go 2. **Package manager** — pip/poetry/uv, npm/pnpm/yarn, maven/gradle, go modules 3. **LLM providers** — match against the LLM Providers table below 4. **Frameworks** — match against the Agent Frameworks / Platforms tables below. **For version-sensitive frameworks, record the resolved major version, not just the package name** — some frameworks split their tracing setup by major version (notably the **Vercel AI SDK**: the `ai` major decides between the v6 and v7 pages). Resolve the actual installed major from the lockfile when `package.json` only gives a range. 5. **Existing tracing** — any pre-existing OTel or observability setup (see guidance below) ### Key rule > **When a framework is detected alongside an LLM provider, instrument both.** The framework instrumentor does not trace the underlying LLM calls — you need the provider instrumentor too. ### Phase 1 output Return a concise summary: * Detected language, package manager, providers, frameworks * Proposed integration list (matched from the routing table below) * Any existing OTel/tracing setup that needs consideration * If monorepo: which service(s) you propose to instrument **STOP. Present your analysis and wait for user confirmation before proceeding to Phase 2.** *** ## INTEGRATION ROUTING TABLE This is the **canonical list** of supported integrations. Use these tables to map detected signals to documentation URLs. Fetch the matched doc pages for implementation details. ### LLM Providers | Detection signal | Integration | Doc URL | | --------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openai` | OpenAI | [https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing](https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing) | | `prismml` or an OpenAI client with base\_url `localhost:8080/v1` | PrismML | [https://arize.com/docs/ax/integrations/llm-providers/prismml/prismml-tracing](https://arize.com/docs/ax/integrations/llm-providers/prismml/prismml-tracing) | | `anthropic` | Anthropic | [https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing](https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing) | | `google.generativeai` or `@google/generative-ai` | Google | [https://arize.com/docs/ax/integrations/llm-providers/google-gen-ai/google-genai-tracing](https://arize.com/docs/ax/integrations/llm-providers/google-gen-ai/google-genai-tracing) | | `groq` | Groq | [https://arize.com/docs/ax/integrations/llm-providers/groq/groq-tracing](https://arize.com/docs/ax/integrations/llm-providers/groq/groq-tracing) | | `boto3` + `bedrock` | Amazon Bedrock | [https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-tracing](https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-tracing) | | `litellm` | LiteLLM | [https://arize.com/docs/ax/integrations/llm-providers/litellm/litellm-tracing](https://arize.com/docs/ax/integrations/llm-providers/litellm/litellm-tracing) | | `ollama` | Ollama | [https://arize.com/docs/ax/integrations/llm-providers/llama/ollama-tracing](https://arize.com/docs/ax/integrations/llm-providers/llama/ollama-tracing) | | `mistralai` | MistralAI | [https://arize.com/docs/ax/integrations/llm-providers/mistralai/mistralai-tracing](https://arize.com/docs/ax/integrations/llm-providers/mistralai/mistralai-tracing) | | `openrouter` | OpenRouter | [https://arize.com/docs/ax/integrations/llm-providers/openrouter/openrouter-tracing](https://arize.com/docs/ax/integrations/llm-providers/openrouter/openrouter-tracing) | | `vertexai` or `google.cloud.aiplatform` | VertexAI | [https://arize.com/docs/ax/integrations/llm-providers/vertexai/vertexai-tracing](https://arize.com/docs/ax/integrations/llm-providers/vertexai/vertexai-tracing) | | `orcarouter` (or an OpenAI client with base\_url `api.orcarouter.ai`) | OrcaRouter | [https://arize.com/docs/ax/integrations/llm-providers/orcarouter/orcarouter-tracing](https://arize.com/docs/ax/integrations/llm-providers/orcarouter/orcarouter-tracing) | | `truefoundry` (or an OpenAI client with a TrueFoundry `base_url`) | TrueFoundry | [https://arize.com/docs/ax/integrations/llm-providers/truefoundry/truefoundry-tracing](https://arize.com/docs/ax/integrations/llm-providers/truefoundry/truefoundry-tracing) | | `doubleword` (or an OpenAI client with a Doubleword `base_url`) | Doubleword | [https://arize.com/docs/ax/integrations/llm-providers/doubleword/doubleword-tracing](https://arize.com/docs/ax/integrations/llm-providers/doubleword/doubleword-tracing) | > **Note:** The Ollama doc URL slug is `/llama`, not `/ollama`. This is intentional. ### Python Agent Frameworks | Detection signal | Integration | Doc URL | | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `langchain` | LangChain | [https://arize.com/docs/ax/integrations/python-agent-frameworks/langchain/langchain-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/langchain/langchain-tracing) | | `langgraph` | LangGraph | [https://arize.com/docs/ax/integrations/python-agent-frameworks/langgraph/langgraph-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/langgraph/langgraph-tracing) | | `llama_index` | LlamaIndex | [https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-tracing) | | `crewai` | CrewAI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/crewai/crewai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/crewai/crewai-tracing) | | `dspy` | DSPy | [https://arize.com/docs/ax/integrations/python-agent-frameworks/dspy/dspy-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/dspy/dspy-tracing) | | `autogen` | AutoGen | [https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-tracing) | | `autogen_agentchat` | AutoGen AgentChat | [https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-agentchat-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-agentchat-tracing) | | `semantic_kernel` | Semantic Kernel | [https://arize.com/docs/ax/integrations/python-agent-frameworks/semantic-kernel/semantic-kernel-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/semantic-kernel/semantic-kernel-tracing) | | `pydantic_ai` | Pydantic AI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/pydantic/pydantic-ai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/pydantic/pydantic-ai-tracing) | | `haystack` | Haystack | [https://arize.com/docs/ax/integrations/python-agent-frameworks/haystack/haystack-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/haystack/haystack-tracing) | | `guardrails` | Guardrails AI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/guardrails-ai/guardrails-ai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/guardrails-ai/guardrails-ai-tracing) | | `smolagents` | Hugging Face Smolagents | [https://arize.com/docs/ax/integrations/python-agent-frameworks/hugging-face-smolagents/smolagents-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/hugging-face-smolagents/smolagents-tracing) | | `instructor` | Instructor | [https://arize.com/docs/ax/integrations/python-agent-frameworks/instructor/instructor-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/instructor/instructor-tracing) | | `agno` | Agno | [https://arize.com/docs/ax/integrations/python-agent-frameworks/agno/agno-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/agno/agno-tracing) | | `google.adk` or `google_adk` | Google ADK | [https://arize.com/docs/ax/integrations/python-agent-frameworks/google-adk/google-adk-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/google-adk/google-adk-tracing) | | `agents` (the `openai-agents` package) | OpenAI Agents SDK | [https://arize.com/docs/ax/integrations/python-agent-frameworks/openai-agents/openai-agents-sdk-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/openai-agents/openai-agents-sdk-tracing) | | `mcp` or `modelcontextprotocol` | Model Context Protocol | [https://arize.com/docs/ax/integrations/python-agent-frameworks/model-context-protocol/mcp-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/model-context-protocol/mcp-tracing) | | `portkey` | Portkey | [https://arize.com/docs/ax/integrations/python-agent-frameworks/portkey/portkey-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/portkey/portkey-tracing) | | `together` | Together AI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/together-ai/together-ai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/together-ai/together-ai-tracing) | | `beeai` | BeeAI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/beeai/beeai-tracing-python](https://arize.com/docs/ax/integrations/python-agent-frameworks/beeai/beeai-tracing-python) | | `strands` (the `strands-agents` package) | AWS Strands Agents | [https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/aws-strands-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/aws-strands-tracing) | | `bedrock-agentcore` or `bedrock-agentcore-starter-toolkit` (a Strands/CrewAI/LangGraph/etc. agent deployed on AWS Bedrock AgentCore Runtime) | AWS Bedrock AgentCore | [https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/bedrock-agentcore](https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/bedrock-agentcore) | | `claude_agent_sdk` (the `claude-agent-sdk` package) | Claude Agent SDK | [https://arize.com/docs/ax/integrations/python-agent-frameworks/claude-agent-sdk/claude-agent-sdk-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/claude-agent-sdk/claude-agent-sdk-tracing) | | `agent_framework` (the `agent-framework` package) | Microsoft Agent Framework | [https://arize.com/docs/ax/integrations/python-agent-frameworks/microsoft/microsoft-agent-framework](https://arize.com/docs/ax/integrations/python-agent-frameworks/microsoft/microsoft-agent-framework) | | `nat` (the `nvidia-nat` package) | NVIDIA NeMo Agent Toolkit | [https://arize.com/docs/ax/integrations/python-agent-frameworks/nvidia/nemo-agent-toolkit-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/nvidia/nemo-agent-toolkit-tracing) | | `pipecat` | Pipecat | [https://arize.com/docs/ax/integrations/python-agent-frameworks/pipecat/pipecat-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/pipecat/pipecat-tracing) | | `pyagentspec` (Oracle Open Agent Spec) | Open Agent Spec | [https://arize.com/docs/ax/integrations/python-agent-frameworks/agentspec/agentspec-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/agentspec/agentspec-tracing) | | `boto3` + `bedrock-agent` | AWS Bedrock Agents | [https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-agents-tracing](https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-agents-tracing) | > **Note:** LlamaIndex Workflows use the **same instrumentor** as core LlamaIndex. If you detect `llama_index`, the LlamaIndex row already covers workflows — no extra instrumentation is needed. When the app uses Workflows specifically (`from llama_index.core.workflow import Workflow, step`, or the `@step` decorator), also point the user to the workflow-focused guide: [https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-workflows-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-workflows-tracing) ### TypeScript/JavaScript Frameworks | Detection signal | Integration | Doc URL | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `langchain` or `@langchain/core` (in `package.json`) | LangChain JS | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/langchain/langchain-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/langchain/langchain-js) | | `@mastra/core` (in `package.json`) | Mastra | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/mastra/mastra-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/mastra/mastra-tracing) | | `ai` major is **7** (`ai@^7` / `ai@7.x` in `package.json` or lockfile) — even if `@ai-sdk/otel` is absent | Vercel AI SDK v7 | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v7-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v7-tracing) | | `ai` major is **6 or earlier** (`ai@^6`, `3.3`–`6.x` in `package.json` — corroborated by `import { ... } from 'ai'` in source) | Vercel AI SDK (v6 and earlier) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v6-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v6-tracing) | | `eve` (in `package.json`, or an `eve/instrumentation` import) | Vercel Eve | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/eve-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/eve-tracing) | | `@openai/agents` (in `package.json`) | OpenAI Agents (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/openai-agents/openai-agents-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/openai-agents/openai-agents-js) | | `@tanstack/ai` (in `package.json`) | TanStack AI | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/tanstack/tanstack-ai-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/tanstack/tanstack-ai-tracing) | | `@i-am-bee` (in `package.json`) | BeeAI JS | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/beeai/beeai-tracing-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/beeai/beeai-tracing-js) | | `@aws-sdk/client-bedrock-agent-runtime` (in `package.json`) | Amazon Bedrock Agents (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/amazon-bedrock/amazon-bedrock-agents-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/amazon-bedrock/amazon-bedrock-agents-js) | | `@modelcontextprotocol/sdk` (in `package.json`) | MCP (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/model-context-protocol/mcp-tracing-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/model-context-protocol/mcp-tracing-js) | > **Note:** Vercel AI SDK v6 and v7 wire telemetry differently and are **not** interchangeable — v6 emits OpenTelemetry spans natively; v7 requires the `@ai-sdk/otel` integration. **Route by the `ai` major version only.** `@ai-sdk/otel` is installed *during* setup — it is **not** a detection signal, and a not-yet-instrumented v7 app won't have it, so never gate the v7 page on its presence. If `package.json` only gives a range (`^7`, `>=7`), read the resolved major from `package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`, or ask the user; **do not default to the v6 page.** The v6 setup produces **zero spans** on `ai@7`, and the v7 setup produces zero spans on `ai@6`. ### Java | Detection signal | Integration | Doc URL | | ----------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `langchain4j` (in `pom.xml` or `build.gradle`) | LangChain4j | [https://arize.com/docs/ax/integrations/java/langchain4j/langchain4j-tracing](https://arize.com/docs/ax/integrations/java/langchain4j/langchain4j-tracing) | | `spring-ai` (in `pom.xml` or `build.gradle`) | Spring AI | [https://arize.com/docs/ax/integrations/java/spring-ai/spring-ai-tracing](https://arize.com/docs/ax/integrations/java/spring-ai/spring-ai-tracing) | | `arconia` (in `pom.xml` or `build.gradle`) | Arconia | [https://arize.com/docs/ax/integrations/java/arconia/arconia-tracing](https://arize.com/docs/ax/integrations/java/arconia/arconia-tracing) | | Hand-built Java agent/pipeline with no matched framework (annotate methods with `@Chain`/`@LLM`/`@Tool`/`@Agent`) | Annotations | [https://arize.com/docs/ax/integrations/java/annotation/annotation-tracing](https://arize.com/docs/ax/integrations/java/annotation/annotation-tracing) | ### Go Requires **Go 1.25+** (floor of the OpenInference Go modules; `arize-otel-go` itself is Go 1.23+). Wire tracing with [`arize-otel-go`](https://github.com/Arize-ai/arize-otel-go) and attach a per-provider auto-instrumentor when one exists, or set OpenInference attributes manually for clients that don't. | Detection signal | Integration | Doc URL | | ---------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `github.com/openai/openai-go` in `go.mod` | OpenAI (auto) | [https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing](https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing) | | `github.com/anthropics/anthropic-sdk-go` in `go.mod` | Anthropic (auto) | [https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing](https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing) | | `go.mod` present, no matched provider | Manual OTel + OpenInference | [https://arize.com/docs/ax/instrument/manual-instrumentation](https://arize.com/docs/ax/instrument/manual-instrumentation) | ### Platforms These are UI-based platforms, not code libraries. They cannot be auto-detected from imports. If the user mentions using one, or you find platform-specific config files (e.g., Docker Compose references, deployment manifests), match them here: | Platform | Doc URL | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | LangFlow | [https://arize.com/docs/ax/integrations/platforms/langflow/langflow-tracing](https://arize.com/docs/ax/integrations/platforms/langflow/langflow-tracing) | | Flowise | [https://arize.com/docs/ax/integrations/platforms/flowise/flowise-tracing](https://arize.com/docs/ax/integrations/platforms/flowise/flowise-tracing) | | Dify | [https://arize.com/docs/ax/integrations/platforms/dify/dify-tracing](https://arize.com/docs/ax/integrations/platforms/dify/dify-tracing) | | Prompt flow | [https://arize.com/docs/ax/integrations/platforms/prompt-flow/prompt-flow-tracing](https://arize.com/docs/ax/integrations/platforms/prompt-flow/prompt-flow-tracing) | ### Fallback If no integration matches, or for advanced use cases: * **Manual instrumentation:** [https://arize.com/docs/ax/instrument/manual-instrumentation](https://arize.com/docs/ax/instrument/manual-instrumentation) * **All integrations:** [https://arize.com/docs/ax/integrations](https://arize.com/docs/ax/integrations) *** ## PHASE 2: IMPLEMENTATION After the user confirms your Phase 1 analysis, implement tracing. ### 1. Fetch integration docs Read the matched doc URLs from the routing table above. Follow the installation and instrumentation steps from those pages. ### 2. Install packages Install the required packages using the detected package manager **before** writing any code. * **Python:** `pip install arize-otel` plus instrumentors (see naming convention below) * **TypeScript/JavaScript:** `npm install @opentelemetry/sdk-trace-node` plus the relevant `@arizeai/openinference-*` package * **Java:** Add OpenTelemetry SDK and the relevant `openinference-instrumentation-*` dependency to `pom.xml` or `build.gradle` * **Go:** core packages, then exactly one provider instrumentor matched to the detected SDK: ``` go get \ github.com/Arize-ai/arize-otel-go \ github.com/Arize-ai/openinference/go/openinference-instrumentation \ github.com/Arize-ai/openinference/go/openinference-semantic-conventions # plus one of: go get github.com/Arize-ai/openinference/go/openinference-instrumentation-openai-go # openai/openai-go go get github.com/Arize-ai/openinference/go/openinference-instrumentation-anthropic-sdk-go # anthropics/anthropic-sdk-go ``` ### 3. Get credentials The user needs their **Arize Space ID** and **API Key** from: [https://app.arize.com/organizations/-/settings/space-api-keys](https://app.arize.com/organizations/-/settings/space-api-keys) Set as environment variables: ```bash theme={null} ARIZE_SPACE_ID= ARIZE_API_KEY= ``` ### 4. Core setup patterns Create a **single centralized instrumentation module** (e.g., `instrumentation.py`, `instrumentation.ts`). Initialize tracing **before** any LLM client is created. #### Python The universal Python pattern uses `arize-otel` to configure OpenTelemetry: ```python theme={null} from arize.otel import register tracer_provider = register( space_id="YOUR_SPACE_ID", # or os.environ["ARIZE_SPACE_ID"] api_key="YOUR_API_KEY", # or os.environ["ARIZE_API_KEY"] project_name="your-project-name", ) ``` Then attach instrumentors for each detected integration: ```python theme={null} from openinference.instrumentation.openai import OpenAIInstrumentor OpenAIInstrumentor().instrument(tracer_provider=tracer_provider) ``` ##### Python instrumentor naming convention Instrumentor packages follow a predictable pattern: | | Pattern | Example (OpenAI) | Example (LlamaIndex) | | --------------- | -------------------------------------- | -------------------------------------- | ------------------------------------------- | | **pip package** | `openinference-instrumentation-{name}` | `openinference-instrumentation-openai` | `openinference-instrumentation-llama-index` | | **Import** | `openinference.instrumentation.{name}` | `openinference.instrumentation.openai` | `openinference.instrumentation.llama_index` | | **Class** | `{Name}Instrumentor` | `OpenAIInstrumentor` | `LlamaIndexInstrumentor` | > **Note:** pip package names use hyphens; Python module names use underscores. For multi-word names (e.g., `llama-index` → `llama_index`), convert hyphens to underscores in the import path. > **Exception — span-processor integrations.** A few integrations do **not** ship an `{Name}Instrumentor` and are **not** wired with `register()` + `.instrument()`. Instead they add a reshaping `SpanProcessor` to a manually built `TracerProvider` (because they need the Arize exporter *and* a span reshaper to coexist, which `register()`'s single default processor can't host). Known cases: **Semantic Kernel** (OpenLIT → `OpenInferenceSpanProcessor` + `openlit.init()`), **AWS Strands** (`StrandsAgentsToOpenInferenceProcessor` + `StrandsTelemetry`), and **Microsoft Agent Framework** (`AgentFrameworkToOpenInferenceProcessor` + `enable_instrumentation`). For these, follow the matched doc page's setup verbatim rather than applying the instrumentor convention above. #### TypeScript / JavaScript TS/JS integrations use `@opentelemetry/sdk-trace-node` as the tracing backbone, with a framework-specific `@arizeai/openinference-*` package. The setup varies by framework: **LangChain JS:** ```typescript theme={null} import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"; import { resourceFromAttributes } from "@opentelemetry/resources"; import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"; import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions"; import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions"; import { LangChainInstrumentation } from "@arizeai/openinference-instrumentation-langchain"; import * as CallbackManagerModule from "@langchain/core/callbacks/manager"; const projectName = process.env.ARIZE_PROJECT_NAME ?? "langchain-js-app"; const provider = new NodeTracerProvider({ resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: projectName, [SEMRESATTRS_PROJECT_NAME]: projectName, }), spanProcessors: [ new SimpleSpanProcessor( new OTLPTraceExporter({ url: "https://otlp.arize.com/v1/traces", headers: { "arize-space-id": process.env.ARIZE_SPACE_ID ?? "", "arize-api-key": process.env.ARIZE_API_KEY ?? "", }, }), ), ], }); provider.register(); const lcInstrumentation = new LangChainInstrumentation(); lcInstrumentation.manuallyInstrument(CallbackManagerModule); ``` **Vercel AI SDK:** ```typescript theme={null} import { OpenInferenceSimpleSpanProcessor, isOpenInferenceSpan } from "@arizeai/openinference-vercel"; import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"; import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; const provider = new NodeTracerProvider({ spanProcessors: [ new OpenInferenceSimpleSpanProcessor({ exporter: new OTLPTraceExporter({ url: "https://otlp.arize.com/v1/traces", headers: { "arize-space-id": process.env.ARIZE_SPACE_ID || "", "arize-api-key": process.env.ARIZE_API_KEY || "", }, }), spanFilter: isOpenInferenceSpan, }), ], }); provider.register(); ``` Then enable telemetry at each AI SDK call site: ```typescript theme={null} const result = streamText({ model: openai("gpt-4o"), messages, experimental_telemetry: { isEnabled: true }, }); ``` **Mastra:** Mastra registers tracing through its observability layer using the first-party `@mastra/arize` exporter (`npm install @mastra/arize @mastra/observability @mastra/core`). The `ArizeExporter` reads `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, and `ARIZE_PROJECT_NAME` from the environment. ```typescript theme={null} import { Mastra } from "@mastra/core"; import { Observability } from "@mastra/observability"; import { ArizeExporter } from "@mastra/arize"; export const mastra = new Mastra({ agents: { /* your agents */ }, observability: new Observability({ configs: { arize: { serviceName: process.env.ARIZE_PROJECT_NAME ?? "my-mastra-app", exporters: [new ArizeExporter()], }, }, }), }); ``` For other TS/JS frameworks, fetch the matched doc URL for framework-specific details. The common elements across all TS/JS setups are: * OTLP export endpoint: `https://otlp.arize.com/v1/traces` * Auth headers: `arize-space-id` and `arize-api-key` * All Arize TS/JS packages live under the `@arizeai/openinference-*` npm scope #### Java Java integrations use the OpenTelemetry Java SDK with OTLP/gRPC export. The level of automation varies: **Arconia** (zero-code — recommended for Spring Boot projects): Add dependencies and Arconia auto-configures tracing via its Spring Boot starter. No explicit OTel setup code needed — just set environment variables. **LangChain4j** (one-liner): ```java theme={null} // After OpenTelemetry SDK initialization: LangChain4jInstrumentor.instrument(); // All LangChain4j calls are automatically traced from this point. ``` **Spring AI** (manual wiring): ```java theme={null} OITracer tracer = new OITracer(tracerProvider.get("com.example.springai"), TraceConfig.getDefault()); ObservationRegistry registry = ObservationRegistry.create(); registry.observationConfig().observationHandler(new SpringAIInstrumentor(tracer)); // Pass registry to model builder: OpenAiChatModel model = OpenAiChatModel.builder() .openAiApi(openAiApi) .observationRegistry(registry) .build(); ``` All Java integrations share these OTel SDK initialization fundamentals: ```java theme={null} OtlpGrpcSpanExporter otlpExporter = OtlpGrpcSpanExporter.builder() .setEndpoint("https://otlp.arize.com:443") .setHeaders(() -> Map.of( "authorization", System.getenv("ARIZE_API_KEY"), "arize-space-id", System.getenv("ARIZE_SPACE_ID"), "arize-interface", "java")) .build(); ``` For full setup details, fetch the matched doc URL. #### Go Wire the exporter with [`arize-otel-go`](https://github.com/Arize-ai/arize-otel-go) and attach the per-provider auto-instrumentor for the detected SDK. The `arize-otel-go` `Register` call reads `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, and `ARIZE_PROJECT_NAME` from the environment when the matching `Options` fields are unset, and sets the required `openinference.project.name` resource attribute on the TracerProvider. ```go theme={null} package main import ( "context" "log" "os" "time" arizeotel "github.com/Arize-ai/arize-otel-go" openaiotel "github.com/Arize-ai/openinference/go/openinference-instrumentation-openai-go" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "go.opentelemetry.io/otel" ) func main() { ctx := context.Background() tp, err := arizeotel.Register(ctx, arizeotel.Options{ ProjectName: "your-go-app", }) if err != nil { log.Printf("register tracer: %v", err) return } defer func() { shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() _ = tp.Shutdown(shutdownCtx) }() // Every /v1/chat/completions call emits an LLM span automatically. client := openai.NewClient( option.WithAPIKey(os.Getenv("OPENAI_API_KEY")), option.WithMiddleware(openaiotel.Middleware(otel.Tracer("your-go-app"))), ) _ = client // ... your app ... } ``` For `anthropics/anthropic-sdk-go`, swap the import and middleware: ```go theme={null} import ( "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/option" anthropicotel "github.com/Arize-ai/openinference/go/openinference-instrumentation-anthropic-sdk-go" ) client := anthropic.NewClient( option.WithMiddleware(anthropicotel.Middleware(otel.Tracer("your-go-app"))), ) ``` For clients without an auto-instrumentor, create spans manually with OpenInference [semantic-conventions constants](https://github.com/Arize-ai/openinference/tree/main/go/openinference-semantic-conventions): ```go theme={null} import ( "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/attribute" semconv "github.com/Arize-ai/openinference/go/openinference-semantic-conventions" ) tracer := otel.Tracer("your-go-app") ctx, span := tracer.Start(ctx, "run-agent") defer span.End() span.SetAttributes( attribute.String(semconv.OpenInferenceSpanKind, semconv.SpanKindChain), attribute.String(semconv.InputValue, userInput), attribute.String(semconv.OutputValue, finalReply), ) ``` EU spaces: pass `Endpoint: arizeotel.EndpointArizeEurope` to `arizeotel.Options`. CLI/short-lived processes **must** keep the `defer tp.Shutdown(ctx)` block — and never call `log.Fatalf` or `os.Exit` after a span has started — or batched spans will be dropped. For full setup details, see [https://arize.com/docs/ax/instrument/manual-instrumentation](https://arize.com/docs/ax/instrument/manual-instrumentation). ### 5. Handling existing OTel / tracing setup If the codebase already has OpenTelemetry or another observability vendor configured: * **Existing `TracerProvider` with no Arize exporter** — add Arize as an additional exporter rather than replacing the existing setup. Use a `BatchSpanProcessor` with the Arize OTLP exporter alongside the existing processors. * **Existing Arize setup** — verify it's configured correctly and update if needed. Do not duplicate. * **Other vendor (Datadog, Honeycomb, etc.)** — inform the user that Arize can run alongside other vendors via additional OTLP exporters, and ask how they'd like to proceed. ### 6. Implementation rules * Use **auto-instrumentation first** — add manual spans only if needed * **Do not build a custom `TracerProvider`/OTLP exporter** — use `register()` (`arize-otel`) or `arize-otel-go`. Only configure raw OTel when explicitly handling an existing provider (see step 5). * **Fail gracefully** if environment variables are missing (warn, don't crash) * Initialize tracing **before** any LLM client is created * Import order matters: register tracer → instrument → create clients *** ## VERIFICATION After implementation: 1. **Run the application** and trigger at least one LLM call 2. **Check Arize UI** at [https://app.arize.com](https://app.arize.com) for traces under your project name 3. **Troubleshooting:** * Verify `ARIZE_SPACE_ID` and `ARIZE_API_KEY` are set correctly * Ensure `register()` / `TracerProvider` initialization is called before instrumentors and client creation * Check network connectivity to `otlp.arize.com:443` * Enable debug logging: set `GRPC_VERBOSITY=debug` environment variable