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
- 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. - Configure the exporter. Use the OTLP/HTTP exporter (
http/protobuforhttp/json). gRPC is not supported. - Send a run. Each trace becomes one run in Rootline. The first trace that arrives marks the source as connected.
- Optional: add a feature and customer. Set
rootline.feature(orfeature) andenduser.id(oruser.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
| Convention | Used 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.* attributes | Trace name, user ID, tags and metadata set for Langfuse |
rootline.* attributes | rootline.feature, rootline.user_id, rootline.tags, rootline.trace_name |
enduser.id, user.id | The customer the run belongs to |
Span status and exception events | Errors: 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;
gzipanddeflateare accepted. - Up to 120 requests per minute per ingest key; over that,
429withRetry-After: 60. 401: missing or unknown key.413: body too large.415: content type other thanapplication/x-protobuforapplication/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()orforce_flush()before a short script exits. - 401 although the key is right: check the header actually reaches Rootline. In
OTEL_EXPORTER_OTLP_HEADERS, writeAuthorization=Bearer%20<key>, or usex-rootline-key=<key>. - Spans go to
/v1/traces/v1/traces:OTEL_EXPORTER_OTLP_TRACES_ENDPOINTis used as-is, while the genericOTEL_EXPORTER_OTLP_ENDPOINTgets/v1/tracesappended. Set eitherhttps://rootline.site/v1/tracesas the traces endpoint orhttps://rootline.siteas the generic one. - Runs show no tool steps: tool spans need
gen_ai.operation.name=execute_toolor agen_ai.tool.name(or the OpenInference equivalents) to count as tool calls.
Official documentation
- OTLP exporter configuration (endpoints, headers, protocol)opentelemetry.io
- OpenTelemetry Protocol Exporter specificationopentelemetry.io
- OpenTelemetry Python exportersopentelemetry.io
- Semantic conventions for generative AI spansopentelemetry.io
- OpenInference specification and instrumentationsgithub.com