{"id":3882,"library":"arize-phoenix-otel","title":"Arize Phoenix OpenTelemetry Wrapper","description":"arize-phoenix-otel is a Python library that provides a lightweight wrapper around OpenTelemetry primitives, offering Phoenix-aware defaults and tracing decorators for common Generative AI patterns. It simplifies the setup of OpenTelemetry for sending traces to Arize Phoenix, an open-source AI observability platform. The library is actively maintained, with frequent updates released as part of the larger `arize-phoenix` monorepo, currently at version 0.15.0.","status":"active","version":"0.15.0","language":"en","source_language":"en","source_url":"https://github.com/Arize-ai/phoenix/tree/main/python/arize-phoenix-otel","tags":["LLM","Observability","OpenTelemetry","Tracing","AI","ML","GenAI"],"install":[{"cmd":"pip install arize-phoenix-otel","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core OpenTelemetry SDK which this library wraps.","package":"opentelemetry-sdk","optional":false},{"reason":"Common instrumentation for OpenAI calls, used with `auto_instrument=True`.","package":"openinference-instrumentation-openai","optional":true}],"imports":[{"note":"The `arize.otel` package is for Arize AX (a different cloud product), while `phoenix.otel` is for the open-source Arize Phoenix. Using the wrong import will lead to incorrect setup and data routing.","wrong":"from arize.otel import register","symbol":"register","correct":"from phoenix.otel import register"},{"symbol":"TracerProvider","correct":"from phoenix.otel import TracerProvider"},{"symbol":"HTTPSpanExporter","correct":"from phoenix.otel import HTTPSpanExporter"}],"quickstart":{"code":"import os\nfrom phoenix.otel import register\nfrom opentelemetry import trace\n\n# Configure Phoenix collector endpoint and API key via environment variables\n# PHOENIX_COLLECTOR_ENDPOINT defaults to http://localhost:4317 (gRPC) or http://localhost:6006/v1/traces (HTTP)\n# PHOENIX_API_KEY for authentication if required by your Phoenix instance\n\n# Example usage with explicit project name and auto-instrumentation\n# For production, set PHOENIX_COLLECTOR_ENDPOINT and PHOENIX_API_KEY environment variables.\n# If running locally without env vars, it defaults to localhost.\ntracer_provider = register(\n    project_name=os.environ.get('PHOENIX_PROJECT_NAME', 'my-llm-app'),\n    auto_instrument=True, # Automatically instruments supported AI/ML libraries like OpenAI, LangChain\n    batch=True # Enable batch processing for better performance, requires shutdown call\n)\n\n# Get a tracer\ntracer = trace.get_tracer(__name__)\n\n# Example of creating a span manually (if auto_instrument=False or for custom logic)\nwith tracer.start_as_current_span(\"my-manual-operation\") as span:\n    span.set_attribute(\"input\", \"test data\")\n    print(\"Performing a traced operation...\")\n    span.set_attribute(\"output\", \"result data\")\n\n# Important: If batch=True, ensure all spans are flushed before the process exits\ntracer_provider.shutdown()","lang":"python","description":"This quickstart demonstrates how to initialize the OpenTelemetry tracer with Arize Phoenix using the `register()` function. It shows how to configure a project name, enable automatic instrumentation for common AI/ML libraries, and includes a manual span creation. Crucially, it highlights the need for `tracer_provider.shutdown()` when using batch processing to ensure all telemetry data is exported before the application terminates. Environment variables (`PHOENIX_COLLECTOR_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`) are automatically read for configuration."},"warnings":[{"fix":"Always import from `phoenix.otel` for Arize Phoenix. Verify your intended product before implementing.","message":"Critical: There are two distinct Arize products with separate Python packages: `arize-phoenix-otel` (for open-source Phoenix) and `arize-otel` (for Arize AX, a cloud product). Ensure you are using `from phoenix.otel import register` for Arize Phoenix. Using `arize.otel` will configure tracing for the wrong product.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the official Arize Phoenix v14 migration guide for detailed steps. Update CLI commands, client instantiation, and API calls to conform to the new structure.","message":"Version 14.0.0 of the broader `arize-phoenix` ecosystem (which `arize-phoenix-otel` is part of) introduced several breaking changes. These include the removal of the `/v1/evaluations` endpoint, deprecation and removal of Evals 1.0 modules, and significant changes to the CLI and the `arize-phoenix-client` package (e.g., `px.Client()` removed, `endpoint` parameter renamed to `base_url`). While `arize-phoenix-otel` focuses on tracing, these changes can affect how users interact with the Phoenix backend.","severity":"breaking","affected_versions":"arize-phoenix>=14.0.0"},{"fix":"Specify the complete endpoint URL (e.g., `register(endpoint=\"http://my-phoenix.com:6006/v1/traces\")`) or ensure `PHOENIX_COLLECTOR_ENDPOINT` environment variable is set with the full URL.","message":"When configuring the OpenTelemetry collector endpoint directly, you must provide a fully qualified URL including the path. For HTTP/protobuf, this is typically `http://localhost:6006/v1/traces`, and for gRPC, it's `http://localhost:4317`. Simply providing `http://localhost:6006` or `http://localhost` may lead to incorrect endpoint resolution.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always call `tracer_provider.shutdown()` at the end of your application's lifecycle, especially in short-lived scripts. Alternatively, use `batch=False` for immediate (but potentially less efficient) export or use `with register(...) as tracer_provider:` context manager.","message":"If batch processing of spans is enabled (`batch=True` in `register()`), it's crucial to call `tracer_provider.shutdown()` before your application process exits. Failing to do so may result in queued spans not being exported to the Phoenix collector, leading to incomplete traces.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}