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

# OpenTelemetry

> Tilde receives agent logs, traces, and metrics over OTLP, stores logs and traces in ClickHouse, and can forward a copy to your own OpenTelemetry collector.

The Tilde gateway has an OpenTelemetry receiver built in. Agents send logs and traces to the gateway over OTLP/HTTP, so you do not need to run a collector for Tilde to work.

If you already run an observability stack, Tilde can forward a copy of agent logs, traces, and metrics to your own collector.

<img src="https://mintcdn.com/tilde/UIZH9VuZaVUMv6QU/images/telemetry-flow.drawio.svg?fit=max&auto=format&n=UIZH9VuZaVUMv6QU&q=85&s=a16159e77aec29500eb32708723ea3c3" alt="Telemetry flow: agents send OTLP logs and traces to the gateway, which queues them in object storage, stores them in ClickHouse, and can forward a copy to your OpenTelemetry collector" width="1363" height="802" data-path="images/telemetry-flow.drawio.svg" />

<div className="zoom-hint"><Icon icon="magnifying-glass-plus" size={13} /> <em>Click to zoom</em></div>

## Signals

| Signal | Protocol | Stored in | Forwarded to your collector |
| - | - | - | - |
| Logs | OTLP/HTTP | ClickHouse | Yes |
| Traces | OTLP/HTTP | ClickHouse | Yes |
| Metrics | OTLP/HTTP | ClickHouse | Yes |

Tilde has a viewer for logs and traces. It stores metrics, and has no metrics viewer.

## Agent logs

The Tilde SDK exports your agent's logs for you. It authenticates each upload, and the gateway then sets the identifying attributes itself, so an agent cannot forge them.

| Log scope | Authenticated by | Attributes the gateway sets |
| - | - | - |
| Invocation | The invocation token | Agent, invocation, run, and thread |
| Deployment | The deployment token | Agent and deployment |

Deployment-scoped logs cover startup and background work, when no invocation is active.

Read logs in the agent's **Logs** tab. Filter by session, run, invocation, trace, scope, and severity. A log line's trace link opens that trace in the native viewer.

## Forward telemetry to your collector

Point Tilde at your collector's OTLP/HTTP endpoint for each signal, with any headers it needs for authentication. Tilde then sends it a copy of every agent log, trace, or metric batch.

Forwarding runs independently of Tilde's own history. If your collector is unavailable, the **Logs** and **Tracing** tabs are unaffected.

## Reliable delivery

The gateway writes each accepted batch to object storage before it acknowledges the upload. Any gateway replica then delivers it, and retries until it succeeds. An outage in ClickHouse or your collector does not drop telemetry, and never slows your agents.

Give each telemetry queue bucket an expiry rule of at least one day. Tilde never deletes a queued batch itself.

## Retention

Tilde keeps log, trace, and metric history for the retention period you configure, or indefinitely if you set none.

## Use your own OpenTelemetry provider in an agent

If your agent already configures OpenTelemetry, add Tilde's processors to your provider.

| Signal | Processor | SDK option |
| - | - | - |
| Traces | `agentSpanProcessor` | `tracing: "existing"` |
| Logs | `agentLogProcessor` | `logging: "existing"` |

See [Traces](/docs/traces#use-your-own-opentelemetry-provider) for an example.