> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-claude-llms-txt-2026-08-12.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup OTEL

> Configure OpenTelemetry tracing with Phoenix-aware defaults

The Phoenix OTEL SDK provides a lightweight wrapper around OpenTelemetry with sensible defaults for Phoenix.

<Note>
  **Go users:** Phoenix does not ship a branded `phoenix-otel` SDK wrapper for Go. Configure the standard [OpenTelemetry Go SDK](https://opentelemetry.io/docs/languages/go/) directly and point an OTLP/HTTP exporter at Phoenix. End-to-end examples live in the Go integration pages — [OpenAI Go SDK](/docs/phoenix/integrations/llm-providers/openai/openai-go-sdk), [Anthropic SDK Go](/docs/phoenix/integrations/llm-providers/anthropic/anthropic-sdk-go), and [Gemini Go SDK](/docs/phoenix/integrations/llm-providers/google-gen-ai/gemini-go-sdk).
</Note>

## Install

<Tabs>
  <Tab title="Python" icon="python">
    ```bash theme={null}
    pip install "arize-phoenix-otel>=0.16.0"
    ```

    <Note>
      Version **0.16.0** or later is required to import OpenInference context managers and semantic conventions directly from `phoenix.otel`. On earlier versions, import them from `openinference.instrumentation` and `openinference.semconv.trace` instead.
    </Note>
  </Tab>

  <Tab title="TypeScript" icon="js">
    ```bash theme={null}
    npm install @arizeai/phoenix-otel
    ```
  </Tab>
</Tabs>

<Note>
  **Do I need to match the SDK version to my Phoenix server version?** No. `arize-phoenix-otel` (and `@arizeai/phoenix-otel`) are versioned independently of the Phoenix server. Any recent SDK version works with any Phoenix server version — you don't need to upgrade the server when you upgrade the SDK, or vice versa. The SDK sends traces over OTLP using [OpenInference semantic conventions](/docs/phoenix/tracing/concepts-tracing/otel-openinference), both of which are backward compatible, so there is no version pairing to track. See [The phoenix.otel helpers](/docs/phoenix/tracing/concepts-tracing/otel-openinference/phoenix-otel-helpers#version-compatibility) for why.
</Note>

## Configure

Set environment variables to connect to your Phoenix instance:

```bash theme={null}
export PHOENIX_API_KEY="your-api-key"

# Local (default, no API key required)
export PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"

# A remote Phoenix deployment
# export PHOENIX_COLLECTOR_ENDPOINT="https://your-phoenix.example.com"

# Self-hosted
# export PHOENIX_COLLECTOR_ENDPOINT="https://your-phoenix-instance.com"
```

<Tip>
  You can find your collector endpoint and API key in the **Settings** page of your Phoenix instance.
</Tip>

## Register

Call `register()` to initialize tracing. The SDK automatically reads your environment variables.

For manual instrumentation, `arize-phoenix-otel` (>=0.16.0) and `@arizeai/phoenix-otel` re-export all commonly used OpenInference helpers so a single dependency is sufficient:

* **Python**: context managers (`using_session`, `using_user`, `using_metadata`, `using_tags`, `using_attributes`, `using_prompt_template`, `suppress_tracing`) and semantic conventions (`SpanAttributes`, `OpenInferenceSpanKindValues`, `OpenInferenceMimeTypeValues`).
* **TypeScript**: `withSpan`, `traceChain`, `traceAgent`, `traceTool`, `observe`, and context setters like `setSession` and `setMetadata`.

<Tabs>
  <Tab title="Python" icon="python">
    ```python theme={null}
    from phoenix.otel import register

    tracer_provider = register(
        project_name="my-llm-app",
        auto_instrument=True,  # automatically instruments OpenAI, LangChain, etc.
    )
    ```

    <Accordion title="Configuration options">
      | Parameter         | Description                                                 |
      | ----------------- | ----------------------------------------------------------- |
      | `project_name`    | Project name in Phoenix (or `PHOENIX_PROJECT_NAME` env var) |
      | `auto_instrument` | Automatically instrument all supported libraries            |
      | `batch`           | Process spans in batch (default: `False`)                   |
      | `endpoint`        | Custom collector endpoint URL                               |
      | `protocol`        | Transport protocol: `"grpc"` or `"http/protobuf"`           |
      | `headers`         | Headers to send with each span payload                      |
    </Accordion>
  </Tab>

  <Tab title="TypeScript" icon="js">
    ```typescript theme={null}
    import { register } from "@arizeai/phoenix-otel";

    register({ projectName: "my-llm-app" });
    ```

    <Accordion title="Configuration options">
      | Parameter          | Type                     | Default                   | Description                                         |
      | ------------------ | ------------------------ | ------------------------- | --------------------------------------------------- |
      | `projectName`      | `string`                 | `"default"`               | Project name in Phoenix                             |
      | `url`              | `string`                 | `"http://localhost:6006"` | Phoenix server URL                                  |
      | `apiKey`           | `string`                 | —                         | API key for authentication                          |
      | `batch`            | `boolean`                | `true`                    | Use batch span processing                           |
      | `headers`          | `Record<string, string>` | `{}`                      | Custom headers for OTLP requests                    |
      | `instrumentations` | `Instrumentation[]`      | —                         | Instrumentations to register                        |
      | `global`           | `boolean`                | `true`                    | Register as the global tracer provider              |
      | `spanProcessors`   | `SpanProcessor[]`        | —                         | Custom span processors (overrides default exporter) |
      | `diagLogLevel`     | `DiagLogLevel`           | —                         | Enable diagnostic logging                           |
    </Accordion>
  </Tab>
</Tabs>

## Instrument

Add instrumentation to capture traces from your LLM calls:

<Tabs>
  <Tab title="Python" icon="python">
    With `auto_instrument=True`, Phoenix automatically discovers and activates **all** OpenInference instrumentor packages installed in your Python environment—no additional code required.

    ```bash theme={null}
    # Install instrumentors for your frameworks
    pip install openinference-instrumentation-openai
    pip install openinference-instrumentation-langchain
    # ... any other OpenInference packages you need
    ```

    <Tip>
      Just `pip install` the instrumentation packages you need and set `auto_instrument=True`. Phoenix handles the rest.
    </Tip>

    See [Integrations](/docs/phoenix/integrations) for all available packages, or use [Tracing Helpers](/docs/phoenix/tracing/how-to-tracing/setup-tracing/instrument) for manual instrumentation.
  </Tab>

  <Tab title="TypeScript" icon="js">
    Install and register instrumentations for your framework:

    ```bash theme={null}
    npm install @arizeai/openinference-instrumentation-openai
    ```

    ```typescript theme={null}
    import OpenAI from "openai";
    import { register, registerInstrumentations } from "@arizeai/phoenix-otel";
    import { OpenAIInstrumentation } from "@arizeai/openinference-instrumentation-openai";

    register({ projectName: "my-llm-app" });

    const instrumentation = new OpenAIInstrumentation();
    instrumentation.manuallyInstrument(OpenAI);

    registerInstrumentations({
      instrumentations: [instrumentation],
    });
    ```

    <Info>
      ESM projects require calling `manuallyInstrument()` on the client class. CommonJS projects can skip this step.
    </Info>

    <Tip>
      For manual spans, import the helpers from `@arizeai/phoenix-otel`. Phoenix's wrappers resolve the active global tracer when they execute, so the same traced function keeps working inside experiment runs and other provider swaps.
    </Tip>

    See [Integrations](/docs/phoenix/integrations) for all available packages.
  </Tab>
</Tabs>

***

<Note>
  Spans may not be exported if still queued in the processor when your process exits. With `batch: true`, call `shutdown()` to explicitly flush before exit. Alternatively, use `batch: false` for immediate export.
</Note>

***

## Advanced Configuration

For more control over tracing behavior, see the SDK reference documentation:

<CardGroup cols={2}>
  <Card title="Python arize-phoenix-otel" icon="python" href="/docs/phoenix/sdk-api-reference/python/arize-phoenix-otel">
    Batch processing, custom endpoints, gRPC/HTTP transport, sampling, and OTel primitives
  </Card>

  <Card title="TypeScript @arizeai/phoenix-otel" icon="js" href="/docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-otel">
    Diagnostic logging, custom headers, and full API reference
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="puzzle-piece" href="/docs/phoenix/integrations">
    Browse auto-instrumentation packages
  </Card>

  <Card title="Tracing Helpers" icon="at" href="/docs/phoenix/tracing/how-to-tracing/setup-tracing/instrument">
    Manual instrumentation with decorators
  </Card>
</CardGroup>