> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry (arize-otel)

[<img src="https://storage.googleapis.com/arize-phoenix-assets/assets/images/arize-docs-images/bf5f53ec-arize-otel.svg" />](https://pypi.org/project/arize-otel/)

<Card title="GitHub - Arize-ai/arize-otel-python" icon="github" href="https://github.com/Arize-ai/arize-otel-python" horizontal>
  Github
</Card>

We have full support for OpenTelemetry simplified instrumentation code that sets up tracing automatically.

The `arize-otel` package provides a lightweight wrapper around OpenTelemetry primitives with Arize AX-aware defaults and options. It is meant to be a very lightweight convenience package to set up OpenTelemetry for tracing LLM applications and send the traces to Arize AX.

Read here for more on [how tracing works](https://arize.com/docs/phoenix/learn/tracing/how-tracing-works).

## Installation

Install `arize-otel` using `pip`

```bash theme={null}
pip install arize-otel
```

## Quickstart

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

The following examples showcase how to use `register` to setup OpenTelemetry in order to send traces to a collector. However, this is **NOT** the same as [instrumenting](/ax/observe/tracing-concepts/what-are-traces) your application. For instance, you can use any of our [OpenInference AutoInstrumentators](https://github.com/Arize-ai/openinference). Assuming we use the OpenAI AutoInstrumentation, we need to run `instrument()` *after* using `register`:

```python theme={null}
from arize.otel import register
# Setup OTel via our convenience function
tracer_provider = register(
    # See details in examples below...
)

# Instrument your application using OpenInference AutoInstrumentators
from openinference.instrumentation.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)
```

The above code snippet will yield a fully setup and instrumented application. It is worth noting that this is completely **optional**. The usage of this package is for convenience only, you can set up OpenTelemetry and send traces to Arize AX without installing this or any other package from Arize AX.

In the following sections we have examples on how to use the `register` function:

### Send traces to Arize AX

To send traces to Arize AX you need to authenticate via the Space ID and API Key. You can find them in the Settings page in the Arize AX platform. In addition, you'll need to specify the project name, a unique name to identify your project in the Arize AX platform.

```python theme={null}
from arize.otel import register

tracer_provider = register(
    space_id = "your-arize-space-id",
    api_key = "your-arize-api-key",
    project_name = "your-project-name",
)
```

### Arize AX GRPC + HTTPS Endpoints

Arize AX has two different endpoints which can be set using the following:

The default behavior is to utilize GRPC which is `https://otlp.arize.com/v1`

```python theme={null}
from arize.otel import register, Endpoint

tracer_provider = register(
    endpoint=Endpoint.ARIZE, #this is the default value if not specified
    space_id = "your-arize-space-id",
    api_key = "your-arize-api-key",
    project_name = "your-model-id",
)
```

The Arize AX HTTPS endpoint is `https://otlp.arize.com/v1/traces`

```python theme={null}
from arize.otel import register, Endpoint, Transport

tracer_provider = register(
    endpoint= "https://otlp.arize.com/v1/traces" #this is the HTTPS endpoint
    space_id = "your-arize-space-id",
    api_key = "your-arize-api-key",
    project_name = "your-model-id",
    transport = Transport.HTTP,
)
```

### Arize AX EU Endpoint

If you are located in the European Union, you'll need to specify the corresponding `Endpoint` (the default endpoint is `Endpoint.ARIZE`):

```python theme={null}
from arize.otel import register, Endpoint

tracer_provider = register(
    endpoint=Endpoint.ARIZE_EUROPE,
    space_id = "your-arize-space-id",
    api_key = "your-arize-api-key",
    project_name = "your-model-id",
)
```

If you would like to configure your tracing using environment variables instead of passing arguments, read Using Environment Variables.

### Send traces to Custom Endpoint

Sending traces to a collector on a custom endpoint is simple, you just need to provide the endpoint as a string. In addition, it is worth noting that the default is to use a `GRPCSpanExporter`. If you'd like to use a `HTTPSpanExporter` instead, specify the transport as shown below:

```python theme={null}
from arize.otel import register

tracer_provider = register(
    endpoint = "https://my-custom-endpoint"
    # any other options...
)
```

### Specify exporter type

If you're using endpoints from the `Endpoint` enum, you do not need to do this, since we know what exporter to use. However, if you're using a custom endpoint, it is worth noting that the default is to use a `GRPCSpanExporter`. If you'd like to use a `HTTPSpanExporter` instead, specify the transport as shown below:

```python theme={null}
from arize.otel import register, Transport

tracer_provider = register(
    endpoint = "https://my-custom-endpoint"
    transport = Transport.HTTP,
    # any other options...
)
```

<Info>
  Note that there can be a silent failure if the transport type and endpoint's expected transport format are mismatched.
</Info>

### Turn off batch processing of spans

We default to using [BatchSpanProcessor](https://opentelemetry.io/docs/languages/js/instrumentation/#picking-the-right-span-processor) from OpenTelemetry because it is non-blocking in case telemetry goes down. In contrast, "SimpleSpanProcessor processes spans as they are created." This can be helpful in development. You can use `SimpleSpanProcessor` with the option `use_batch_processor=False`.

```python theme={null}
from arize.otel import register

tracer_provider = register(
    # other options...
    batch=False
)
```

### Debug

As you're setting up your tracing, it is helpful to print to console the spans created. You can achieve this by setting `log_to_console=True`.

```python theme={null}
from arize.otel import register

tracer_provider = register(
    # other options...
    log_to_console=True
)
```

### Route traces to multiple spaces and projects

If a single application needs to send traces to different Arize AX spaces or projects, use `register_with_routing`. This is useful for multi-tenant applications, shared platforms, or services that need to route traces by team, customer, or environment at request time.

Unlike `register`, you do not configure a single `space_id` or `project_name` up front. Instead, you set routing values dynamically with `set_routing_context`, and all child spans created within that context inherit those values automatically.

```python theme={null}
from arize.otel import register_with_routing, set_routing_context
from openinference.instrumentation.openai import OpenAIInstrumentor
from openai import OpenAI

tracer_provider = register_with_routing(
    api_key="your-arize-api-key",
)

OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

client = OpenAI()

with set_routing_context(
    space_id="your-space-id",
    project_name="your-project-name",
):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Write a haiku about tracing."}],
    )
```

In this example, all spans created inside the `with set_routing_context(...)` block are routed to the specified Arize AX space and project. This includes spans created by auto-instrumentors such as OpenAI, LangChain, and LlamaIndex.

<Info>
  Both `space_id` and `project_name` are required for routing. If either value is missing, spans in that context are not sent to Arize AX.
</Info>

<Warning>
  `register_with_routing` creates and caches a dedicated span processor for each unique `space_id` it sees. If your application routes to a large number of spaces, memory usage will grow accordingly.
</Warning>

Use an API key that has access to every target space you plan to route traces to. For long-running services, consider using a [service key](/ax/security-and-settings/service-keys).

## Using Environment Variables

The register function will read from environment variables if the arguments are not passed:

```python theme={null}
from arize.otel import register

tracer_provider = register(
    space_id = ... # Will be read from ARIZE_SPACE_ID env var
    api_key = ... # Will be read from ARIZE_API_KEY env var
    project_name = ... # Will be read from ARIZE_PROJECT_NAME env var
    endpoint = ... # Will be read from ARIZE_COLLECTOR_ENDPOINT env var, defaults to Endpoint.Arize
)
```

In the event of conflict, if an environment variable is set but a different argument is passed, the argument passed will take precedence and the environment variable will be ignored.

## Using OTel Primitives

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

```python theme={null}
from opentelemetry import trace as trace_api
from arize.otel import HTTPSpanExporter, TracerProvider, SimpleSpanProcessor

tracer_provider = TracerProvider()
span_exporter = HTTPSpanExporter(endpoint=...)
span_processor = SimpleSpanProcessor(span_exporter=span_exporter)
tracer_provider.add_span_processor(span_processor)
trace_api.set_tracer_provider(tracer_provider)
```

Wrappers have Arize AX-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.

**Specifying the **`endpoint`** directly**

```python theme={null}
from opentelemetry import trace as trace_api
from arize.otel import TracerProvider

tracer_provider = TracerProvider(endpoint="https://your-desired-endpoint.com")
trace_api.set_tracer_provider(tracer_provider)
```

### Configuring resources

```python theme={null}
# export ARIZE_COLLECTOR_ENDPOINT=https://your-desired-endpoint.com

from opentelemetry import trace as trace_api
from arize.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

```python theme={null}
# export ARIZE_COLLECTOR_ENDPOINT=https://your-desired-endpoint.com

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

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

### Specifying a custom GRPC endpoint

```python theme={null}
from opentelemetry import trace as trace_api
from arize.otel import TracerProvider, BatchSpanProcessor, GRPCSpanExporter

tracer_provider = TracerProvider()
batch_processor = BatchSpanProcessor(
    span_exporter=GRPCSpanExporter(endpoint="https://your-desired-endpoint.com")
)
tracer_provider.add_span_processor(batch_processor)
```

## Questions?

Find us in our [Slack Community](https://arize-ai.slack.com/join/shared_invite/zt-2w57bhem8-hq24MB6u7yE_ZF_ilOYSBw#/shared-invite/email) or email [support@arize.com](mailto:support@arize.com)