How it works

How telemetry.dev turns OpenTelemetry spans into traces, costs, and dashboard views.

Your application records spans with an SDK or any OpenTelemetry exporter and sends them over OTLP/HTTP. The ingest service checks the API key, reads model, token, and content fields from each span, calculates cost, removes content your privacy settings exclude, and stores the result for the dashboard.

Traces and spans

A trace is one run of your application from start to finish, such as one request to an agent. A span is one operation inside that run: a model call, a tool call, a database query, or a function you chose to record.

Spans form a tree. When code runs inside an active span, the spans it starts become that span’s children. The dashboard draws the tree as a waterfall, with each bar showing when its span started and how long it took:

The first-party SDKs give each span a type, and the type sets the standard gen_ai.operation.name attribute that the dashboard uses to label and color it:

Provider and framework integrations set these attributes for you. Spans from other OpenTelemetry instrumentation keep their own names and attributes; the span attributes reference lists which ones telemetry.dev reads.

Projects, environments, and API keys

• A project holds telemetry from one application, along with its API keys, privacy settings, and retention period.
• An API key sends data to exactly one project. Keys start with td_live_. Each new project gets a key named default, and the dashboard shows the full key only once.
• An environment is a name such as production or development that you set on your telemetry. It drives the dashboard’s environment filter and selects which capture setting applies.

The SDKs write the environment to the deployment.environment.name resource attribute, from TELEMETRY_DEV_ENVIRONMENT, and default to production. If a payload has no deployment.environment.name, the ingest service uses deployment.environment. If neither is set, it uses the key’s environment, or default for a key that accepts all environments.

A key can accept every environment or only one. A key scoped to one environment rejects any payload from a different environment with 403. See Environments and API keys.

What happens at ingest

The ingest service accepts OTLP traces, logs, and metrics as protobuf or JSON at https://ingest.telemetry.dev/v1/traces, /v1/logs, and /v1/metrics. The OTLP ingest reference covers headers, limits, and every error response.

While it normalizes a span, the service:

• Reads the model, provider, token usage, input, output, and tool and agent details from gen_ai.* attributes and from the other conventions it supports, such as the Vercel AI SDK’s ai.* and OpenInference’s llm.*. See Span attributes.
• Sets the span’s cost. A valid cost sent by the client is kept as sent. Otherwise the server multiplies the token counts by the model’s prices. An unknown model or missing token usage leaves the cost empty. See Cost calculation.
• Applies your privacy settings: it drops prompts and responses when capture is off for the span’s environment, and replaces secrets, personal data, and your custom patterns with [REDACTED].

What you see in the dashboard

• Traces lists runs with their input, output, duration, tokens, cost, and models. Open a trace to see its waterfall, then select a span to read its input, output, attributes, events, and errors. See Traces, sessions, and logs.
• Sessions groups traces that share a session ID, such as the turns of one conversation, and shows a timeline of each session’s model calls, tool calls, and errors.
• Overview charts requests, cost, latency, tokens, and errors over time. See Analytics.