Start free
Menu

Product

Start free
Docs menu

OpenTelemetry setup

Traza Cloud accepts OTLP over HTTP, protobuf or JSON, at https://api.trazadb.com/v1/traces. Any OpenTelemetry SDK, Collector or exporter can send to it with an ingest key:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.trazadb.com
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20$TRAZA_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # or http/json
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip         # optional

The SDK appends /v1/traces to the endpoint. The space in the header value is written %20, as the OpenTelemetry environment-variable format requires. gRPC is not served; every SDK supports http/protobuf.

Spans instrumented with OpenLLMetry, OpenInference or the OpenTelemetry GenAI conventions arrive with sessions, models, providers and token counts recognized, with no attribute renaming. The full list of keys and their precedence is in LLM semantics.

Three things that decide whether it works

1. Put a session id on every span of a run. A run is a session id, or one trace when there is none. Guard holds runs to limits, and Replay replays runs, so a run must be what you mean by one. Membership is decided per span: if the root span carries session.id and its children do not, the children are not in the session. Use session.id, gen_ai.conversation.id, or OpenLLMetry’s session_id association property.

2. Record content if you want to replay. A replay serves recorded model answers, so it needs prompts and completions on the spans. OpenLLMetry records them by default (TRACELOOP_TRACE_CONTENT left unset or true). A model step without a recorded answer refuses the replay and names the step.

3. Resource attributes, other than service.name, are not stored. The engine reads service.name (and traza.tenant) from the resource and drops the rest: deployment.environment, service.version, host.name and so on. Put anything you want to filter on onto the spans themselves, with a span processor or a Collector transform. Scope and span attributes are kept.

Do not set traza.tenant. Your key already binds every span to your project’s tenant; a span that names a different one fails the whole export with 400.

How fast verdicts arrive

The batch span processor exports every five seconds by default, so an agent can take several steps between crossing a limit and its exporter hearing about it. For a stop that lands before the next step, have the agent ask the pre-call check instead of relying on acknowledgements.

At the cap

When the organization reaches its monthly spans with overage off, the engine answers exports with 429 and Retry-After. OTLP exporters back off and retry. Reads and exports keep working. See Billing.

By SDK