OTEL Additions for Trailsense

Learn which extra attributes and trace conventions to add on top of standard OpenTelemetry data so Trailsense can build sessions and conversation turns.

Standard OTEL instrumentation already gives Trailsense most of the raw execution detail: trace IDs, span IDs, timing, nesting, and the attributes emitted by your framework or instrumentation library.

To render that data as readable agent conversations, Trailsense needs a small amount of extra structure on top of regular OTEL data. The examples below use Python with OpenLLMetry, but the same conventions apply to any OTEL-compatible library.

What You Need To Add

Endpoint and authentication

Trailsense accepts traces at http://ingest.trailsense.ai/v1/traces over OTLP HTTP/Protobuf.

Requests must include this header:

Authorization: Bearer <TRAILSENSE_API_TOKEN>

Generate TRAILSENSE_API_TOKEN in Settings → API Keys.

We are located in Central Europe (Germany).

A stable conversation ID

Trailsense groups related traces into a session using the gen_ai.conversation.id attribute. With OpenLLMetry, you can set this value with the @conversation(conversation_id="session-id") decorator. Apply the decorator to the top-level function in the call tree so all spans created for this agent response have the same conversation ID.

Use the same conversation ID for every turn in the same chat or session. When Trailsense detects a new conversation ID, it creates a new session automatically.

One trace per user-visible turn

A single trace should represent one conversation turn or one agent invocation that produces a user-visible response.

This keeps the session view readable: one trace in Trailsense maps to one turn in the conversation. This is usually the case for most of the instrumentation libraries, so you don't need to change anything here.

Root-span input and output

On the root span of that trace, add these two custom attributes:

trailsense.input: the user request or human-facing input for the turn
trailsense.output: the final agent response shown to the user

Trailsense uses these attributes to build the conversation view. Child spans can still carry the detailed OTEL data for model calls, tools, retrieval, or orchestration.

Next Steps

Ready to implement this? Follow the Quickstart with OpenLLMetry to see a complete working example.