Skip to main content

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.

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: 
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: 
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: 
npm exec --yes costhawk@latest -- --login
you already have a hybrid token with otel:ingest included.

​
Example Configuration

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)
If you are wiring telemetry and trying to decide what data to keep, read OpenTelemetry for the protocol model and Logging for the request metadata you should preserve alongside traces.

Admin API Sync

Low-friction org-level cost visibility

MCP Operations

Verify local MCP + auto-sync health

OpenTelemetry Glossary

Terminology and cost context for OTLP-based telemetry

Logging Glossary

What to record so telemetry stays useful for cost analysis