> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticenv.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> Enable OpenTelemetry export and access run-level agent telemetry data

The SDK has two observability layers:

1. **OpenTelemetry export** — distributed traces, metrics, and structured logs pushed to any OTLP-compatible backend (Jaeger, Grafana, Datadog, etc.). Configured once at agent creation.
2. **Run-level telemetry** — `AgentTelemetry` on every `AgentRunResult`. LLM round counts, tool breakdowns, and storage operation summaries returned inline with each result. No configuration required.

## Enable OpenTelemetry

Pass [`WithObservabilityConfig`](/getting-started/configuration) to wire traces, metrics, and logs in one block:

```go theme={null}
a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithObservabilityConfig(&agent.ObservabilityConfig{
        Endpoint: "localhost:4317",        // gRPC OTLP endpoint
        Protocol: agent.OTLPProtocolGRPC,  // or OTLPProtocolHTTP
        Insecure: true,                    // dev only — omit for TLS
    }),
    agent.WithLogLevel("info"),
)
defer a.Close() // flushes all OTLP exporters — required
```

Use the **same** `WithObservabilityConfig` on `NewAgent` and `NewAgentWorker`. LLM calls and tool executions run on the worker process — without matching config those spans and metrics are dropped.

Opt out of individual signals:

```go theme={null}
agent.WithObservabilityConfig(&agent.ObservabilityConfig{
    Endpoint:       "localhost:4317",
    DisableTraces:  false, // default — enabled
    DisableMetrics: false, // default — enabled
    DisableLogs:    false, // default — enabled
})
```

See [Tracing](/observability/tracing), [Metrics](/observability/metrics), and [Logs](/observability/logs) for per-signal details and collector configuration.

***

## Run-level telemetry (`AgentTelemetry`)

Every completed run populates [`AgentTelemetry`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/agent#AgentTelemetry) on [`AgentRunResult`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/agent#AgentRunResult). This is **run-level behavioral data** returned with the result — separate from OTLP export. Use it for app-side logging, dashboards, and eval harness assertions.

## Structure

`AgentTelemetry` has three sections:

| Section | Tracks |
| - | - |
| `Run` | Orchestration lifecycle — timing, LLM round count, finish reason |
| `Tools` | Tool invocation totals, failures, per-tool breakdown |
| `Storage` | Retriever searches and memory recall/store operations |

Fields are **zero** when the corresponding feature is not configured (no retriever → retriever counts are 0; no memory → memory counts are 0).

## Run telemetry

| Field | Description |
| - | - |
| `StartedAt` | Run start time |
| `CompletedAt` | Run completion time |
| `TotalLLMCalls` | LLM calls across all tool rounds |
| `FinishReason` | `complete` or `max_iterations` |

`max_iterations` means the run hit [`WithMaxIterations`](/getting-started/configuration) before producing a final answer.

## Tool telemetry

| Field | Description |
| - | - |
| `TotalCalls` | Total tool invocations |
| `FailedCalls` | Tools that returned an error — excludes approval-denied and unauthorized cases |
| `Breakdown` | Per-tool invocation counts — key is tool name |
| `FailedBreakdown` | Per-tool failure counts |

Covers native tools, MCP tools, retriever tools, and sub-agent delegation tools.

## Storage telemetry

| Field | Description |
| - | - |
| `TotalRetrieverSearches` | Total RAG searches |
| `FailedRetrieverSearches` | Failed retriever searches |
| `PrefetchSearches` | Searches from prefetch or hybrid mode |
| `AgenticSearches` | Searches from agentic or hybrid mode (LLM-initiated) |
| `TotalMemoryRecalls` | Memory load operations before the run |
| `FailedMemoryRecalls` | Failed recall operations |
| `TotalMemoryStores` | Memory persist operations |
| `FailedMemoryStores` | Failed store operations |

See [Retrieval](/features/retrieval) and [Memory](/features/memory) for when each counter increments.

## Run

```go theme={null}
agentRun, err := a.Run(ctx, "What's the weather in Tokyo?", nil)
if err != nil {
    return err
}
result, err := agentRun.Get(ctx)
if err != nil {
    return err
}

t := result.Telemetry
fmt.Printf("llm_calls=%d finish=%s\n", t.Run.TotalLLMCalls, t.Run.FinishReason)
fmt.Printf("tool_calls=%d failed=%d\n", t.Tools.TotalCalls, t.Tools.FailedCalls)
fmt.Printf("retriever=%d prefetch=%d agentic=%d\n",
    t.Storage.TotalRetrieverSearches,
    t.Storage.PrefetchSearches,
    t.Storage.AgenticSearches)
fmt.Printf("memory recall=%d store=%d\n",
    t.Storage.TotalMemoryRecalls,
    t.Storage.TotalMemoryStores)
```

Example: [Simple Agent](/examples/simple-agent) · [Observability](/examples/observability).

## Stream

Telemetry is on `Result.Telemetry` inside the `AgentEventTypeRunFinished` event:

```go theme={null}
for ev := range eventCh {
    if ev.Type() != agent.AgentEventTypeRunFinished {
        continue
    }
    finished, ok := ev.(*agent.AgentRunFinishedEvent)
    if !ok || finished.Result == nil || finished.Result.Telemetry == nil {
        continue
    }
    fmt.Println(finished.Result.Telemetry.Run.TotalLLMCalls)
}
```

## Token usage vs telemetry

| Data | Where | Purpose |
| - | - | - |
| **Telemetry** | `Result.Telemetry` | Run behavior — LLM round count, tool breakdown, storage ops |
| **Token usage** | `Result.LLMUsage` | Aggregate token counts for cost and quota tracking |

See [Token Usage](/features/token-usage).

## Eval harness

Telemetry fields are designed for eval assertions — total LLM calls, tool breakdown, finish reason, and storage counts. See [Eval Harness](/testing/eval-harness).

## Example

<CardGroup cols={2}>
  <Card title="Telemetry" icon="play" href="/examples/simple-agent" horizontal>
    SHOW\_TELEMETRY on run results
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Metrics" icon="chart-line" href="/observability/metrics" horizontal>
    OTLP counters and histograms
  </Card>

  <Card title="Tracing" icon="route" href="/observability/tracing" horizontal>
    Distributed spans per LLM and tool call
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.