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

# OTel Receiver

> Send real-time coding telemetry to CostHawk via OTLP

Use OTel when you want near real-time coding telemetry in addition to provider admin/cost APIs.

Claude Code and Codex CLI are the primary use cases here: both can export OTLP telemetry when these environment variables are set in your tool/runtime config.

## Endpoint

Set your exporter endpoint to:

```bash theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.costhawk.ai
```

Your exporter appends OTLP paths automatically:

* `/v1/metrics`
* `/v1/logs`
* `/v1/traces` (accepted; trace storage can be enabled later)

## Authentication

Use a CostHawk token in OTLP headers:

```bash theme={null}
OTEL_EXPORTER_OTLP_HEADERS="x-costhawk-key=YOUR_HYBRID_TOKEN"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
```

The token must include `otel:ingest`. If you installed MCP with:

```bash theme={null}
npm exec --yes costhawk@latest -- --login
```

you already have a hybrid token with `otel:ingest` included.

## Example Configuration

```bash theme={null}
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.costhawk.ai
export OTEL_EXPORTER_OTLP_HEADERS="x-costhawk-key=YOUR_HYBRID_TOKEN"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
```

## Best Practices

* Use a dedicated ingest key per environment (dev/staging/prod)
* Rotate ingest keys periodically
* Keep MCP enabled for interactive queries in Claude Code/Codex
* Use Admin API sync for provider-level billing truth; use OTel for real-time activity signals

## Common Troubleshooting

* `401 Unauthorized`: invalid/missing `x-costhawk-key`
* `415 Unsupported Media Type`: exporter not sending OTLP protobuf/json
* No events in dashboard: verify endpoint is `https://ingest.costhawk.ai` (no extra `/v1`)

## Related Concepts

If you are wiring telemetry and trying to decide what data to keep, read <a href="/glossary/opentelemetry">OpenTelemetry</a> for the protocol model and <a href="/glossary/logging">Logging</a> for the request metadata you should preserve alongside traces.

<CardGroup cols={2}>
  <Card title="Admin API Sync" icon="key" href="/integrations/admin-api">
    Low-friction org-level cost visibility
  </Card>

  <Card title="MCP Operations" icon="terminal" href="/mcp-server/operations">
    Verify local MCP + auto-sync health
  </Card>

  <Card title="OpenTelemetry Glossary" icon="chart-line" href="/glossary/opentelemetry">
    Terminology and cost context for OTLP-based telemetry
  </Card>

  <Card title="Logging Glossary" icon="file-lines" href="/glossary/logging">
    What to record so telemetry stays useful for cost analysis
  </Card>
</CardGroup>