OTLP Ingestion

Platform

How telemetry reaches the Traccia platform — HTTP, gRPC, auth, and which clients use which transport.

The Traccia platform ingests OpenTelemetry Protocol (OTLP) data over HTTP and gRPC. The Traccia Python and TypeScript SDKs always use HTTP. Native OpenTelemetry clients (Claude Code, the OTel Collector, custom OTel SDK apps) can use either transport depending on their exporter configuration.

Do not mix SDK and OTel env vars

The Traccia SDK reads TRACCIA_* variables and traccia.toml — not OTEL_EXPORTER_OTLP_*. Setting OTel variables alone will not configure the Traccia SDK. See Configuration for SDK options.

Platform endpoints

Authenticate every request with your ingestion API key: Authorization: Bearer tr_live_…

SignalOTLP/HTTPOTLP/gRPC
Traceshttps://api.traccia.ai/v2/tracesapi.traccia.ai:4317
Metricshttps://api.traccia.ai/v2/metricsapi.traccia.ai:4317
Logshttps://api.traccia.ai/v2/logsapi.traccia.ai:4317
AuthenticationHTTP headergRPC metadata (same Bearer token)

HTTP uses a separate URL per signal. gRPC uses one host and port for traces, metrics, and logs — do not append /v2/traces to the gRPC endpoint.

Which client uses what

ClientTransportConfiguration
Traccia Python SDKOTLP/HTTP onlyTRACCIA_API_KEY, optional TRACCIA_ENDPOINT, or traccia.toml
Traccia TypeScript SDKOTLP/HTTP onlySame TRACCIA_* / traccia.toml keys
Claude CodeHTTP or gRPCOTEL_EXPORTER_OTLP_* in ~/.claude/settings.json
OpenTelemetry CollectorHTTP or gRPCexporters.otlp block in collector YAML
Generic OTel SDK appHTTP or gRPCOTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT, signal-specific endpoints

Traccia SDK (HTTP)

Default platform endpoint when you only set an API key. No OTel environment variables required.

bash
export TRACCIA_API_KEY=tr_live_xxxxxxxxxxxx
# Optional — defaults to https://api.traccia.ai/v2/traces
# export TRACCIA_ENDPOINT=https://api.traccia.ai/v2/traces

Metrics default to https://api.traccia.ai/v2/metrics (derived from the traces endpoint). See SDK Exporters.

Native OTel clients (gRPC)

Use these settings when the application exports through the standard OpenTelemetry SDK or auto-instrumentation — not through the Traccia SDK.

OpenTelemetry SDK / auto-instrumentation
bash
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.traccia.ai:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer tr_live_xxxxxxxxxxxx"

Claude Code

Claude Code can use HTTP (per-signal URLs) or gRPC (single endpoint). See Claude Code integration for copy-paste settings.

Native OTel clients (HTTP)

Some clients prefer explicit per-signal HTTP endpoints instead of gRPC.

OpenTelemetry SDK (HTTP/protobuf)
bash
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.traccia.ai/v2/traces
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.traccia.ai/v2/metrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://api.traccia.ai/v2/logs
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer tr_live_xxxxxxxxxxxx"

OpenTelemetry Collector

Forward from a collector using either protocol. Example gRPC exporter to Traccia:

collector-config.yaml
yaml
exporters:
  otlp/traccia:
    endpoint: api.traccia.ai:4317
    tls:
      insecure: false
    headers:
      Authorization: "Bearer tr_live_xxxxxxxxxxxx"


service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/traccia]

Next Steps

Platform getting started

Connect the Traccia SDK to the platform

Claude Code

HTTP and gRPC setup for Claude Code telemetry

Troubleshooting

Diagnose connectivity and endpoint issues

SDK configuration

TRACCIA_* variables and traccia.toml reference

© 2026 Traccia.