Metadata-Version: 2.3
Name: arize-phoenix-otel
Version: 0.5.1
Summary: LLM Observability
Project-URL: Documentation, https://docs.arize.com/phoenix/
Project-URL: Issues, https://github.com/Arize-ai/phoenix/issues
Project-URL: Source, https://github.com/Arize-ai/phoenix
Author-email: Arize AI <phoenix-devs@arize.com>
License: Elastic-2.0
License-File: IP_NOTICE
License-File: LICENSE
Keywords: Explainability,Monitoring,Observability
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.8
Requires-Dist: openinference-semantic-conventions>=0.1.9
Requires-Dist: opentelemetry-exporter-otlp
Requires-Dist: opentelemetry-proto>=1.12.0
Requires-Dist: opentelemetry-sdk
Requires-Dist: opentelemetry-semantic-conventions
Requires-Dist: typing-extensions<5,>=4.5
Provides-Extra: test
Description-Content-Type: text/markdown

# arize-phoenix-otel

Provides a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults.

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`

# Examples

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.


## Quickstart

```
from phoenix.otel import register
tracer_provider = register()
```

This is all you need to get started using OTel with Phoenix! `register` defaults to sending spans
to an endpoint at `http://localhost` using gRPC.

## Phoenix Authentication

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

### Configuring the collector endpoint

There are two ways to configure the collector endpoint:
- Using environment variables
- Using the `endpoint` keyword argument

#### Using environment variables

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

```
# export PHOENIX_COLLECTOR_ENDPOINT=https://your-phoenix.com:6006

from phoenix.otel import register
tracer_provider = register()
```

#### Specifying the `endpoint` directly

When passing in the `endpoint` argument, **you must specify the fully qualified endpoint**. For
example, in order to export spans via HTTP to localhost, use Pheonix's HTTP collector endpoint:
`http://localhost:6006/v1/traces`. The gRPC endpoint is different: `http://localhost:4317`.

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

### Additional configuration

`register` can be configured with different keyword arguments:
- `project_name`: The Phoenix project name (or `PHOENIX_PROJECT_NAME` env. var)
- `headers`: Headers to send along with each span payload (or `PHOENIX_CLIENT_HEADERS` env. var)
- `batch`: Whether or not to process spans in batch

```
from phoenix.otel import register
tracer_provider = register(
    project_name="otel-test", headers={"Authorization": "Bearer TOKEN"}, batch=True
)
```

## A drop-in replacement for OTel primitives

For more granular tracing configuration, these wrappers can be used as drop-in replacements for
OTel primitives:

```
from opentelemetry import trace as trace_api
from phoenix.otel import HTTPSpanExporter, TracerProvider, SimpleSpanProcessor

tracer_provider = TracerProvider()
span_exporter = HTTPSpanExporter(endpoint="http://localhost:6006/v1/traces")
span_processor = SimpleSpanProcessor(span_exporter=span_exporter)
tracer_provider.add_span_processor(span_processor)
trace_api.set_tracer_provider(tracer_provider)
```

Wrappers have Phoenix-aware defaults to greatly simplify the OTel configuration process. A special
`endpoint` keyword argument can be passed to either a `TracerProvider`, `SimpleSpanProcessor` or
`BatchSpanProcessor` in order to automatically infer which `SpanExporter` to use to simplify setup.

### Using environment variables

```
# export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006

from opentelemetry import trace as trace_api
from phoenix.otel import TracerProvider

tracer_provider = TracerProvider()
trace_api.set_tracer_provider(tracer_provider)
```

#### Specifying the `endpoint` directly

```
from opentelemetry import trace as trace_api
from phoenix.otel import TracerProvider

tracer_provider = TracerProvider(endpoint="http://localhost:4317")
trace_api.set_tracer_provider(tracer_provider)
```

### Further examples

Users can gradually add OTel components as desired:

## Configuring resources

```
# export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006

from opentelemetry import trace as trace_api
from phoenix.otel import Resource, PROJECT_NAME, TracerProvider

tracer_provider = TracerProvider(resource=Resource({PROJECT_NAME: "my-project"}))
trace_api.set_tracer_provider(tracer_provider)
```

## Using a BatchSpanProcessor

```
# export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006

from opentelemetry import trace as trace_api
from phoenix.otel import TracerProvider, BatchSpanProcessor

tracer_provider = TracerProvider()
batch_processor = BatchSpanProcessor()
tracer_provider.add_span_processor(batch_processor)
```

## Specifying a custom GRPC endpoint

```
from opentelemetry import trace as trace_api
from phoenix.otel import TracerProvider, BatchSpanProcessor, GRPCSpanExporter

tracer_provider = TracerProvider()
batch_processor = BatchSpanProcessor(
    span_exporter=GRPCSpanExporter(endpoint="http://custom-endpoint.com:6789")
)
tracer_provider.add_span_processor(batch_processor)
```
