Start
Lilium
SDKs

OpenTelemetry

OTLP ingest endpoint, authentication, and the span attributes Lilium recognizes.

Updated August 4, 2026

Lilium accepts OTLP directly. If you already run OpenTelemetry, you do not need a second instrumentation layer.

#Endpoint and authentication

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.lilium.ai/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer ${LILIUM_API_KEY}

Lilium accepts OTLP over HTTP as protobuf or JSON. It does not expose an OTLP gRPC listener.

#Recognized attributes

Spans are stored regardless of their attributes. These are the ones that get enriched into model, cost, and agent grouping.

AttributeTypePurpose
gen_ai.provider.namestringProvider, for example openai
gen_ai.request.modelstringModel id, used for cost lookup
gen_ai.usage.input_tokensintPrompt tokens
gen_ai.usage.output_tokensintCompletion tokens
gen_ai.usage.cache_read.input_tokensintBilled at the cached rate
lilium.agent_idstringStable logical agent identity, groups runs
lilium.agent_rolestringOptional classification shared by related agents
lilium.instruction_component_version_idstringLinks a run to an instruction version

#Sampling

Use a parent-based sampler. Span-level sampling produces traces with missing parents, and a run with holes in it cannot be replayed.

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.25

#Running alongside an existing backend

Add Lilium as an additional exporter rather than replacing the current one. Spans are delivered to both.

service:
  pipelines:
    traces:
      exporters: [otlphttp/lilium, otlp/existing]

Full walkthrough: Send OpenTelemetry spans to Lilium.