import lighttrace
lighttrace.register()   # that's it: LangGraph, CrewAI, OpenAI Agents, Pydantic AI, ... are traced

Why LightTrace

• 🔌 Two lines, any framework: register() finds what your app uses and turns on the right OpenTelemetry listener. That covers 13 agent frameworks, 5 model clients, and anything else that speaks OpenTelemetry, in any language.
• 🧵 Built for agents: run trees with waterfalls, threads as one chat across turns, tool calls with arguments and results, and errors with tracebacks.
• 💸 Tokens, cost and speed: per call, per trace and per thread, with P50/P99 latency, time to first token, and a dashboard.
• 🏠 Yours: one Python process with SQLite or Postgres on your own machine. Your prompts never leave it, and there are no accounts or seats to pay for.
• 🔒 Private by default: API keys to send traces, a password for the UI, and localhost only unless you expose it.
• 🪶 Light: about 50–100 MB of RAM, and a plain HTML/JS UI with no build step.

Works with: LangChain · LangGraph · LlamaIndex · CrewAI · OpenAI Agents · Pydantic AI · Google ADK · Strands · Microsoft Agent Framework · Semantic Kernel · DSPy · smolagents · Agno · Qwen-Agent · OpenAI · Anthropic · Gemini · Bedrock · Portkey · Vercel AI SDK (versions tested)

Traces: status, latency, tokens and cost at a glance	Threads: the whole conversation, turn by turn
Dashboard: traces, errors, latency, tokens and cost over time

Contents

• Quick start
• Trace your app
• Supported frameworks
• Using the UI
• Deploy: Docker, Postgres, HTTPS, Configuration
• Retention and storage
• Troubleshooting
• Limits
• API
• Development

Quick start

You need Python 3.10 or newer. The whole quick start runs on one machine and makes no LLM calls.

1. Install the server.

python3 -m venv .venv && source .venv/bin/activate
pip install "lighttrace[server]"         # from a checkout of this repo: pip install ".[server]"

2. Configure it. Copy the example settings and fill in the two required values:

cp .env.example .env
python3 -c "import secrets; print(secrets.token_urlsafe(32))"   # use the output as an API key

In .env, set:

LIGHTTRACE_API_KEYS=<the key you just generated>
LIGHTTRACE_PASSWORD=<a password for the web UI>

3. Start it.

lighttrace          # serves http://127.0.0.1:1984 ; --host, --port and --db override .env

lighttrace reads .env from the current directory. Variables already set in the shell take precedence.

4. Log in. Open http://127.0.0.1:1984 and enter LIGHTTRACE_PASSWORD.

5. Send a trace. In a second terminal, run the sample LangGraph agent. It uses a fake model, so it needs no LLM key:

pip install lighttrace langgraph
LIGHTTRACE_ENDPOINT=http://127.0.0.1:1984 LIGHTTRACE_API_KEY=<your key> LIGHTTRACE_PROJECT=demo \
  python examples/langgraph_demo.py

A project called demo appears in the UI, with traces in three threads. Every other framework has a similar runnable script in examples/.

Trace your app

With register() (Python)

pip install lighttrace          # small: the OpenTelemetry sender + listeners, no server parts

import lighttrace
lighttrace.register()           # once at startup, before the app does any AI work

Set these where the app runs:

That's all. There's no special start command, and it works with --reload, gunicorn, Docker and short scripts: whatever is left is sent when the process exits. If the endpoint or the key isn't set, register() does nothing, so the same code runs untraced wherever they aren't set.

All options can also be passed in code:

lighttrace.register(
    project="myapp",
    endpoint="http://127.0.0.1:1984",
    api_key="...",
    capture_content=True,   # False: leave prompts, answers, tool arguments and results out
    clients=None,           # True/False: force tracing of raw model clients on or off (see below)
)

It returns the OpenTelemetry TracerProvider, or None when tracing is off. Calling it again returns the same provider.

To leave some calls out of the traces (a health-check ping, say), wrap them. This works with every framework, across await, and for everything the calls start; enabled=True turns tracing back on inside such a block:

with lighttrace.tracing_context(enabled=False):
    await llm.ainvoke([HumanMessage(content="ping")], max_tokens=1)

What register() does:

1. Finds the frameworks the app has installed.
2. Turns on their listeners. LightTrace writes none of its own. It uses OpenTelemetry's official GenAI instrumentations, or OpenInference's where the official one is missing or records too little (LangChain/LangGraph, LlamaIndex, CrewAI). Where the framework has its own OpenTelemetry (ADK, Strands, Microsoft Agent Framework, Semantic Kernel, Pydantic AI), it uses that. Model clients (OpenAI, Anthropic, Bedrock, Google GenAI, Portkey) are traced unless the frameworks present already record their model calls, so no call is recorded twice.
3. Points one sender at LightTrace with the key and project.

