The previous four pages — Resource, Exporter, Span Processor, and Tracer Provider — walked through the OpenTelemetry tracing components one by one. Wiring them up by hand in every application is verbose. The phoenix.otel SDK collapses all of it into a single function call — and adds a few Phoenix-specific capabilities on top.

For the practical how-to of installing and using these helpers, see Set up tracing. This page covers what they do under the hood.

Appreciate the Simplicity#

Configuring tracing with raw OpenTelemetry — Resource, Exporter, Span Processor, Tracer Provider — looks like this:

from opentelemetry import tracefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessorfrom opentelemetry.sdk.resources import Resourcefrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporterdef init_phoenix_tracing():    resource = Resource.create({        "openinference.project.name": "my-project",    })    otlp_exporter = OTLPSpanExporter(        endpoint="http://localhost:6006/v1/traces",    )    span_processor = BatchSpanProcessor(otlp_exporter)    tracer_provider = TracerProvider(resource=resource)    tracer_provider.add_span_processor(span_processor)    trace.set_tracer_provider(tracer_provider)    return tracer_provider.get_tracer("my-project")

The Phoenix register() helper replaces all of that:

from phoenix.otel import registertracer_provider = register(project_name="my-project")

Same outcome — Resource, Exporter, Span Processor, Tracer Provider all wired up — in much less code.

What `register()` Does Under the Hood#

The convenience function handles four things for you. Each one has additional capabilities specific to OpenInference and Phoenix compared to the standard OTel SDK:

Component returned by `register()`	What it adds beyond standard OTel
Tracer Provider	A Phoenix-aware provider with sensible defaults. Combined with the OpenInference instrumentation libraries, it makes the OpenInference context managers (`using_session`, `using_user`, `using_metadata`, etc.) attach attributes to spans automatically.
Span Processor	Configured and pre-attached. `SimpleSpanProcessor` by default, `BatchSpanProcessor` when you pass `batch=True`.
Span Exporter	Auto-detects gRPC or HTTP from the endpoint URL and configures the matching OTLP exporter. If `api_key` is set, it adds the `Authorization: Bearer <key>` header for you.
Resource	Sets the project name automatically from your `project_name` argument (or the `PHOENIX_PROJECT` environment variable, with `PHOENIX_PROJECT_NAME` accepted as an alias).

Version Compatibility#

arize-phoenix-otel is versioned independently of the Phoenix server, and the two are not coupled — any recent SDK version works with any server version. You do not need to upgrade the server when you upgrade the SDK, or match version numbers between them.

This works because register() never calls a version-gated server endpoint. Everything it wires up rests on two backward-compatible contracts:

OTLP transport — the exporter sends spans over the OpenTelemetry Protocol, which every Phoenix server version accepts.
OpenInference semantic conventions — the attribute names both sides agree on, tracked in the openinference-semantic-conventions package and evolved additively.

Because compatibility rests on these stable layers rather than matched version pairs, there is no arize-phoenix-otel × Phoenix server version table to consult. (Individual features — not the SDK as a whole — may carry a minimum server version; those are noted on the relevant feature pages.)

Auto-instrumentation#

register() has an auto_instrument=True option that automatically calls .instrument() on every OpenInference auto-instrumentor installed in your environment.

from phoenix.otel import registertracer_provider = register(    project_name="my-project",    auto_instrument=True,)

That single call replaces manually doing OpenAIInstrumentor().instrument(...), LangChainInstrumentor().instrument(...), and so on for every installed instrumentor. Just pip install the instrumentors you want active, and auto_instrument=True finds them at runtime.

For the full set of installable instrumentors, see the OpenInference repository.

Configuration#

register() reads from environment variables when arguments aren’t passed:

Argument	Environment variable	Notes
`project_name`	`PHOENIX_PROJECT` (alias `PHOENIX_PROJECT_NAME`)	Name of the project in Phoenix. If both env vars are set, `PHOENIX_PROJECT` wins. Defaults to `"default"`.
`endpoint`	`PHOENIX_COLLECTOR_ENDPOINT`	The collector endpoint. Defaults to `http://localhost:6006`.
`api_key`	`PHOENIX_API_KEY`	Optional for local Phoenix. Required for any instance with authentication enabled — added as a Bearer token header.
`headers`	`PHOENIX_CLIENT_HEADERS`	Additional headers for the OTLP request (e.g. tenant identifiers).

The full signature:

register(    *,    endpoint: Optional[str] = None,    project_name: Optional[str] = None,    batch: bool = False,    set_global_tracer_provider: bool = True,    headers: Optional[Dict[str, str]] = None,    protocol: Optional[Literal["http/protobuf", "grpc"]] = None,    verbose: bool = True,    auto_instrument: bool = False,    api_key: Optional[str] = None,)

All arguments are keyword-only.

Multi-project routing#

Phoenix is typically deployed as one instance per environment, and each application sends all of its traces to a single project. If you need to route traces from one application to multiple projects, the options are:

Multiple register() calls with different project_name values and set_global_tracer_provider=False on all but one. You then have to track which tracer provider to use where in your code.
OpenTelemetry Collector with a routing connector — let the application send all spans to the Collector, then route to different Phoenix projects (or different backends entirely) based on span attributes. See OpenTelemetry Collector.

For the common case — single app, single project — one register() call is everything you need.

When to Use Which#

Use case	Recommended approach
Single project, simple app	`register(...)`
Single project + auto-instrument every installed library	`register(project_name=..., auto_instrument=True)`
Multiple projects from one app	Multiple `register()` calls, or an OTel Collector routing connector
Maximum control, custom processor pipeline	Raw OTel — see Tracer Provider

Next step#

You’ve covered every component on the OTel side. Time to learn what OpenInference adds on top — starting with the semantic conventions that make AI traces meaningful:

Next: OpenInference Semantic Conventions