---
name: agentbyte-otel-tracing
description: Guide for enabling OpenTelemetry tracing in Agentbyte for agents, orchestrators, and workflows. Use this when adding Jaeger/OTLP observability, tracing model or tool calls, or validating runtime span hierarchies.
license: MIT
---

Use this skill when adding OpenTelemetry-based observability to Agentbyte code.

## Inputs to confirm
- Whether tracing should cover agents only, or also orchestrators and workflows
- Which OTLP endpoint and service name should be used
- Whether prompt/response content may be captured safely
- Whether metrics are needed or traces alone are sufficient

## Pattern 1: Environment-First Auto-Instrumentation

Set environment variables before the first `agentbyte` import.

```python
import os

os.environ["AGENTBYTE_ENABLE_OTEL"] = "true"
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4318"
os.environ["OTEL_SERVICE_NAME"] = "my-agentbyte-service"

# Optional debugging / privacy-sensitive flags
os.environ["AGENTBYTE_OTEL_CAPTURE_CONTENT"] = "false"
os.environ["OTEL_METRICS_ENABLED"] = "false"

from agentbyte import Agent
```

This is the preferred path because importing package root already triggers Agentbyte's OTel auto-instrumentation when `AGENTBYTE_ENABLE_OTEL=true`.

What auto-instrumentation gives you:
- agent root spans
- child `chat <model>` spans
- child `tool <name>` spans
- orchestration root spans
- workflow root and workflow-step spans

## Pattern 2: Manual Agent Middleware

Use this only when you do not want global auto-instrumentation and need opt-in tracing on specific agents.

```python
from agentbyte import Agent
from agentbyte.middleware import OTelMiddleware

agent = Agent(
    name="traced_agent",
    ...,
    middlewares=[OTelMiddleware()],
)
```

## What Gets Traced

### Agents
- root span: `agent <name>`
- child spans for model calls
- child spans for tool calls

### Orchestrators
- root span: `orchestration <PatternName>`
- span attributes such as:
  - `agentbyte.orchestration.pattern`
  - `agentbyte.orchestration.agent_count`
  - `agentbyte.orchestration.iterations`
  - `agentbyte.orchestration.message_count`
  - `agentbyte.orchestration.stop_reason`

### Workflows
- root span: `workflow <workflow_name>`
- child spans: `workflow step <step_id>`
- embedded `AgentbyteAgentStep` executions can contain nested agent/chat/tool spans beneath the workflow step span

## Jaeger / OTLP Setup

For local Jaeger all-in-one, use an OTLP HTTP endpoint such as:

```python
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4318"
```

Agentbyte appends `/v1/traces` internally for the trace exporter, so pass the base OTLP endpoint, not the full traces path.

## Useful Environment Variables

| Variable | Purpose |
|---|---|
| `AGENTBYTE_ENABLE_OTEL` | Enable Agentbyte tracing |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP HTTP endpoint |
| `OTEL_SERVICE_NAME` | Service name shown in traces |
| `OTEL_METRICS_ENABLED` | Enable metrics export when supported |
| `AGENTBYTE_OTEL_CAPTURE_CONTENT` | Opt in to prompt/response content capture |

## Validation Approach
- Run a simple traced agent first to verify exporter setup.
- Then verify orchestrator/workflow traces if those surfaces are in scope.
- Check the trace hierarchy, not just whether any span appears.
- For local Jaeger setups, confirm the service name is visible in the UI before debugging deeper instrumentation issues.

## Guardrails
- Set OTel environment variables before the first `agentbyte` import.
- Prefer auto-instrumentation unless you specifically need per-agent manual control.
- Treat `AGENTBYTE_OTEL_CAPTURE_CONTENT` as opt-in only; it may expose sensitive prompts, completions, or tool arguments.
- Do not assume Jaeger supports metrics by default; traces are the primary integration path.
- If local proxy settings interfere with `localhost`, clear or bypass them for the OTLP endpoint.
