Skip to content
OBSERVABILITY · OTEL

See what your AI agents actually did.

An OpenTelemetry-native trace explorer for agents. Instrument in a few lines, send spans over OTLP, and explore every run, replay, and cost.

OpenTelemetry-native · gen_ai spans over OTLP (JSON + protobuf) · self-host on plain Postgres.

  • OTLPnative ingest (JSON + protobuf)
  • gen_aiOTel semantic spans
  • 5Explorer views
  • Postgres 16spans are the source of truth
  • 1 portAPI + UI, no CORS
  • Apache-2.0License
$ npm install @usetheo/lens-sdkcoming to npm
Read the docs View on GitHub

AI agents fail in ways plain logs can’t explain — which tool ran, what the model cost, why a session went sideways. Theo Traces treats every agent run as an OpenTelemetry trace: your agent emits standard gen_ai spans over OTLP, and one docker compose up gives you the API, Postgres, and a Trace Explorer to walk the span tree, replay the session, and read cost and tool breakdowns.

What you get

Concretely, what ships.

OTLP-native ingest

Standard gen_ai spans over OTLP/HTTP; JSON and protobuf accepted.

One-command stack

docker compose up starts API, Postgres, and UI on one port.

Span-tree explorer

Every execution as a waterfall of agent and tool-call spans.

Session replay

Step through a run’s session replay in the Explorer.

Cost + token view

Reads gen_ai.usage tokens into typed columns for cost analytics.

Extensible adapters

Map an external agent onto typed fields with one service.name adapter.

Feel it
typescript
import { initTheoLens, startAgent, recordToolCall } from '@usetheo/lens-sdk';

const theo = initTheoLens({ endpoint: 'http://localhost:4318', serviceName: 'checkout-agent' });

await startAgent(theo.tracer, 'checkout', async (span) => {
  span.setModel('gpt-4o').setProvider('openai').setUsage({ inputTokens: 12, outputTokens: 8 });
  recordToolCall(span, 'search-products', { query: 'running shoes' });
});

await theo.shutdown(); // flush buffered spans before exit

Instrument an agent in a handful of lines with the SDK helpers.

What you'd ship

Things you would actually build.

  • 01Debug an agent run by walking its span tree from prompt to tool call.
  • 02Replay a past session step-by-step to see where an agent went wrong.
  • 03Track token usage and cost per execution across models and providers.
  • 04Break down which tools an agent called, with their arguments.
  • 05Observe Claude Code itself — its OTel sessions land as first-class executions.
  • 06Onboard an external agent by writing one service.name adapter, no schema change.
Why Theo Traces

How it compares.

OpenTelemetry is the neutral standard for traces, and the gen_ai conventions give agent spans a shared vocabulary. Comparison stated at a general level, public docs mid-2026.

CapabilityTheo TracesLangSmithLangfusePhoenix / OTel
IngestionOTLP-native gen_ai (JSON + protobuf)SDK-proprietarySDK / OTel-partialOTel
LicenseApache-2.0ProprietaryOSS + SaaSOSS
DeployOne docker compose up, single portManaged SaaSSelf-host / SaaSSelf-host
StoragePlain Postgres (spans = truth)ProprietaryPostgresVaries
Agent onboardingOne service.name adapterSDKSDKManual

OpenTelemetry-native from the ground up, self-hosted on plain Postgres — instrumenting an agent means emitting spans everyone already understands, not adopting one more proprietary SDK.

Why now

Agents are moving into production faster than the tooling to see inside them. Theo Traces builds directly on the OpenTelemetry gen_ai standard instead of one more proprietary SDK.

Status

Honest claims only.

  • OTLP-native ingest of gen_ai spans (JSON + protobuf), persisted to Postgres, with a Trace Explorer.
  • Instrument via the SDK helpers; session replay, cost, and tool analytics per run.
  • Apache-2.0 · one docker compose up · automatic context propagation on the roadmap.

See what your AI agents actually did.

$ npm install @usetheo/lens-sdkcoming to npm

Read the docs → docs.usetheo.dev

View the source → github.com/usetheodev/theo-lens

More in the ecosystem