Traces

A trace represents a single request flowing through your system. It's made of spans — individual units of work with a start time, duration, service name, and attributes. Lightarch groups spans by trace_id and renders them as a waterfall.

Screenshot needed

Traces page: full list view showing 6 traces grouped by trace_id. Columns: expand arrow, Trace ID (truncated), Root Service, Spans count, Duration, Status badge (OK/Error), Time. One row is expanded showing the waterfall flamegraph below.

Trace Explorer

Filter bar

Use the filter bar at the top of the Traces page to narrow results:

Filter	What it does
Search	Full-text search on span body/message (FTS5 indexed — fast)
Service	Multi-select chip — add one or more services to filter
Environment	Auto-populated from your spans — production, staging, development, etc.
Severity	Toggle chips: TRACE DEBUG INFO WARN ERROR FATAL
Status	Toggle chips: 2xx 3xx 4xx 5xx
Duration	Min duration threshold in ms (e.g. show only spans > 500ms)
Trace ID	Paste a full or partial trace ID to jump directly to that trace
Time range	5m / 15m / 1h / 6h / 24h / 3d / 7d presets or custom date pickers

Click Run Query to apply filters. The page doesn't auto-refresh — this keeps it fast on large datasets.

Expanding a trace

Click any row to expand the waterfall. Each row in the waterfall is a span, shown proportionally to its duration relative to the total trace time.

Screenshot needed

Expanded trace waterfall: 4 spans across api-gateway, user-service, postgres-db, redis services. Each span has a proportional cyan bar showing its duration offset within the trace. Error spans show red bars. Span IDs shown in mono font.

View logs for a trace

At the top of the expanded waterfall, click "View logs for this trace". The Logs page opens pre-filtered by that trace_id, showing every log record that shares the same trace — perfect for correlating an error in traces with its log output.

Screenshot needed

'View logs for this trace' link highlighted at top of waterfall. Arrow showing navigation to Logs page with trace_id filter pre-filled, showing 3 log entries for that trace.

Cold storage

Spans older than 48 hours roll off D1 (hot index) into R2 cold storage. To fetch an old trace:

bash

# Fetch by trace ID — checks D1 first, falls back to R2 automatically
la trace fetch aabb1122ccdd3344

# In the UI: paste the trace ID in the Trace ID filter and click Run Query

Cold storage fetches take 2–5 seconds (R2 SQL scan) vs milliseconds for hot D1 queries. The UI shows "⚠ Fetched from cold storage (R2)" in the waterfall header when this happens.

CLI

bash

# ASCII flamegraph in terminal
la trace fetch aabb1122ccdd3344

# Raw JSON output
la trace fetch aabb1122ccdd3344 --json

# Find trace IDs via SQL
la query "SELECT DISTINCT trace_id, service, duration_ms FROM recent_spans WHERE is_error = 1 ORDER BY timestamp DESC LIMIT 10"

Screenshot needed

Terminal output of 'la trace fetch': ASCII flamegraph showing Trace ID, Total duration, Status: ERROR. Tree of services with bar chart blocks showing proportional timing. Example: '├── api-gateway [████████░░░░░░░░░░░░] [342ms] ✗'