Integration

Send OpenTelemetry traces to Rootline

If your agent already emits OpenTelemetry spans, a few lines of exporter configuration send them to Rootline. GenAI and OpenInference semantic-convention spans work as they are.

RootlinePublished

Short answer

Create an ingest key in Rootline Settings, then point your OTLP/HTTP trace exporter at https://rootline.site/v1/traces with the key in an Authorization: Bearer (or X-Rootline-Key) header. Protobuf and JSON are both accepted. GenAI and OpenInference semantic-convention spans work as they are; if your instrumentation sends prompts and answers as log events, also export logs to /v1/logs.

Set up

  1. Create an ingest key. In Rootline, open Settings → OpenTelemetry ingest key and create a key. It starts with rl_ingest_ and is shown once; Rootline stores only a hash of it. Creating a new key replaces the old one.
  2. Configure the exporter. Use the OTLP/HTTP exporter (http/protobuf or http/json). gRPC is not supported.
  3. Send a run. Each trace becomes one run in Rootline. The first trace that arrives marks the source as connected.
  4. Optional: add a feature and customer. Set rootline.feature (or feature) and enduser.id (or user.id) as span or resource attributes to group issues and see cost per customer on Team.

Environment variables

Most OpenTelemetry SDKs read these standard variables. Header values in OTEL_EXPORTER_OTLP_HEADERS must be URL-encoded, so the space after Bearer is written %20:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://rootline.site/v1/tracesOTEL_EXPORTER_OTLP_PROTOCOL=http/protobufOTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<ingest-key>"# Prompts and answers sent as log events (OpenTelemetry GenAI):OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://rootline.site/v1/logs

If your SDK doesn't decode header values, use the header without a space instead: OTEL_EXPORTER_OTLP_HEADERS="x-rootline-key=<ingest-key>". Rootline accepts either.

Python example

With the OpenTelemetry Python SDK and the OTLP/HTTP exporter (opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http). The span attributes follow the GenAI semantic conventions for a tool call:

import json, osfrom opentelemetry import tracefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessorfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporterexporter = OTLPSpanExporter(    endpoint="https://rootline.site/v1/traces",    headers={"Authorization": f"Bearer {os.environ['ROOTLINE_INGEST_KEY']}"},)provider = TracerProvider()provider.add_span_processor(BatchSpanProcessor(exporter))trace.set_tracer_provider(provider)tracer = trace.get_tracer("support-agent")with tracer.start_as_current_span("invoke_agent support-agent") as run:    run.set_attribute("rootline.feature", "refunds")    run.set_attribute("enduser.id", "customer-123")    with tracer.start_as_current_span("execute_tool lookup_order") as tool:        tool.set_attribute("gen_ai.operation.name", "execute_tool")        tool.set_attribute("gen_ai.tool.name", "lookup_order")        tool.set_attribute("gen_ai.tool.call.arguments", json.dumps({"order_id": "A-1042"}))        tool.set_attribute("gen_ai.tool.call.result", json.dumps({"status": "delivered"}))provider.shutdown()   # flush before the process exits

What Rootline reads

ConventionUsed for
OpenTelemetry GenAI (gen_ai.* attributes and log events)Model calls (operation, model, token usage, prompts and answers) and tool calls (gen_ai.tool.name, arguments, result)
OpenInference (openinference.span.kind, input.value, output.value, tool.name)LLM, tool and chain spans from OpenInference instrumentations
Traceloop (traceloop.entity.input / output)Inputs and outputs from Traceloop-style instrumentation
langfuse.* attributesTrace name, user ID, tags and metadata set for Langfuse
rootline.* attributesrootline.feature, rootline.user_id, rootline.tags, rootline.trace_name
enduser.id, user.idThe customer the run belongs to
Span status and exception eventsErrors: a span with status ERROR is a failed step, with the exception type and message as its error

Runs from OpenTelemetry go through the same detection, issue grouping, explanations and cost calculation as runs from Langfuse.

Limits and responses

  • Request body up to 5 MB (compressed), 20 MB after decompression; gzip and deflate are accepted.
  • Up to 120 requests per minute per ingest key; over that, 429 with Retry-After: 60.
  • 401: missing or unknown key. 413: body too large. 415: content type other than application/x-protobuf or application/json, or an unsupported encoding. 400: a body that doesn't parse.
  • Trace data is deleted automatically after 90 days.

Troubleshooting

  • Nothing arrives, no errors: the batch processor exports in the background. Call shutdown() or force_flush() before a short script exits.
  • 401 although the key is right: check the header actually reaches Rootline. In OTEL_EXPORTER_OTLP_HEADERS, write Authorization=Bearer%20<key>, or use x-rootline-key=<key>.
  • Spans go to /v1/traces/v1/traces: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is used as-is, while the generic OTEL_EXPORTER_OTLP_ENDPOINT gets /v1/traces appended. Set either https://rootline.site/v1/traces as the traces endpoint or https://rootline.site as the generic one.
  • Runs show no tool steps: tool spans need gen_ai.operation.name=execute_tool or a gen_ai.tool.name (or the OpenInference equivalents) to count as tool calls.

Official documentation

Send your first trace

Create a free workspace, make an ingest key in Settings and point your exporter at Rootline. Using Langfuse instead? Connect it with an API key pair.

Start debugging free creates a free account, no card. Then open Settings → OpenTelemetry ingest key, create a key and set the exporter variables above. Using Langfuse instead? See the Langfuse setup.