Start
Lilium
Guides
Connect

Send OpenTelemetry spans to Lilium

Point an existing OTLP pipeline at Lilium and keep the collector, sampling, and exporters you already run.

August 4, 2026Intermediate15 minutes

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

  1. From the Collector if you already run one. Central configuration, no application redeploy.

  2. 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.

AttributePurpose
gen_ai.provider.nameProvider, for example openai or anthropic
gen_ai.request.modelModel identifier used for cost attribution
gen_ai.usage.input_tokensPrompt tokens
gen_ai.usage.output_tokensCompletion tokens
gen_ai.usage.cache_read.input_tokensCached prompt tokens
lilium.agent_idStable logical agent identity, used to group runs
lilium.agent_roleOptional 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.