Traceloop SDK (OpenLLMetry)

Warnings

• breaking Traceloop.init() MUST be called before importing provider libraries (openai, anthropic, langchain, etc.). The SDK instruments providers via OpenTelemetry monkey-patching applied at init time. If you import openai before calling Traceloop.init(), the OpenAI client is not patched and zero spans are generated — no error, no warning, just missing traces.
  Fix: Always structure imports as: (1) from traceloop.sdk import Traceloop, (2) Traceloop.init(...), (3) import openai / import anthropic / etc. Never import provider libraries at the top of your file before Traceloop.init() runs.
• breaking @aworkflow decorator is deprecated and will be removed in a future version. @workflow now handles both sync and async functions — use it for both.
  Fix: Replace all @aworkflow with @workflow. No other change needed — the decorator handles async automatically.
• gotcha disable_batch defaults to False (batch mode). In production this is correct — batching reduces overhead. In development/local testing, batches are held and flushed on a timer, so traces may not appear in your backend for several seconds after function completion. Confusingly, the process may exit before the batch flushes, causing traces to vanish entirely.
  Fix: Add disable_batch=True to Traceloop.init() in all dev/test environments. Remove it in production.
• gotcha There is no installable package named 'openllmetry' on PyPI. The project is called OpenLLMetry and the GitHub repo is traceloop/openllmetry, but the Python package is 'traceloop-sdk'. pip install openllmetry will fail or install a wrong package. Individual instrumentors (for specific providers without the full SDK) are installable as separate packages: e.g. opentelemetry-instrumentation-openai.
  Fix: pip install traceloop-sdk — not openllmetry. If you only need instrumentors for an existing OTel stack (no Traceloop.init()), install the individual opentelemetry-instrumentation-* packages from the openllmetry repo.
• gotcha TRACELOOP_HEADERS uses a non-standard key=value format (not HTTP header format). Example: 'Authorization=Bearer token' NOT 'Authorization: Bearer token'. Using colons instead of equals signs causes the header to not be sent, resulting in 401/403 errors at the OTLP endpoint with no clear error message.
  Fix: Use equals sign: TRACELOOP_HEADERS='Authorization=Bearer <token>'. For multiple headers, comma-separate: 'Authorization=Bearer <token>,x-org-id=123'.

Install

• pip install traceloop-sdk Core SDK — auto-instruments supported providers on init

Imports

• Traceloop

  from traceloop.sdk import Traceloop

  Main class. Call Traceloop.init() once at startup. There is no 'openllmetry' top-level import — that's the project name, not a Python package.
• decorators

  from traceloop.sdk.decorators import workflow, task, agent, tool

  All span-type decorators live in traceloop.sdk.decorators. @aworkflow was deprecated — use @workflow for both sync and async functions.

Quickstart

Import order is load-bearing. Traceloop.init() must be called before importing provider libraries — the SDK uses OTel monkey-patching which only works if the provider hasn't been imported yet. disable_batch=True is strongly recommended in development.

import os

# CRITICAL: Import and init Traceloop BEFORE importing openai, langchain, etc.
# The SDK patches provider modules at init time — late import means no instrumentation.
from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, task

# Option A: Export to Traceloop cloud
Traceloop.init(
    app_name='my-llm-app',
    api_key=os.environ['TRACELOOP_API_KEY'],
    disable_batch=True  # disable in dev — sends spans immediately, not in batches
)

# Option B: Export to any OTLP backend (no Traceloop account needed)
# Set via env vars before init:
# TRACELOOP_BASE_URL=http://localhost:4318  (Jaeger, Grafana Agent, etc.)
# TRACELOOP_HEADERS='Authorization=Bearer <token>'
Traceloop.init(app_name='my-llm-app')  # reads env vars automatically

# Provider imports AFTER init
import openai
client = openai.OpenAI()

# Manual tracing with decorators
@workflow(name='answer_question')
def answer_question(question: str) -> str:
    response = client.chat.completions.create(
        model='gpt-4o',
        messages=[{'role': 'user', 'content': question}]
    )
    return response.choices[0].message.content

# @task for sub-steps within a workflow
@task(name='format_prompt')
def format_prompt(question: str) -> str:
    return f'Answer concisely: {question}'

result = answer_question('What is OpenTelemetry?')