Implementation:Arize ai Phoenix Span Processor Exporter

Knowledge Sources	Phoenix
Domains	AI Observability, OpenTelemetry, Telemetry Transport
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for transmitting telemetry spans from client applications to a collector provided by the phoenix.otel module's Phoenix-aware wrappers around the OpenTelemetry SDK's SimpleSpanProcessor, BatchSpanProcessor, HTTPSpanExporter, and GRPCSpanExporter.

Description

The phoenix.otel module provides drop-in replacements for four core OpenTelemetry SDK classes. These wrappers extend the base classes with Phoenix-aware defaults: automatic endpoint inference from environment variables, automatic authentication header injection, and protocol auto-detection based on URL patterns.

Four wrapper classes:

SimpleSpanProcessor: Extends opentelemetry.sdk.trace.export.SimpleSpanProcessor. Exports each completed span synchronously. When no explicit span_exporter is provided, it auto-creates an HTTP or gRPC exporter based on the endpoint.
BatchSpanProcessor: Extends opentelemetry.sdk.trace.export.BatchSpanProcessor. Buffers spans and exports in batches. Same auto-creation behavior as SimpleSpanProcessor.
HTTPSpanExporter: Extends opentelemetry.exporter.otlp.proto.http.trace_exporter.OTLPSpanExporter. Sends spans via HTTP POST with protobuf serialization. Auto-infers the endpoint (defaulting to http://localhost:6006/v1/traces) and authentication headers.
GRPCSpanExporter: Extends opentelemetry.exporter.otlp.proto.grpc.trace_exporter.OTLPSpanExporter. Sends spans via gRPC. Auto-infers the endpoint (defaulting to http://localhost:4317) and authentication headers.

All four classes check for authentication headers in the following precedence order: (1) explicit headers parameter, (2) PHOENIX_CLIENT_HEADERS / OTEL_EXPORTER_OTLP_HEADERS environment variables, (3) PHOENIX_API_KEY environment variable (injected as an Authorization: Bearer header).

Usage

Use these wrapper classes when:

You need more control than register() provides but still want Phoenix-aware defaults.
You are composing a custom tracing pipeline with specific processor/exporter combinations.
You need to configure batch processing parameters (queue size, batch size, schedule delay).
You want to explicitly select HTTP or gRPC transport.

Code Reference

Source Location

Repository: Phoenix
File: packages/phoenix-otel/src/phoenix/otel/otel.py
- SimpleSpanProcessor: lines 367-436
- BatchSpanProcessor: lines 439-523
- HTTPSpanExporter: lines 526-598
- GRPCSpanExporter: lines 601-683

Signature

SimpleSpanProcessor:

class SimpleSpanProcessor(_SimpleSpanProcessor):
    def __init__(
        self,
        span_exporter: Optional[SpanExporter] = None,
        endpoint: Optional[str] = None,
        headers: Optional[Dict[str, str]] = None,
        protocol: Optional[Literal["http/protobuf", "grpc"]] = None,
    ):
        ...

BatchSpanProcessor:

class BatchSpanProcessor(_BatchSpanProcessor):
    def __init__(
        self,
        span_exporter: Optional[SpanExporter] = None,
        endpoint: Optional[str] = None,
        headers: Optional[Dict[str, str]] = None,
        protocol: Optional[Literal["http/protobuf", "grpc"]] = None,
    ):
        ...

HTTPSpanExporter:

class HTTPSpanExporter(_HTTPSpanExporter):
    def __init__(self, *args: Any, **kwargs: Any):
        ...

GRPCSpanExporter:

class GRPCSpanExporter(_GRPCSpanExporter):
    def __init__(self, *args: Any, **kwargs: Any):
        ...

Import

from phoenix.otel import SimpleSpanProcessor, BatchSpanProcessor
from phoenix.otel import HTTPSpanExporter, GRPCSpanExporter

I/O Contract

Inputs (SimpleSpanProcessor / BatchSpanProcessor)

Name	Type	Required	Description
span_exporter	Optional[SpanExporter]	No	An explicit `SpanExporter` instance. If `None`, one is auto-created based on the endpoint and protocol.
endpoint	Optional[str]	No	Collector endpoint URL. Falls back to `PHOENIX_COLLECTOR_ENDPOINT` env var, then `http://localhost:6006`. Used only when `span_exporter` is `None`.
headers	Optional[Dict[str, str]]	No	Custom headers for authentication. Falls back to `PHOENIX_CLIENT_HEADERS` / `OTEL_EXPORTER_OTLP_HEADERS` env vars. Used only when `span_exporter` is `None`.
protocol	Optional[Literal["http/protobuf", "grpc"]]	No	Explicit transport protocol. If not set, inferred from the endpoint URL pattern.

Inputs (HTTPSpanExporter)

Name	Type	Required	Description
endpoint	Optional[str]	No	HTTP collector endpoint (e.g., `http://localhost:6006/v1/traces`). Falls back to `PHOENIX_COLLECTOR_ENDPOINT` + `/v1/traces` suffix.
headers	Optional[Dict[str, str]]	No	HTTP headers for authentication. Falls back to env vars and `PHOENIX_API_KEY`.
args, *kwargs	Any	No	All other arguments forwarded to the base `OTLPSpanExporter` (e.g., `timeout`, `compression`).

Inputs (GRPCSpanExporter)

Name	Type	Required	Description
endpoint	Optional[str]	No	gRPC collector endpoint (e.g., `http://localhost:4317`). Falls back to `PHOENIX_COLLECTOR_ENDPOINT` with gRPC port.
headers	Optional[Dict[str, str]]	No	gRPC metadata headers for authentication. Falls back to env vars and `PHOENIX_API_KEY`.
insecure	Optional[bool]	No	Whether to use an insecure channel. Forwarded to the base exporter.
credentials	Optional	No	gRPC credentials object for server authentication.
timeout	Optional[int]	No	Backend request timeout in seconds.
compression	Optional	No	gRPC compression method.

Outputs

Name	Type	Description
SimpleSpanProcessor instance	SimpleSpanProcessor	Processor that exports spans synchronously on the calling thread.
BatchSpanProcessor instance	BatchSpanProcessor	Processor that buffers and exports spans in batches on a background thread.
HTTPSpanExporter instance	HTTPSpanExporter	Exporter that serializes spans as protobuf and sends via HTTP POST.
GRPCSpanExporter instance	GRPCSpanExporter	Exporter that serializes spans as protobuf and sends via gRPC.

Usage Examples

Simple Processor with Auto-Inferred Endpoint

from phoenix.otel import SimpleSpanProcessor

# Endpoint and exporter are auto-created from PHOENIX_COLLECTOR_ENDPOINT
processor = SimpleSpanProcessor()

Batch Processor for Production

from phoenix.otel import BatchSpanProcessor

processor = BatchSpanProcessor(
    endpoint="https://my-phoenix.com/v1/traces",
    headers={"Authorization": "Bearer my-token"},
    protocol="http/protobuf",
)

Custom Exporter with Explicit Configuration

from phoenix.otel import HTTPSpanExporter, BatchSpanProcessor

exporter = HTTPSpanExporter(
    endpoint="http://localhost:6006/v1/traces",
    headers={"Authorization": "Bearer my-token"},
)

processor = BatchSpanProcessor(span_exporter=exporter)

gRPC Transport

from phoenix.otel import GRPCSpanExporter, SimpleSpanProcessor

exporter = GRPCSpanExporter(endpoint="http://localhost:4317")
processor = SimpleSpanProcessor(span_exporter=exporter)

Composing a Full Custom Pipeline

from phoenix.otel import TracerProvider, BatchSpanProcessor, HTTPSpanExporter
from opentelemetry.sdk.resources import Resource

# Create a custom resource
resource = Resource.create({
    "openinference.project.name": "my-production-app",
    "service.name": "inference-service",
})

# Create exporter and processor
exporter = HTTPSpanExporter(
    endpoint="https://collector.example.com/v1/traces",
    headers={"X-API-Key": "secret"},
)
processor = BatchSpanProcessor(span_exporter=exporter)

# Assemble the provider
provider = TracerProvider(resource=resource, verbose=False)
provider.add_span_processor(processor)

Protocol Auto-Detection

from phoenix.otel import SimpleSpanProcessor

# HTTP is inferred because the path contains /v1/traces
http_processor = SimpleSpanProcessor(
    endpoint="http://localhost:6006/v1/traces"
)

# gRPC is inferred because port 4317 matches the default gRPC port
grpc_processor = SimpleSpanProcessor(
    endpoint="http://localhost:4317"
)

# Explicit protocol override
explicit_processor = SimpleSpanProcessor(
    endpoint="http://localhost:8080",
    protocol="http/protobuf",
)

Related Pages

Implements Principle

Principle:Arize_ai_Phoenix_Span_Transmission

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment