{"id":77,"library":"traceloop-sdk","title":"Traceloop SDK (OpenLLMetry)","description":"Python SDK for OpenLLMetry — an open-source, OpenTelemetry-based observability library for LLM applications built and maintained by Traceloop. Provides auto-instrumentation for 20+ LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Ollama) and frameworks (LangChain, LlamaIndex, CrewAI), plus manual @workflow/@task/@agent decorators. KEY RELATIONSHIP: traceloop-sdk is the convenience wrapper around OpenLLMetry instrumentation packages. 'openllmetry' is NOT a separate installable package — it's the umbrella project name for the GitHub monorepo. The installable SDK is 'traceloop-sdk'. By default, traces are exported to Traceloop cloud, but the SDK is fully vendor-agnostic via TRACELOOP_BASE_URL — it can export to any OTLP backend (Datadog, Grafana, Jaeger, Honeycomb, etc.) without using Traceloop's platform at all.","status":"active","version":"0.52.5","language":"python","source_language":"en","source_url":"https://github.com/traceloop/openllmetry","tags":["traceloop","openllmetry","tracing","observability","opentelemetry","llm-monitoring","auto-instrumentation","otel"],"install":[{"cmd":"pip install traceloop-sdk","lang":"bash","label":"Core SDK — auto-instruments supported providers on init"}],"dependencies":[],"imports":[{"note":"Main class. Call Traceloop.init() once at startup. There is no 'openllmetry' top-level import — that's the project name, not a Python package.","wrong":"import openllmetry","symbol":"Traceloop","correct":"from traceloop.sdk import Traceloop"},{"note":"All span-type decorators live in traceloop.sdk.decorators. @aworkflow was deprecated — use @workflow for both sync and async functions.","wrong":"from traceloop.sdk import workflow","symbol":"decorators","correct":"from traceloop.sdk.decorators import workflow, task, agent, tool"}],"quickstart":{"code":"import os\n\n# CRITICAL: Import and init Traceloop BEFORE importing openai, langchain, etc.\n# The SDK patches provider modules at init time — late import means no instrumentation.\nfrom traceloop.sdk import Traceloop\nfrom traceloop.sdk.decorators import workflow, task\n\n# Option A: Export to Traceloop cloud\nTraceloop.init(\n    app_name='my-llm-app',\n    api_key=os.environ['TRACELOOP_API_KEY'],\n    disable_batch=True  # disable in dev — sends spans immediately, not in batches\n)\n\n# Option B: Export to any OTLP backend (no Traceloop account needed)\n# Set via env vars before init:\n# TRACELOOP_BASE_URL=http://localhost:4318  (Jaeger, Grafana Agent, etc.)\n# TRACELOOP_HEADERS='Authorization=Bearer <token>'\nTraceloop.init(app_name='my-llm-app')  # reads env vars automatically\n\n# Provider imports AFTER init\nimport openai\nclient = openai.OpenAI()\n\n# Manual tracing with decorators\n@workflow(name='answer_question')\ndef answer_question(question: str) -> str:\n    response = client.chat.completions.create(\n        model='gpt-4o',\n        messages=[{'role': 'user', 'content': question}]\n    )\n    return response.choices[0].message.content\n\n# @task for sub-steps within a workflow\n@task(name='format_prompt')\ndef format_prompt(question: str) -> str:\n    return f'Answer concisely: {question}'\n\nresult = answer_question('What is OpenTelemetry?')","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"fix":"Replace all @aworkflow with @workflow. No other change needed — the decorator handles async automatically.","message":"@aworkflow decorator is deprecated and will be removed in a future version. @workflow now handles both sync and async functions — use it for both.","severity":"breaking","affected_versions":"recent"},{"fix":"Add disable_batch=True to Traceloop.init() in all dev/test environments. Remove it in production.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use equals sign: TRACELOOP_HEADERS='Authorization=Bearer <token>'. For multiple headers, comma-separate: 'Authorization=Bearer <token>,x-org-id=123'.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure all required dependencies are installed. If 'pip install traceloop-sdk' was not sufficient, try explicitly installing 'httpx' with 'pip install httpx'.","message":"The Traceloop SDK, or one of its core dependencies, requires the 'httpx' library. A 'ModuleNotFoundError: No module named 'httpx'' indicates that 'httpx' was not installed successfully alongside the SDK.","severity":"breaking","affected_versions":"all"},{"fix":"Ensure that the 'openai' package is installed in your Python environment. You can typically resolve this by running `pip install openai`.","message":"The script failed with a 'ModuleNotFoundError: No module named 'openai''. This indicates that the 'openai' package was not installed in the environment where the script was executed.","severity":"breaking","affected_versions":"all"}],"env_vars":{"optional":[{"name":"TRACELOOP_BASE_URL","note":"Override the OTLP export endpoint. Use this to route traces to any OTel-compatible backend. Examples: Grafana (https://otlp-gateway-<zone>.grafana.net/otlp), Datadog agent (http://localhost:4318), Jaeger (http://localhost:4318). Default: Traceloop cloud."},{"name":"TRACELOOP_HEADERS","note":"Custom headers for the OTLP exporter, in key=value format. Used for auth to external backends. Example: 'Authorization=Bearer <token>'. Multiple headers: comma-separated."}],"required":[{"name":"TRACELOOP_API_KEY","note":"API key for the hosted Traceloop platform. If exporting to a different OTLP backend, this is not required."}]},"last_verified":"2026-05-12T07:31:03.975Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"pip install traceloop-sdk","cause":"The `traceloop-sdk` Python package has not been installed in the current environment.","error":"ModuleNotFoundError: No module named 'traceloop'"},{"fix":"Ensure an OTLP Collector is running and accessible at the specified `TRACELOOP_BASE_URL`, or verify your `TRACELOOP_BASE_URL` and `TRACELOOP_API_KEY` configuration.","cause":"The configured OpenTelemetry Collector or OTLP endpoint (e.g., `http://localhost:4318` by default) is not running or is unreachable.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"fix":"Set the `TRACELOOP_API_KEY` environment variable with a valid API key, or pass it explicitly to `Traceloop.init(api_key='your_api_key')`.","cause":"The `TRACELOOP_API_KEY` environment variable or `api_key` parameter in `Traceloop.init()` is missing or invalid when exporting traces to an OTLP endpoint that requires authentication (like Traceloop Cloud).","error":"Failed to export spans: HTTP status code: 401"},{"fix":"Ensure `Traceloop.init()` is called as early as possible in your application's lifecycle, ideally before any LLM client instances are created or used.","cause":"`Traceloop.init()` was called after the LLM client (e.g., `openai.OpenAI()`, `ChatOpenAI()`) was already initialized, preventing the SDK from correctly patching the library.","error":"traceloop-sdk no traces for openai"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.88,"mem_mb":33.4,"disk_size":"93.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.55,"mem_mb":31.2,"disk_size":"93M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}