Metadata-Version: 2.5
Name: arize-otel
Version: 0.14.1
Summary: OpenTelemetry tracing helpers for Arize
Project-URL: Documentation, https://docs.arize.com/arize/large-language-models/tracing
Project-URL: Issues, https://github.com/Arize-ai/arize-otel-python/issues
Project-URL: Source, https://github.com/Arize-ai/arize-otel-python
Project-URL: Changelog, https://github.com/Arize-ai/arize-otel-python/blob/main/CHANGELOG.md
Author-email: Arize AI <support@arize.com>
Maintainer-email: Arize AI <support@arize.com>
License: BSD
License-File: LICENSE
Keywords: Explainability,Monitoring,Observability,Tracing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: <3.15,>=3.8
Requires-Dist: openinference-instrumentation>=0.1.22; python_version < '3.10'
Requires-Dist: openinference-instrumentation>=0.1.56; python_version >= '3.10'
Requires-Dist: openinference-semantic-conventions>=0.1.5
Requires-Dist: opentelemetry-exporter-otlp>=1.22
Requires-Dist: opentelemetry-proto>=1.12.0
Requires-Dist: opentelemetry-sdk>=1.22
Requires-Dist: requests<3,>=2
Provides-Extra: dev
Requires-Dist: pytest<9,>=7.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
    <a target="_blank" href="https://arize.com" style="background:none">
        <img alt="arize banner" src="https://storage.googleapis.com/arize-assets/arize-logo-white.jpg"  width="auto" height="auto"></img>
    </a>
    <br/>
    <br/>
    <a href="https://docs.arize.com/">
        <img src="https://img.shields.io/static/v1?message=Docs&logo=data:image/png;base64,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&labelColor=grey&color=blue&logoColor=white&label=%20"/>
    </a>
    <a target="_blank" href="https://join.slack.com/t/arize-ai/shared_invite/zt-1px8dcmlf-fmThhDFD_V_48oU7ALan4Q">
        <img src="https://img.shields.io/static/v1?message=Community&logo=slack&labelColor=grey&color=blue&logoColor=white&label=%20"/>
    </a>
    <br/>
    <a target="_blank" href="https://pypi.org/project/arize-otel/">
        <img src="https://img.shields.io/pypi/v/arize-otel">
    </a>
    <a target="_blank" href="https://pypi.org/project/arize-otel/">
        <img src="https://img.shields.io/pypi/status/arize-otel?style=flat&logo=ticktick&logoColor=white"/>
    </a>
    <a target="_blank" href="https://pypi.org/project/arize-otel/">
        <img src="https://img.shields.io/pypi/pyversions/arize-otel?logo=python&logoColor=white">
    </a>
    <a target="_blank" href="https://github.com/Arize-ai/arize-otel-python/blob/main/LICENSE">
        <img src="https://img.shields.io/pypi/l/arize-otel">
    </a>

</p>

---

