Nooa Trace Viewer

Trace Viewer

The viewer (src/nooa/viewer/) is a single FastAPI app that is both the OTLP receiver agents send spans to and the web UI (React SPA) for browsing traces, LLM calls, and evaluation experiments. Traces persist in SQLite, so they survive restarts.

Start it

nooa start-dev                                  # http://localhost:5001
nooa start-dev --port 5002                      # custom port
nooa start-dev --db /path/to/other.db           # separate trace store
nooa start-dev --host 127.0.0.1                 # default host is 0.0.0.0

Stop with Ctrl-C. If deps are missing: uv sync --extra viewer. If the port is busy, the command reports the offending PID.

• Database resolution: --db > $NOOA_TRACE_DB > ~/.config/nooa/traces.db.
• Alternate entry point: python -m nooa.viewer (this path honors $NOOA_TRACE_VIEWER_PORT, default 5001; start-dev uses --port instead). DB default for the raw module is ./traces.db — prefer start-dev.

End-to-end workflow

nooa start-dev                                # terminal 1
uv run python my_agent.py                        # terminal 2 — auto-traced (see nooa-capturing-traces)
open http://localhost:5001/traces                # browse the session

Agents auto-detect the viewer at startup and stream spans; no code changes needed. If the agent ran on another host/port, set OTLP_ENDPOINT=http://<host>:<port>/v1/traces in the agent's environment.

Using the UI

Trace-detail features worth knowing:

• Timeline — dual-canvas zoomable timeline of all events; filter sidebar — toggle event types, filter by span/agent/LLM/execution ID.
• LLM call view — full reconstructed conversations per call (/api/traces/{session_id}/calls under the hood).
• Annotations — score/label/comment/tags on a trace; quick 👍/👎.
• Playground — re-run an LLM turn with a different model/temperature and diff the output.
• Batch ID chip in the header (copyable) — groups imported/eval runs; filter the list with /traces?batch_id=….
• Keyboard: j/k navigate, / search, ? shows all shortcuts. URL captures view state, so links are shareable; add &embed=true to embed.

Viewer plugin metadata

The viewer selects a registered span renderer from the nooa.viewer.plugin OpenTelemetry span attribute. Core NOOA tracing sets this automatically for method, generation, code-execution, and tool-execution spans. Code that adds a new renderer in src/nooa/viewer/frontend-react/src/components/plugins/index.ts can select it for custom spans by setting the same attribute on those spans.

Older imported traces may still carry the pre-NOOA key nemo_oo_agents.viewer.plugin; the viewer accepts that as a compatibility fallback, but new span producers should write nooa.viewer.plugin.

Import, export, delete

# Import OTLP .jsonl trace files (from exporters.jsonl(...) or a viewer export)
nooa import-traces ./traces/                          # dir (recursive) or single file
nooa import-traces run.jsonl --endpoint http://host:5001 --batch-id my-exp-v2

# Import a Harbor eval job directory
nooa import-harbor <job-dir>

# Export one session as .jsonl (round-trips through import-traces)
curl -o session.jsonl "http://localhost:5001/api/trace/export?session_id=<ID>"

# Delete
nooa delete-traces --batch-id my-exp-v2               # one batch via API
# DELETE /api/traces/{session_id}                        # one session
# DELETE /api/traces?confirm=true                        # everything

# Housekeeping for on-disk trace FILES (not the viewer DB)
nooa traces list
nooa traces delete --older-than 7

Import notes: only OTLP JSON lines ({"resourceSpans": [...]}) are accepted; the session ID is derived from the filename; already-imported sessions are skipped; omitted --batch-id auto-generates import_<timestamp>_<hex>.

REST API (for scripts and agents)

Base: http://localhost:5001. Most useful endpoints:

Ingestion is queued and written by a single background writer, so a GET immediately after a run may miss the tail — POST /v1/sync first when scripting.

Pitfalls

• nooa start-dev resolves the DB and sets NOOA_TRACE_DB in its own environment before starting uvicorn (same process); a separately launched python -m nooa.viewer without that var uses ./traces.db in the CWD — easy way to "lose" traces into a second DB.
• The viewer refuses to start (exit 1) if the SQLite DB is locked by another viewer instance — check for an already-running start-dev.
• Old docs mention a separate viewer package and a nooa viewer subcommand; the viewer now lives in src/nooa/viewer/ and nooa start-dev is the canonical command.

Related skills

• nooa-capturing-traces — how spans get produced and exported.
• nooa-trace-explorer — programmatic trace analysis (CLI + Python) on top of files or this viewer.