> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.trytilde.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> See every invocation as a trace, with model calls, tool calls, latency, token usage, and errors, in the Tilde UI and in Langfuse.

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](https://mintcdn.com/tilde-enterprise/E0-xiX0zmRn_ubi0/images/telemetry-flow.drawio.svg?fit=max\&auto=format\&n=E0-xiX0zmRn_ubi0\&q=85\&s=e65fe4017532e2a72bb7fc832db6ee00)

&#x20;*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.

> [!NOTE]
>
> Traces need a configured [Langfuse integration](https://enterprise-docs.trytilde.ai/integrations/langfuse.md). 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

| Captured by default | Captured only if you opt in |
| - | - |
| The invocation and its runtime calls | Prompts and completions |
| Trace context, propagated from the gateway | Tool inputs and outputs |
| Model, token usage, latency, and errors, from your framework's instrumentation | |
| Tilde SDK, sidecar, and gateway versions | |

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.

```typescript Agent setup theme={"system"}
import { agentSpanProcessor, createAgentServer } from "@trytilde/sdk";

const provider = new NodeTracerProvider({
  spanProcessors: [agentSpanProcessor, yourExistingProcessor],
});
provider.register();

createAgentServer({ tracing: "existing", run });
```

Register the provider's async context manager before you start the agent. Your spans then flow to both Tilde and your existing backend.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.