---
name: agentbyte-otel-tracing
description: Guide for enabling OpenTelemetry (OTel) instrumentation in Agentbyte. Use this when connecting agents to Jaeger, tracing LLM calls, or aggregating multi-turn token metrics.
---

Use this skill to add observability to your agents.

## Pattern 1: Automatic Instrumentation
```python
import os
# MUST occur before any agentbyte imports
os.environ["AGENTBYTE_ENABLE_OTEL"] = "true"
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4318"
os.environ["OTEL_SERVICE_NAME"] = "my-agent-service"

from agentbyte.middleware import auto_instrument
auto_instrument()

# Agents will now automatically create traces in Jaeger
```

## Pattern 2: Manual Instrumentation
```python
from agentbyte.middleware import OTelMiddleware

agent = Agent(
    name="my-traced-agent",
    ...,
    middlewares=[OTelMiddleware()]
)
```

## Environment Config
| Variable | Purpose |
|---|---|
| `AGENTBYTE_OTEL_CAPTURE_CONTENT` | Capture full message text in spans |
| `AGENTBYTE_OTEL_CAPTURE_USAGE` | Aggregate tokens, calls, and cost in root span |

## Guardrails
- **Import Order:** Ensure OTel environment variables are set before the first `agentbyte` import.
- **Jaeger:** Ensure your OTLP collector endpoint is active.
- **PII:** Be careful with `AGENTBYTE_OTEL_CAPTURE_CONTENT` in production environments.
