> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt > Use this file to discover all available pages before exploring further. # OpenTelemetry Tracing > Export Cognee traces to OpenTelemetry backends. Cognee ships a built-in OpenTelemetry (OTEL) tracing layer. It creates OTEL spans for every `@observe`-decorated function and can export them to any OTLP-compatible backend — Grafana Tempo, Jaeger, Dash0, Datadog, Honeycomb, and others. ## How It Works In Cognee core, the `@observe` decorator maps only to OpenTelemetry. When tracing is enabled, it wraps each decorated function in an OTEL span; when tracing is disabled it is a no-op that passes the call straight through. There is no built-in Sentry or Langfuse backend to configure. | Feature | OTEL | | ---------------- | ------------------------------- | | Enabled by | `COGNEE_TRACING_ENABLED=true` | | Data destination | Any OTLP backend (or in-memory) | | Span type | OTEL span | ## Installation OTEL support requires OpenTelemetry dependencies. Install them with the `tracing` extra: ```bash theme={null} pip install 'cognee[tracing]' ``` The extra installs `opentelemetry-sdk` plus the OTLP gRPC and HTTP exporters. No additional packages are needed for the in-memory buffer. ## Quick Start ### 1. Enable tracing via environment variable ```dotenv theme={null} COGNEE_TRACING_ENABLED=true ``` That's all that is required to activate in-memory span collection. Spans are buffered in a ring buffer (last 50 traces) and can be read programmatically. ### 2. Export to an OTLP backend (optional) Point cognee at an OTLP-compatible collector: ```dotenv theme={null} COGNEE_TRACING_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4317 OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer OTEL_SERVICE_NAME=my-cognee-service # default: "cognee" ``` ```dotenv theme={null} COGNEE_TRACING_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic OTEL_SERVICE_NAME=cognee ``` ```dotenv theme={null} COGNEE_TRACING_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 OTEL_SERVICE_NAME=cognee ``` Start Jaeger with the all-in-one image and its OTLP gRPC port (`4317`) exposed. ```dotenv theme={null} COGNEE_TRACING_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=https://ingress.eu-west-1.aws.dash0.com:4317 OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer OTEL_SERVICE_NAME=cognee ``` ### 3. Using an auto-instrumentation agent If you launch your application with `opentelemetry-instrument` or an APM agent (Datadog, Dash0, Elastic), it configures its own `TracerProvider` before your code runs. Cognee detects this and **attaches its in-memory exporter to the existing provider** instead of creating a new one — so cognee spans appear inside your existing trace alongside other spans from your application. ```bash theme={null} opentelemetry-instrument python my_app.py ``` No additional Cognee configuration is required beyond enabling tracing. Your external agent or APM still needs its own exporter configuration if you want spans sent to a remote backend; in this mode Cognee attaches its in-memory exporter to the existing provider so `get_last_trace()` and related helpers still work. ## Programmatic API You can also control tracing from Python: ```python theme={null} from cognee.modules.observability.trace_context import ( enable_tracing, disable_tracing, is_tracing_enabled, get_last_trace, get_all_traces, clear_traces, ) # Enable with optional console output for debugging enable_tracing(console_output=True) # ... run cognee operations ... trace = get_last_trace() if trace: print(trace.summary()) # {'operation': 'cognee.observe.main', 'total_duration_ms': 1234.5, # 'span_count': 12, 'breakdown': {...}, 'errors': []} for span in trace.spans(): print(span["name"], span["duration_ms"]) disable_tracing() ``` ### `CogneeTrace` API | Method | Returns | Description | | ----------- | ------------ | ---------------------------------------------------------- | | `spans()` | `list[dict]` | Flat list of span dicts sorted by start time | | `summary()` | `dict` | Root operation, total duration, per-span breakdown, errors | | `tree()` | `dict` | Hierarchical span tree as nested dicts | Each span dict contains: `name`, `trace_id`, `span_id`, `parent_span_id`, `start_time_ns`, `end_time_ns`, `duration_ms`, `status`, `attributes`. ## Span Attributes Cognee sets the following semantic attributes on spans: | Attribute | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cognee.span.category` | Value of `as_type=` passed to `@observe` | | `cognee.llm.model` | LLM model name | | `cognee.llm.provider` | LLM provider | | `cognee.pipeline.stage` | Pipeline stage that issued the LLM call — `extraction`, `summarization`, or `query`; present on LLM spans made within a stage boundary regardless of whether [per-stage routing](/setup-configuration/llm-providers#per-stage-model-routing) overrides are set | | `cognee.search.type` | Search type enum value used by retrieval | | `cognee.search.query` | Search query text used by retrieval | | `cognee.pipeline.task_name` | Pipeline task name | | `cognee.vector.collection` | Vector collection name | | `cognee.db.system` | Database backend identifier | ## Environment Variables Reference | Variable | Default | Description | | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `COGNEE_TRACING_ENABLED` | `false` | Set to `true` to enable OTEL tracing | | `OTEL_SERVICE_NAME` | `cognee` | Service name attached to all spans | | `OTEL_EXPORTER_OTLP_ENDPOINT` | *(none)* | OTLP collector endpoint. Cognee currently prefers the OTLP gRPC exporter when both gRPC and HTTP exporters are installed. | | `OTEL_EXPORTER_OTLP_HEADERS` | *(none)* | Auth headers (e.g. `Authorization=Bearer `) | | `OTEL_RESOURCE_ATTRIBUTES` | *(none)* | Comma-separated extra resource attributes attached to the tracer provider resource (e.g. `service.namespace=my-team,service.version=1.0,deployment.environment.name=prod`). Read by the OpenTelemetry SDK itself. | Cognee reads `OTEL_EXPORTER_OTLP_ENDPOINT` directly and passes it to the OTLP exporter. Other standard `OTEL_EXPORTER_OTLP_*` settings such as headers are honored by the underlying exporter library. `OTEL_RESOURCE_ATTRIBUTES` is read by the OpenTelemetry SDK and merged into the provider resource. When Cognee creates its own `TracerProvider`, that includes `service.name`, `service.version`, and `deployment.environment`; in auto-instrumented setups, the external provider's resource configuration applies instead. Cognee currently tries the OTLP gRPC exporter first and only falls back to the OTLP HTTP exporter if the gRPC exporter package is unavailable. Because the shipped extras install both exporters, the practical default is gRPC. Use a gRPC-compatible OTLP endpoint unless you intentionally run with only the HTTP exporter installed. If you are running Cognee as an HTTP server and want to inspect traces or pipeline activity over HTTP, see **Activity and Observability** in [Deploy REST API Server](/guides/deploy-rest-api-server#activity-and-observability).