Send OpenTelemetry spans to Lilium
Point an existing OTLP pipeline at Lilium and keep the collector, sampling, and exporters you already run.
Before you start
- An OpenTelemetry SDK or Collector already running
- An Lilium project API key
- Outbound HTTPS to the ingest endpoint
If your services already emit OpenTelemetry, you do not need a second instrumentation layer. Lilium accepts OTLP directly and reconstructs agent lineage from standard span attributes.
#Choose where to export from
-
From the Collector if you already run one. Central configuration, no application redeploy.
-
From the application SDK if you do not. One fewer moving part, at the cost of configuring each service.
#Configure the Collector
Add Lilium as an exporter and reference it in your traces pipeline. Existing exporters stay exactly as they are.
exporters:
otlphttp/lilium:
endpoint: https://api.lilium.ai
headers:
authorization: Bearer ${env:LILIUM_API_KEY}
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/lilium, otlp/existing]#Configure the application SDK
If you export straight from the process, point the standard environment variables at the ingest endpoint. No code change is required.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.lilium.ai/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer ${LILIUM_API_KEY}
OTEL_SERVICE_NAME=support-agent#Emit the attributes that carry meaning
Generic spans arrive as generic spans. To get model, cost, and agent grouping, set the semantic convention attributes on the spans your agent produces.
| Attribute | Purpose |
|---|---|
gen_ai.provider.name | Provider, for example openai or anthropic |
gen_ai.request.model | Model identifier used for cost attribution |
gen_ai.usage.input_tokens | Prompt tokens |
gen_ai.usage.output_tokens | Completion tokens |
gen_ai.usage.cache_read.input_tokens | Cached prompt tokens |
lilium.agent_id | Stable logical agent identity, used to group runs |
lilium.agent_role | Optional classification shared by related agents |
Spans without these attributes are still stored and searchable. They simply are not enriched.
#Keep lineage intact under sampling
Use a parent-based sampler. Span-level sampling produces traces with holes in them, and a trace with a missing parent cannot be replayed.
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.25#Verify ingest
Send one trace, then check that the run appears with its full hierarchy rather than as a set of unrelated spans. Flat arrival almost always means context is not propagating across an async boundary in the producing service.
#Where to go next
The OpenTelemetry reference lists every recognized attribute. If you would rather use the native SDK, start with the OpenAI guide.
Common questions
No. Add Lilium as an additional exporter in the same pipeline and spans are delivered to both destinations.
Lilium accepts OTLP over HTTP as protobuf or JSON. It does not expose an OTLP gRPC listener.
They are stored and searchable, but only spans carrying gen_ai attributes are enriched with model and cost fields.
Only if you sample at the span level. Use a parent-based sampler so a sampled trace keeps every span in its hierarchy.