Setup using Phoenix OTEL

Phoenix OTEL provides a lightweight, vendor-agnostic way to instrument your services using OpenTelemetry and stream traces directly into Phoenix for debugging, monitoring, and model evaluation. This guide walks you through configuring your application to emit OTEL-compatible spans, enabling end-to-end visibility into requests, model calls, and system behavior with minimal overhead.

Getting Started

To begin sending traces to Phoenix using OpenTelemetry, install the Phoenix OTEL packages for your environment and configure a basic tracer. Below are quick-start examples for both Python and TypeScript users

Python

phoenix.otel is a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults.

pip install arize-phoenix-otel

These defaults are aware of environment variables you may have set to configure Phoenix:

• PHOENIX_COLLECTOR_ENDPOINT

• PHOENIX_PROJECT_NAME

• PHOENIX_CLIENT_HEADERS

• PHOENIX_API_KEY

• PHOENIX_GRPC_PORT

TS

Configure your Environment

There are two ways to configure the collector endpoint:

• Using environment variables

• Using the endpoint keyword argument

If you're using Phoenix Cloud, you'll need your API Key & your space endpoint. If you're running Phoenix locally, you'll just need your endpoint. (ex. localhost:6006)

Create your OTEL tracer

Once the Phoenix OTEL packages are installed, initialize a tracer so your spans can be collected and viewed in Phoenix.

Python

The phoenix.otel module provides a high-level register function to configure OpenTelemetry tracing by setting a global TracerProvider. The register function can also configure headers and whether or not to process spans one by one or by batch.

from phoenix.otel import register
tracer_provider = register(
    project_name="default", # sets a project name for spans
    batch=True, # uses a batch span processor
    auto_instrument=True, # uses all installed OpenInference instrumentors
    # optional: if you want to configure custom endpoint
    # endpoint="http://localhost:6006/v1/traces"
    # protocol="grpc", # use "http/protobuf" for http transport
)

If the PHOENIX_API_KEY environment variable is set, register will automatically add an authorization header to each span payload.

If you're setting the PHOENIX_COLLECTOR_ENDPOINT environment variable, register will automatically try to send spans to your Phoenix server using gRPC.

register can be configured with different keyword arguments:

• project_name: The Phoenix project name

  • or use PHOENIX_PROJECT_NAME env. var

• headers: Headers to send along with each span payload

  • or use PHOENIX_CLIENT_HEADERS env. var

• batch: Whether or not to process spans in batch

TS

Configuring the collector endpoint

When passing in the endpoint argument, you must specify the fully qualified endpoint. If the PHOENIX_GRPC_PORT environment variable is set, it will override the default gRPC port.

For default, the local endpoint will be localhost:6006 or your space's hostname when using Pheonix Cloud.

When passing in the endpoint argument, you must specify the fully qualified endpoint. If the PHOENIX_GRPC_PORT environment variable is set, it will override the default gRPC port.

HTTP

The HTTP transport protocol is inferred from the endpoint

from phoenix.otel import register
tracer_provider = register(endpoint="http://localhost:6006/v1/traces")

GRPC

Custom GRPC Port

Instrumentation

Once you've connected your application to your Phoenix instance using phoenix.otel.register, you need to instrument your application. You have a few options to do this:

1. Using OpenInference auto-instrumentors. If you've used the auto_instrument flag above, then any instrumentor packages in your environment will be called automatically. For a full list of OpenInference packages, see https://arize.com/docs/phoenix/integrations

2. Using Phoenix Decorators.

3. Using Base OTEL.