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

# Telemetry

> Built-in OpenTelemetry support for spans, metrics, and session cost tracking.

<Note>
  **OpenTelemetry** — Set `OTEL_EXPORTER_OTLP_ENDPOINT` and telemetry is on. Leave unset for zero overhead.
</Note>

## Environment Variables

| Variable                      | Description                                                                                                         | Default     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP/HTTP collector URL (e.g. [http://localhost:4318](http://localhost:4318)). When set, telemetry is auto-enabled. | unset = off |
| `GITAGENT_OTEL_ENABLED`       | Set to false to force-disable telemetry even when endpoint is set.                                                  | auto        |
| `OTEL_SERVICE_NAME`           | service.name resource attribute.                                                                                    | gitagent    |
| `OTEL_SERVICE_VERSION`        | service.version resource attribute.                                                                                 | unset       |
| `OTEL_EXPORTER_OTLP_HEADERS`  | Comma-separated key=value pairs, no quotes (e.g. Authorization=Bearer xyz,x-tenant=abc).                            | unset       |
| `OTEL_TRACES_EXPORTER`        | Set to console to print spans to stdout — no collector needed.                                                      | unset       |

## Spans Emitted

| Span                     | Kind     | Attributes                                                                                                           |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `gitagent.agent.session` | INTERNAL | gitagent.entry, gitagent.cost\_usd, gitagent.session.duration\_ms                                                    |
| `gitagent.tool.execute`  | INTERNAL | tool.name, tool.call\_id, tool.status, tool.error\_message                                                           |
| `gen_ai.chat`            | CLIENT   | gen\_ai.system, gen\_ai.request.model, gen\_ai.usage.input\_tokens, gen\_ai.usage.output\_tokens, gitagent.cost\_usd |
| `HTTP …`                 | CLIENT   | URL, status code, duration (auto via instrumentation-undici)                                                         |

## Metrics Emitted

| Metric                             | Type      | Description                            |
| ---------------------------------- | --------- | -------------------------------------- |
| `gitagent.tool.calls`              | counter   | Tool executions, labelled by tool.name |
| `gitagent.tool.duration_ms`        | histogram | Tool execution duration                |
| `gitagent.session.duration_ms`     | histogram | Session duration                       |
| `gitagent.session.cost_usd`        | counter   | Cumulative session cost in USD         |
| `gen_ai.client.token.usage`        | counter   | Token usage by model and token type    |
| `gen_ai.client.operation.duration` | histogram | LLM call duration                      |

## Jaeger Quickstart

```bash theme={null}
docker run -d --name jaeger \
  -p 16686:16686 -p 4318:4318 \
  jaegertracing/all-in-one:latest

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent
# Open http://localhost:16686
```

## Console Output (No Collector)

```bash theme={null}
OTEL_TRACES_EXPORTER=console gitagent --voice --dir ~/assistant
```

<Warning>
  `OTEL_TRACES_EXPORTER=console` is useful for local debugging only — it prints every span to stdout and will flood your terminal in long-running sessions.
</Warning>

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="code" href="/open-source/gitagent/sdk/overview">
    Full API reference for query(), tool(), buildTool(), and hooks
  </Card>

  <Card title="Utilities" icon="wrench" href="/open-source/gitagent/sdk/utilities">
    Cost tracking helpers that back the gitagent.session.cost\_usd metric
  </Card>

  <Card title="Environment Variables" icon="gear" href="/open-source/gitagent/configuration/environment-variables">
    Full list of environment variables GitAgent reads
  </Card>

  <Card title="Compliance & Audit" icon="shield-check" href="/open-source/gitagent/enterprise/compliance">
    Pair telemetry with the git-native audit trail for full observability
  </Card>
</CardGroup>