OpenLLMetry (Standalone Instrumentors)

Warnings

• breaking There 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
• breaking Two 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.
• breaking Instrumentors 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.
• gotcha TRACELOOP_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.
• gotcha Datadog'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.

Install

• pip install opentelemetry-instrumentation-openai OpenAI instrumentor (from OpenLLMetry / Traceloop)
• pip install opentelemetry-instrumentation-anthropic Anthropic instrumentor
• pip install opentelemetry-instrumentation-langchain LangChain instrumentor
• pip install opentelemetry-instrumentation-llamaindex LlamaIndex instrumentor
• pip install opentelemetry-instrumentation-chromadb opentelemetry-instrumentation-pinecone opentelemetry-instrumentation-weaviate Vector DB instrumentors

Imports

• OpenAI instrumentor (OpenLLMetry)

  from opentelemetry.instrumentation.openai import OpenAIInstrumentor

  Both exist and both work, but produce different span schemas. opentelemetry.instrumentation = OpenLLMetry (Traceloop). openinference.instrumentation = OpenInference (Arize). Importing the wrong one for your backend results in spans with mismatched attribute names that your backend may not parse correctly.

Quickstart

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