- [Overview](#overview)
- [Uploading large blobs from OpenInference](#uploading-large-blobs-from-openinference)
- [Installation](#installation)
- [Quickstart](#quickstart)
  - [Automatically instrument installed OpenInference packages](#automatically-instrument-installed-openinference-packages)
  - [Add pre-export span processors](#add-pre-export-span-processors)
  - [Send traces to Arize](#send-traces-to-arize)
  - [Send traces to Custom Endpoint](#send-traces-to-custom-endpoint)
  - [Specify exporter type](#specify-exporter-type)
  - [Turn off batch processing of spans](#turn-off-batch-processing-of-spans)
  - [Debug](#debug)
- [Routing Traces to Different Arize Spaces and Projects](#routing-traces-to-different-arize-spaces-and-projects)
- [Using Environment Variables](#using-environment-variables)
- [Using OTel Primitives](#using-otel-primitives)
  - [Specifying the `endpoint` directly](#specifying-the-endpoint-directly)
  - [Configuring resources](#configuring-resources)
  - [Using a BatchSpanProcessor](#using-a-batchspanprocessor)
  - [Specifying a custom GRPC endpoint](#specifying-a-custom-grpc-endpoint)
- [Questions?](#questions)
- [Copyright, Patent, and License](#copyright-patent-and-license)

## Overview

`arize-otel` provides Arize-aware OpenTelemetry defaults for instrumenting LLM
applications and exporting their traces to [Arize](https://arize.com/).

## Uploading large blobs from OpenInference

OpenInference instrumentors can capture images as base64-encoded span
attributes. `arize-otel` can upload oversized images to Arize and replace the
inline content with a lightweight `arize://` reference. This avoids sending
large image payloads through the trace exporter while preserving the image in
Arize.

Blob uploading requires Python 3.10 or newer and
`openinference-instrumentation>=0.1.56`. Python 3.8 and 3.9 remain supported for
tracing without blob uploading.

For zero-code configuration, set the normal Arize tracing variables and select
the registered uploader:

```bash
export ARIZE_API_KEY="..."
export ARIZE_SPACE_ID="..."
export ARIZE_PROJECT_NAME="my-project"
export OPENINFERENCE_BLOB_UPLOADER="arize"
```

Use `OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH` to configure the maximum image data
URI length that OpenInference keeps inline.

You can also configure the uploader explicitly:

```python
from arize.otel import ArizeBlobUploader
from openinference.instrumentation import TraceConfig

config = TraceConfig(blob_uploader=ArizeBlobUploader())
```

Uploads run in the background after a bounded one-second grant request. If a
grant cannot be obtained, OpenInference falls back to redacting the oversized
value. A failure after an `arize://` reference has been emitted is logged but
cannot rewrite the exported span.

Use `ARIZE_BLOB_ENDPOINT` to override the blob upload endpoint independently of
`ARIZE_COLLECTOR_ENDPOINT`, such as for an on-prem deployment. The uploader also
honors `set_routing_context(...)` for applications that route traces dynamically
between spaces and projects.

## Installation

Install `arize-otel` using `pip`

```bash
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](https://docs.arize.com/phoenix/tracing/concepts-tracing/how-does-tracing-work) your application. You can instrument installed [OpenInference instrumentors](https://github.com/Arize-ai/openinference) automatically with `auto_instrument=True`, or manually call a specific instrumentor after `register`.

### Automatically instrument installed OpenInference packages

Set `auto_instrument=True` to discover installed OpenInference instrumentors and call `instrument(tracer_provider=...)` for each one:

```python
from arize.otel import register

tracer_provider = register(
    space_id="your-arize-space-id",
    api_key="your-arize-api-key",
    project_name="your-model-id",
    auto_instrument=True,
)
```

`auto_instrument=True` only instruments libraries with a corresponding OpenInference instrumentation package installed in your Python environment.

To instrument one library explicitly instead, run `instrument()` _after_ using `register`:

```python
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 without installing this or any other package from Arize.

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

### Add pre-export span processors

Some OpenInference integrations, such as processor-style integrations that transform native OpenTelemetry spans into OpenInference attributes, expose a `SpanProcessor` instead of an `instrument()` method. Pass those processors to `register(span_processors=[...])` so they run before the Arize exporter while `register` continues to configure Arize authentication headers, endpoint, transport, batching, and project metadata:

```python
from arize.otel import register
from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor

tracer_provider = register(
    space_id="your-arize-space-id",
    api_key="your-arize-api-key",
    project_name="your-model-id",
    span_processors=[OpenInferenceSpanProcessor()],
)
```

Use `span_processors` for processors that enrich or transform spans before export. You do not need to create a separate Arize `SpanExporter` just to preserve Arize headers.

### Send traces to Arize

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

```python
from arize.otel import register

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

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

```python
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](#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
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
from arize.otel import register, Transport

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

### 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
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
from arize.otel import register

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

## Routing Traces to Different Arize Spaces and Projects

The `register_with_routing` function enables dynamic routing of traces to different Arize spaces and projects. This is useful when you need to route traces from a single application to multiple Arize spaces (e.g., based on the team or service generating the request).

### Usage

First, set up the tracer provider with routing enabled via `register_with_routing`. Note that unlike the standard `register()` function, you don't need to specify a single `space_id` or `project_name` upfront.

Then, call `with set_routing_context()` to set the space id and project to which traces should be routed. The `set_routing_context()` context manager uses OpenTelemetry's context API to set routing attributes that automatically propagate to all child spans within that context. This works seamlessly with auto-instrumentors (OpenAI, LangChain, LlamaIndex, etc.) because the routing attributes are inherited by all spans created within the context. 

```python
from arize.otel import register_with_routing, set_routing_context
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer_provider = register_with_routing(
    api_key="your-arize-api-key",  
    # endpoint and transport are optional and default to Arize's GRPC endpoint
)

OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

current_project_id = "project-123"
current_space_id = "current-space"

# Both space_id and project_name must be provided for routing to work;
# otherwise, spans will be skipped and not sent to Arize
with set_routing_context(space_id=current_space_id, project_name=current_project_id):
    # All OpenAI calls and spans within this context will be routed to the specified space and project
    response = openai_client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    # Traces automatically go to "current-space" with project name "project-123"
```

### Performance Considerations

The routing processor creates a dedicated span processor (with its own exporter) for each unique `space_id` encountered. These processors are cached in memory for the lifetime of the application. If your application routes to many different spaces (e.g., hundreds or thousands), memory usage will grow accordingly.


## Using Environment Variables

`register` and the tracing constructors read environment defaults when called. Set or update
environment variables after importing the package and before constructing a provider or exporter.
Omitting an environment-backed argument, or passing `None`, uses the current environment value.
Existing providers and exporters retain their original configuration.

```python
from arize.otel import register

tracer_provider = register()
```

| Argument | Environment variable | Default when unset |
| --- | --- | --- |
| `space_id` | `ARIZE_SPACE_ID` | Required |
| `api_key` | `ARIZE_API_KEY` | Required |
| `project_name` | `ARIZE_PROJECT_NAME` | `default` |
| `project_type` | `ARIZE_PROJECT_TYPE` | `application` |
| `endpoint` | `ARIZE_COLLECTOR_ENDPOINT` | `Endpoint.ARIZE` |

`register` accepts `application`, `harness`, or `experiment` for `project_type` and sets it on the
provider resource as `arize.project.type`. Explicit arguments take precedence over environment
values. Empty strings are explicit values and fail validation; an unset or empty environment
endpoint uses `Endpoint.ARIZE`. Processors with a custom `span_exporter` do not require Arize
configuration.

## Using OTel Primitives

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

```python
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-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
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
# 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
# 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
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://join.slack.com/t/arize-ai/shared_invite/zt-1px8dcmlf-fmThhDFD_V_48oU7ALan4Q) or email support@arize.com

## Copyright, Patent, and License

Copyright 2024 Arize AI, Inc. All Rights Reserved.

This software is licensed under the terms of the 3-Clause BSD License. See [LICENSE](https://github.com/Arize-ai/arize-otel-python/blob/main/LICENSE).
