Skip to main content
Tilde records each agent invocation as an OpenTelemetry trace. A trace shows the model calls and tool calls the agent made, how long each took, what it cost in tokens, and where it failed. The Tilde SDK sets up tracing for you. Traces appear in the agent’s Tracing tab without any agent configuration.

How traces reach Tilde

Trace flow from the agent SDK through the Tilde gateway's embedded receiver to Langfuse, and back to the Tilde UI
Click to zoom
1

The SDK exports spans

The SDK uploads OTLP batches to the gateway, authenticated with the invocation token. Only a live invocation can upload traces, so an agent cannot write traces for work it was not given.
2

The gateway verifies and queues them

The gateway’s embedded OpenTelemetry receiver validates each batch, and stamps it with the verified agent, run, invocation, and thread.
3

Tilde delivers them to Langfuse

The gateway delivers each batch to your self-hosted Langfuse, which is the system of record for traces. Delivery retries until it succeeds.
Traces need a configured Langfuse integration. Without one, Tilde authenticates and validates trace uploads, then discards them.

Read traces in Tilde

Open the agent’s Tracing tab. Tilde has a native trace viewer, so operators do not need a Langfuse login.
  • The observations grid lists model and tool calls, with filters for session, run, and time.
  • The waterfall shows one trace’s spans, nested by parent, and coloured by latency.
  • The inspector shows a span’s input, output, and metadata.
  • Each trace, observation, and session can link straight to the same record in Langfuse.
Tilde checks that a trace belongs to the agent before it shows it. Langfuse credentials stay on the gateway and never reach the browser.

What a trace contains

Spans that your framework’s OpenTelemetry instrumentation creates inside run join the same trace. Whether they include prompts and tool inputs is that instrumentation’s setting. Tilde’s own instrumentation never captures request bodies or authorization headers.

Use your own OpenTelemetry provider

If your agent already configures an OpenTelemetry provider, add Tilde’s span processor to it, rather than letting the SDK create a second provider.
Agent setup
Register the provider’s async context manager before you start the agent. Your spans then flow to both Tilde and your existing backend.