If the app already set up OpenTelemetry, register() adds LightTrace to it as one more destination.

Threads (conversations): put a thread_id, session_id or conversation_id in the run's metadata. In LangGraph, that is the usual config={"configurable": {"thread_id": ...}}.

Without the LightTrace package (any language)

The receiver is standard OpenTelemetry, so any OTLP/HTTP exporter can send to it directly, including other languages, an existing OpenTelemetry setup, or the zero-code opentelemetry-instrument launcher:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:1984
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # OTLP over HTTP; gRPC is not supported
export OTEL_EXPORTER_OTLP_HEADERS=x-api-key=<your key>
export OTEL_SERVICE_NAME=my-app                    # the project

See docs/ for per-framework pages and plain OpenTelemetry.

API keys and projects

Only the keys listed in LIGHTTRACE_API_KEYS (comma-separated) are accepted; anything else gets a 401. Give each app or team its own key. To shut an app out, remove its key from the list and restart.

Projects need no setup. A trace goes to the project named by LIGHTTRACE_PROJECT, which register() sends as the x-lighttrace-project header. Without it, the trace goes to the app's service.name (OTEL_SERVICE_NAME), and failing that to default. Several apps or environments can share one server as separate projects, e.g. myapp-staging and myapp-prod.

Supported frameworks

Per-framework notes and runnable examples are in docs/. Every framework below is tested end to end: a test runs its example through lighttrace.register() against a live LightTrace, with a fake model or a stub model server, so no LLM is called. The versions are the newest releases, tested on Linux with Python 3.13; each runs in CI on every change.

Also understood when sent over OpenTelemetry: the LangSmith SDK's OTel mode (end to end), MLflow, Langfuse SDK v3, OpenLLMetry and OpenLIT (real payloads).

Using the UI

Projects: every project, with its traces, threads, error rate, P50/P99 latency, tokens and cost for a time window.

Inside a project there are four tabs and a stats sidebar (traces, threads, error rate, P50/P99, tokens, median tokens per trace, cost):

Filters: time range, status, full-text search over inputs/outputs/errors, name, run type, tag, metadata key:value (several), latency ≥ / ≤ and tokens ≥.

• Active filters show as chips, and any filter can be saved per project.
• Columns can be shown or hidden.
• A Live toggle refreshes every 10 seconds.

A thread opens on one page with three views (keys T, U, D):

• Trajectory: the whole conversation as chat across all turns (human, AI, tool calls with arguments, tool results), de-duplicated. Each turn gets a line with latency, tokens, cost, model and links to the LLM call. You can download it as Markdown.
• Turns: one card per turn, with its input and output.
• Details: every turn with its run tree collapsed, and the selected turn expanded. Each tree has a waterfall, a filter box, expand/collapse, and arrow-key / j k navigation.

Opening a trace that belongs to a thread takes you to that thread's Details view.

The run panel (right side) shows latency, time to first token, tokens in/out, cost, model, and the run id with a copy button. It has two tabs:

• Run: the error with its traceback; input and output as Pretty or raw JSON, with copy; LLM messages as chat, retriever documents and tool arguments.
• Metadata: metadata, tags, invocation params, timing, ids, runtime and events.

The UI has light and dark modes; your choice is remembered per browser.

Cost columns appear when LIGHTTRACE_PRICES is set (see Configuration).

Deploy

Docker

The image includes Postgres support.

cp .env.example .env                     # set LIGHTTRACE_API_KEYS and LIGHTTRACE_PASSWORD
docker build -t lighttrace .
docker run -d --name lighttrace --restart unless-stopped \
  -p 127.0.0.1:1984:1984 -v lighttrace-data:/data --env-file .env \
  -e LIGHTTRACE_HOST=0.0.0.0 lighttrace

Inside the container, LightTrace binds to 0.0.0.0 and stores SQLite at /data/lighttrace.db (on the lighttrace-data volume). -p 127.0.0.1:… keeps it private on the host. Put a reverse proxy in front to expose it (see HTTPS).

Postgres

pip install "lighttrace[server,postgres]"

LIGHTTRACE_DB=postgresql://lighttrace:<password>@<host>:5432/lighttrace
LIGHTTRACE_RETENTION_DAYS=0          # keep forever

Create an empty database and a user that owns it; LightTrace creates its tables on start. Any Postgres 12+ should work, including managed ones (Supabase, Neon, RDS); the tests run against 18. Back up with your provider's snapshots or pg_dump.

HTTPS with Caddy

Keep LightTrace on 127.0.0.1:1984 and let Caddy terminate TLS. With a domain:

# /etc/caddy/Caddyfile
traces.example.com {
    reverse_proxy 127.0.0.1:1984
}

