openllmetry

library0.52.5 (versioned in sync with traceloop-sdk)pypypi✓ verified 25d ago

OpenLLMetry is a project name, not a single installable PyPI package. It refers to two related but distinct things that must not be confused: (1) The traceloop-sdk — the high-level Traceloop SDK (already documented separately) that wraps OpenLLMetry auto-instrumentation behind Traceloop.init(). (2) Standalone opentelemetry-instrumentation-* packages — individual OTel instrumentors for specific LLM providers/frameworks, published from the traceloop/openllmetry GitHub monorepo. These can be used WITHOUT traceloop-sdk in any existing OpenTelemetry setup. ECOSYSTEM CONFUSION: There is a second, competing instrumentation ecosystem called OpenInference (from Arize-ai/openinference), which publishes openinference-instrumentation-* packages. Both OpenLLMetry and OpenInference instrumentors instrument the same providers (OpenAI, LangChain, etc.), use different span attribute schemas, and route to different preferred backends. They are NOT interchangeable.

observability llm-agents ai-ml

pip install opentelemetry-instrumentation-openai

homepage ↗

INSTALL

IMPORT

SIG · OPENLLMETRY

openllmetry

observabilitypythonv0.52.5 (versioned in sync with traceloop-sdk)

Install

3.0s avg

Import

—

Disk

110MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.000s · 74.1MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 3.0s · import 0.000s · 145MB

110MB installed

● package 110MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenAIInstrumentor

✓ from opentelemetry.instrumentation.openai import OpenAIInstrumentor

✗ from opentelemetry.instrumentation.openai import OpenAIInstrumentor

TracerProvider must be configured before calling .instrument(). Instrumentors do not create or manage the TracerProvider — that is your responsibility. If you want zero-config setup, use traceloop-sdk instead (it manages the TracerProvider for you).

# Standalone usage — no traceloop-sdk required # Requires only: opentelemetry-sdk + opentelemetry-exporter-otlp + individual instrumentors import os from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter # 1. Set up TracerProvider and exporter (any OTLP backend) tracer_provider = TracerProvider() exporter = OTLPSpanExporter( endpoint='http://localhost:4318/v1/traces', # Jaeger, Grafana, Phoenix, Datadog, etc. ) tracer_provider.add_span_processor(BatchSpanProcessor(exporter)) trace.set_tracer_provider(tracer_provider) # 2. Instrument providers — must call before importing/using the library from opentelemetry.instrumentation.openai import OpenAIInstrumentor from opentelemetry.instrumentation.langchain import LangChainInstrumentor OpenAIInstrumentor().instrument(tracer_provider=tracer_provider) LangChainInstrumentor().instrument(tracer_provider=tracer_provider) # 3. Use your libraries normally — spans are captured automatically import openai client = openai.OpenAI(api_key=os.environ['OPENAI_API_KEY']) response = client.chat.completions.create( model='gpt-4o', messages=[{'role': 'user', 'content': 'Hello!'}] ) # To suppress prompt/completion content from traces (PII/privacy): os.environ['TRACELOOP_TRACE_CONTENT'] = 'false' # Must be set before .instrument() is called # Using with traceloop-sdk (alternative — SDK manages the provider): # from traceloop.sdk import Traceloop # Traceloop.init(app_name='my-app') # handles all of the above automatically

Debug

Known issues

breakingThere is no 'openllmetry' package on PyPI. pip install openllmetry fails. The correct packages are individual opentelemetry-instrumentation-* packages (for standalone use) or traceloop-sdk (for managed use). This is the most common mistake from reading OpenLLMetry documentation without checking package names.

fix

pip install opentelemetry-instrumentation-openai (or whichever provider you need). Full package list: https://github.com/traceloop/openllmetry/tree/main/packages

affects: all

breakingTwo competing ecosystems publish instrumentors for the same providers under similar-looking package names: opentelemetry-instrumentation-openai (OpenLLMetry/Traceloop, imports from opentelemetry.instrumentation.*) vs openinference-instrumentation-openai (OpenInference/Arize, imports from openinference.instrumentation.*). Mixing instrumentors from both ecosystems in the same app generates spans with conflicting attribute schemas. Most backends are only tuned for one schema.

fix

Pick one ecosystem and stick to it. Using Phoenix or Arize AX? Use openinference-instrumentation-* packages. Using Datadog, Traceloop cloud, or a generic OTLP backend? Use opentelemetry-instrumentation-* packages (OpenLLMetry). Never mix both in the same app unless you have a span processor that normalizes the schemas.

affects: all

breakingInstrumentors must be called BEFORE the target library is imported or used. Calling OpenAIInstrumentor().instrument() after openai has already been imported and used will not retroactively patch existing client instances. New instances created after .instrument() may work, but this is unreliable.

fix

Call all .instrument() calls at application startup before any other imports of the target library. Structure: (1) set up TracerProvider, (2) call all .instrument(), (3) import and use provider libraries.

affects: all

gotchaTRACELOOP_TRACE_CONTENT=false must be set BEFORE .instrument() is called. Setting it after instrumentation has been applied has no effect — the content capture is baked in at patch time.

fix

Set os.environ['TRACELOOP_TRACE_CONTENT'] = 'false' at the very top of your entry point, before any instrumentation calls.

affects: all

gotchaDatadog's LLM Observability supports OpenLLMetry (opentelemetry-instrumentation-*) starting at version 0.47+. It explicitly does NOT support OpenInference (openinference-instrumentation-*). Other backends have different compatibility: Phoenix natively supports OpenInference but can accept OpenLLMetry spans via a span processor bridge.

fix

Verify your target backend's supported schema before choosing an ecosystem. Check backend docs for 'OpenLLMetry' vs 'OpenInference' support.

affects: all

breakingThe OpenTelemetry OTLP exporter (e.g., OTLPSpanExporter) is not found. This indicates that the `opentelemetry-exporter-otlp` package (or its specific HTTP/gRPC variant) has not been installed. Without an exporter, traces cannot be sent to an OTLP backend.

fix

Install the necessary OpenTelemetry exporter package: `pip install opentelemetry-exporter-otlp` (for gRPC) or `pip install opentelemetry-exporter-otlp-proto-http` (for HTTP/protobuf).

affects: all

Upgrade

Version history

0.52.5 (versioned in sync with traceloop-sdk)latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

47 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

homepagehttps://www.traceloop.com/openllmetry ↗