Tracing

Archestra exports OpenTelemetry traces and backend logs to any OTLP-compatible backend, such as Tempo, Jaeger, Honeycomb, or Grafana Cloud. Each LLM call and MCP tool call is a span that carries the agent, user, teams, model, token counts, and cost. Span names and gen_ai.* attributes follow the OpenTelemetry GenAI semantic conventions. Attributes the conventions do not cover use the archestra.* prefix.

Configuration

Set ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT to your collector's base URL. Archestra exports OTLP over HTTP (port 4318 by convention), not gRPC (4317).

ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

The default is http://localhost:4318. Archestra appends /v1/traces for traces and /v1/logs for logs, and reports the service name Archestra.

The bearer token wins when both are set. Basic authentication needs both the username and the password.

Restart the backend after you change these variables. To check the export, send a chat message, then search your tracing backend for service Archestra and a span named chat <agent name>.

Logs

Archestra sends its backend logs to the same collector. Each record carries trace_id and span_id, plus session_id inside an agent session. Your tracing backend uses them to jump from a span to its logs.

Content Capture

Archestra records message and tool content as span events:

Each event is truncated to 10,000 characters; ARCHESTRA_OTEL_CONTENT_MAX_LENGTH changes the limit.

Capture is on by default. Set ARCHESTRA_OTEL_CAPTURE_CONTENT=false to leave the events out. With content encryption on, capture is off by default. This keeps encrypted content from reaching your telemetry backend as plaintext. ARCHESTRA_OTEL_CAPTURE_CONTENT=true turns it back on.

Verbose Tracing

By default, Archestra exports only agent spans: LLM calls, MCP tool calls, agent runs, and Knowledge Base calls. Set ARCHESTRA_OTEL_VERBOSE_TRACING=true to also export HTTP routes, outgoing HTTP calls, database queries, and DNS lookups. Use it for debugging. It multiplies span volume.

Trace Structure

An agent run is one trace. Its root span groups the LLM calls and tool calls of that turn:

chat Support Bot                  root span (SpanKind.SERVER)
├── chat claude-sonnet-4-5        LLM call (SpanKind.CLIENT)
├── execute_tool github__list_repos
└── chat claude-sonnet-4-5        follow-up LLM call with the tool result

The root span's route.category tells you how the agent was invoked:

Calls from your own applications to the LLM Proxy (route.category=llm-proxy) and the MCP Gateway (route.category=mcp-gateway) start their own traces. To group them, send the same X-Archestra-Session-Id header with each request. Archestra records it as gen_ai.conversation.id.

Archestra also emits:

• context_compaction auto and context_compaction manual spans when chat history is compacted.
• send_completion spans when an Agent Runtime run sends its final reply to ChatOps or email.
• Spans from the Code Sandbox under the service name archestra-sandbox-rs, nested under the tool call that ran the command.

LLM Spans

Each LLM call is a SpanKind.CLIENT span named {operation} {model}, for example chat gpt-4o-mini or generate_content gemini-2.5-flash. Knowledge Base embedding calls are named embedding {model}.

gen_ai.usage.input_tokens includes cached tokens. The llm_tokens_total{type="input"} metric does not. It reads lower when prompt caching is active.

Knowledge Base embedding and reranking calls have no agent attributes. Their archestra.trigger.source is knowledge:embedding or knowledge:reranker.

MCP Tool Call Spans

Each tool call through the MCP Gateway is a span named execute_tool {tool_name}, for example execute_tool github__list_repos.

A blocked call never runs. Its span records the policy decision with span status ERROR and the reason as the status message.

Identity Attributes

LLM spans, MCP spans, and agent run root spans carry who made the request:

The LLM Proxy has no labels or teams. Filter its traffic by the archestra.user.team.*, archestra.external_agent_id, or archestra.app.name attributes.