No domain? sslip.io gives every IP a hostname, and Caddy gets a real Let's Encrypt certificate for it. For a server at 203.0.113.7:

traces.203-0-113-7.sslip.io {
    reverse_proxy 127.0.0.1:1984
}

Then set LIGHTTRACE_COOKIE_SECURE=true and point apps at https://traces.203-0-113-7.sslip.io (LIGHTTRACE_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT). If the app runs on the same server, http://127.0.0.1:1984 is simpler and skips TLS.

Configuration

All configuration is through environment variables or a .env file; .env.example has every one with comments.

Server:

App (with register()): LIGHTTRACE_ENDPOINT, LIGHTTRACE_API_KEY and LIGHTTRACE_PROJECT (see Trace your app).

Retention and storage

With LIGHTTRACE_RETENTION_DAYS > 0, LightTrace checks every hour and deletes whole traces whose root started longer ago than that. With 0 nothing is ever deleted, and Postgres is the better choice.

SQLite:

• Size: the file stops growing once retention kicks in, because freed pages are reused.
• Reclaim disk: stop the server and run sqlite3 lighttrace.db 'VACUUM'.
• Back up: sqlite3 lighttrace.db ".backup backup.db" is safe while the server runs.

Run payloads are never logged, since they usually hold user and business data.

Troubleshooting

Limits

• Tracing only, one receiver. There are no feedback, datasets, experiments/evaluations, annotation queues, prompt hub or playground. Data comes in only through the OpenTelemetry receiver.
• No public share links, on purpose: a share link publishes every prompt and tool result to anyone holding it.
• OTLP over HTTP only. It accepts protobuf or JSON, with gzip but not zstd. OTLP logs are read for GenAI content only, and metrics are dropped. Traces produced while LightTrace is down are lost once the exporter's short retry gives up, because exporters don't buffer to disk.
• Search and stats aren't indexed. Text search is a LIKE/ILIKE scan, and percentiles and dashboards are computed in Python over the selected time window. That's fine for hundreds of thousands of traces; at many millions, narrow the window or add database-side indexes (e.g. pg_trgm).
• One admin, no roles. There's a single admin password and no users. Anyone who can log in sees every project, and any valid API key can write to any project.
• LangChain's OpenTelemetry mode is verified with langsmith 0.14.x (what langchain-core 1.x installs).

API

Ingest: POST /v1/traces, POST /v1/logs and POST /v1/metrics (accepted, then dropped).

• Send the key in x-api-key or Authorization: Bearer <key>.
• Bodies are OTLP/HTTP protobuf or JSON; ids can be hex or base64.
• The optional x-lighttrace-project header names the project.

UI JSON: these need the session cookie from POST /api/login ({"password": "..."}). Writes also need the x-lighttrace: 1 header.

Filters: since, until (epoch seconds), status (success/error/pending), q, name, run_type, tag, thread_id, meta=key:value (repeatable), min_latency, max_latency, min_tokens.

Development

git clone https://github.com/ganeshsali/lighttrace.git && cd lighttrace
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .       # lint (config in pyproject.toml)
.venv/bin/pytest -q          # includes end-to-end LangGraph tests; no LLM calls
.venv/bin/python -m build && .venv/bin/twine check --strict dist/*   # the package, as released

• Framework tests: the end-to-end tests in tests/test_frameworks.py skip unless their framework is installed, e.g. .venv/bin/pip install llama-index-core openai-agents pydantic-ai-slim.

• Postgres tests: run them against a throwaway database; the tests wipe it.

  docker run --rm -e POSTGRES_PASSWORD=pw -p 5432:5432 postgres:18
  LIGHTTRACE_TEST_PG=postgresql://postgres:pw@127.0.0.1:5432/postgres .venv/bin/pytest -q
  

• Project layout:

  Path	What's there
  lighttrace/client.py	register()
  lighttrace/app.py	The server: receiver, auth and UI API
  lighttrace/otel.py	Turns OTLP spans into runs
  lighttrace/store.py	All SQL (SQLite and Postgres)
  lighttrace/static/	The UI

• Releasing: bump __version__ in lighttrace/__init__.py, add a section to CHANGELOG.md, then push a v<version> tag. CI builds the package, checks it and publishes it to PyPI, a GitHub release and ghcr.io.

Contributions are welcome: see CONTRIBUTING.md (commits are signed off under the DCO), SECURITY.md for reporting vulnerabilities, and the Code of Conduct.

License

MIT. See CHANGELOG.md for what changed in each release.

LightTrace is an independent project, not affiliated with or endorsed by LangChain, Inc. "LangSmith" is a trademark of LangChain, Inc.; it is named here only to say which SDK can send to LightTrace.