tv - Local Trace Viewer for AI Agents

A fast, local trace viewer for AI agent development. Single binary, zero config, works with any OpenTelemetry-instrumented AI framework.

uvx trace-view

Why tv?

When building AI agents with tools like pydantic-ai, LangChain, or custom frameworks, you need to see what's happening:

  • What prompts are being sent?
  • What tools are being called and with what arguments?
  • Where is the latency coming from?
  • What's the token usage?

Production observability tools (Datadog, Jaeger) are overkill for local development. tv gives you a purpose-built viewer that understands AI agent traces.

Features

Dual Interface - Web UI for detailed analysis, TUI for quick terminal-based viewing

GenAI-Aware - Automatically classifies spans into user messages, assistant responses, tool calls, and thinking blocks (including Claude's extended thinking)

Zero Config - Point your OTEL exporter at localhost:4318 and spans appear automatically. Sessions are auto-grouped by process.

Real-time Updates - Spans stream in live via SSE as your agent runs

Token Tracking - See input/output token counts and totals per session

Timeline View - Visual representation of span timing for performance analysis

Search - Full-text search across span content

Export - Export sessions to JSON for analysis or sharing

Installation

# Run directly (no install)
uvx trace-view

# Or install globally
uv tool install trace-view

# Or add to project
uv add trace-view

# From source
cargo install traceview

Quick Start

import traceview

traceview.init()  # starts server at http://localhost:4318, configures OTEL

# your traced code runs normally
run_my_agent()

uv add "trace-view[otel]"
python my_agent.py

Or run standalone: uvx trace-view

CLI Usage

# Default: Web UI + TUI together
tv

# Server only (background/headless)
tv serve

# TUI only (connect to existing db)
tv ui

# Custom port and database
tv --port 8080 --db my_traces.db

# Environment variables work too
TV_PORT=8080 TV_DB_PATH=my_traces.db tv serve

Keyboard Shortcuts (TUI)

Key Action
j / k Move down / up
gg / G Jump to first / last
Ctrl+d / Ctrl+u Page down / up
Enter / Space Expand span
Tab Switch panel
h / l Focus sessions / spans
? Show help
q Quit

Web UI Features

  • Filter tabs: All | Tools | Thoughts | Errors
  • View modes: Conversation (default) | Timeline
  • Search: Full-text search across spans
  • Export: Download sessions as JSON
  • Dark/Light mode toggle
  • Real-time updates via SSE
  • Token summary per session

How Sessions Work

tv automatically groups spans into sessions using this priority:

  1. session.id attribute (explicit)
  2. gen_ai.conversation.id (OTEL GenAI convention)
  3. service.instance.id (auto-generated per process)
  4. Falls back to trace_id

This means all spans from a single script execution automatically group together without any configuration.

Span Classification

tv maps OTEL GenAI semantic conventions to span types:

Span Kind Source
User gen_ai.user.message events
Assistant gen_ai.assistant.message events
Thinking gen_ai.thinking (Anthropic extended thinking)
Tool Call gen_ai.tool.message with tool_calls
Tool Result gen_ai.tool.message without tool_calls
System gen_ai.system.message events

Architecture

  • Single binary - No external dependencies
  • SQLite storage - WAL mode for concurrent read/write
  • OTLP ingest - HTTP/JSON and HTTP/protobuf support
  • Batch writer - Configurable batching for high-throughput ingest
  • SSE streaming - Real-time updates without polling

Development

# Install dependencies (use --no-editable for binary)
uv sync --no-editable

# Run the binary
.venv/bin/tv

# Build Rust directly
cargo build

# Run tests
cargo test

# Before committing
cargo cl        # strict clippy
cargo t         # tests
cargo fmt --check

# Python checks
uv run ruff check python/
uv run pyright python/

License

MIT

Roadmap

  • Full-text search
  • Export to JSON
  • Python package
  • Pre-built binaries
  • Cost tracking
  • Span diff mode

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for h0rv from gravatar.com h0rv

License

MIT

Requires

Python >=3.9

Provides Extra

full otel

Tags

opentelemetry tracing observability genai llm

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

trace_view-0.1.0.tar.gz (142.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

trace_view-0.1.0-py3-none-win_amd64.whl (3.2 MB view details)

Uploaded Python 3Windows x86-64

trace_view-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

trace_view-0.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.1 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

trace_view-0.1.0-py3-none-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

trace_view-0.1.0-py3-none-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file trace_view-0.1.0.tar.gz.

File metadata

  • Download URL: trace_view-0.1.0.tar.gz
  • Upload date:
  • Size: 142.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for trace_view-0.1.0.tar.gz
Algorithm Hash digest
SHA256 2e8c879860cdd15a00a86ab60e3d7a69ff2636381f4f8a15abaaca09c7c1a096
MD5 29fe56cdfa53e8c7968eb966d2decede
BLAKE2b-256 776a3a44e5ccb15fb86eb8ff1a78baf23a77a13b5cad392cd3ed3ebb052c3a94

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace_view-0.1.0.tar.gz:

Publisher: release.yml on h0rv/traceview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace_view-0.1.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: trace_view-0.1.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 3.2 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for trace_view-0.1.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 afe46828c23e0a36d0c9970d2c2b709a80b115741d47986c00c302c232b5a2ba
MD5 95ecbbd4c93dc809afed203835fc9181
BLAKE2b-256 4c7214b4efa338d5c992a11105c4ed26dcd7d12d5c5f1ee9977ad3ba36d14f29

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace_view-0.1.0-py3-none-win_amd64.whl:

Publisher: release.yml on h0rv/traceview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace_view-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for trace_view-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b23947ec72d0ea06195a16a2a200ed2390e7c444193e1459b07cad941c5a42bc
MD5 8210d99219a4829a4e9f14e1b34eb659
BLAKE2b-256 a36cc62df3f32d759e191eec57ff0ecedde5edeb644770968d875fb52a83cbef

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace_view-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on h0rv/traceview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace_view-0.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for trace_view-0.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 173a03914086b5a5a2765f49b26810b614ce4ff110f2a8fa639228ca930cdb4e
MD5 8b357c568bf743a08d11ba9f150e8b56
BLAKE2b-256 be70a985d14ecf2f021aaa4c8a4b70726dab43cb074427f4eec8cadc078ed282

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace_view-0.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on h0rv/traceview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace_view-0.1.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for trace_view-0.1.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c1a213d4718d1a8f222f14034f2607f70e364853e0dff2bf559a3cdf228699cd
MD5 d4bb2cbc6fdb1f456deeb92ae3ebc818
BLAKE2b-256 3dc1d25de44718719145b7b0081c072f4fd99fbc0197de29870e5ea974775bd4

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace_view-0.1.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on h0rv/traceview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace_view-0.1.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for trace_view-0.1.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 50d7480594b398f4d7ade1246420ca78707211ff833b0e2d1857bb8a4fbe7e32
MD5 c48fa413c89750ef1dc638a372be6c80
BLAKE2b-256 21664fd7d7c636d046b1ae49e9764e09dd48bb396899801f97f16f9a5cc89c17

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace_view-0.1.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on h0rv/traceview

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

6 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page