A CLI tool to investigate Pydantic Logfire traces. One command streams a trace into local SQLite and prints a peek summary. Search the saved data offline with SQL.
- Save + peek - A traceId/URL fetch streams all records into SQLite, then prints a compact summary (roots, top spans, exceptions with ancestry paths, slow spans)
- Local SQL - Query saved traces offline with SQLite syntax. Local queries need no token and have no rate limit.
- API SQL - Run DataFusion SQL directly against Logfire
- URL env auto-select - A Logfire URL's org/project picks the matching environment profile
- Compact/verbose modes - Machine-friendly JSON. Show HTTP request/response details.
- Flexible config - CLI flags, environment variables, or config file
# Build
make build
# Fetch a trace: streams to ~/.cache/lfsnag/<traceId>.sqlite, prints a peek summary
./bin/lfsnag <traceId># Clone the repository
git clone https://github.com/bigbag/lfsnag.git
cd lfsnag
# Build
make build
# Or install to GOPATH/bin
make install-c, --compact- Compact JSON output-v, --verbose- Show HTTP request/response details-e, --env- Environment profile (auto-picked from a Logfire URL's org/project)-f, --fields- Columns to save on fetch (default: all)--save FILE- SQLite path for a fetch (default:~/.cache/lfsnag/<traceId>.sqlite)--db FILE- Query a local SQLite file (--sqlor--peek)--peek- Peek summary. Works only with--db. A bare traceId already peeks.--sql- Raw SQL query (Logfire API, or--dblocal file)--token- Override read token
Mode rules:
--dbneeds--sqlor--peek. It rejects a traceId and--save.--sqlrejects--peek,--save, and a traceId.- A bare traceId always saves and peeks.
start_timestamp- The time when the span/log started (UTC)end_timestamp- When the span/log completed (UTC)duration- Elapsed time in seconds (NULL for logs)trace_id- Trace identifier (32 hex chars)span_id- Span identifier (16 hex chars)parent_span_id- Parent span reference (NULL for root spans)kind-span,log,span_event, orpending_spanspan_name- Short name shared by similar recordsmessage- Human-readable descriptionlevel- Severity levelis_exception- Whether the span holds an exceptionexception_type- Exception class nameexception_message- Exception messageexception_stacktrace- Formatted tracebackattributes- Arbitrary structured data (JSON)tags- Grouping labelsotel_status_code- Span status indicatorotel_status_message- Span error status descriptionotel_events- Span events (JSON)otel_links- Span links (JSON)service_name- Service/application nameservice_version- Service versionservice_instance_id- Service instance identifierservice_namespace- Service namespacedeployment_environment- Environment (production, staging, etc.)process_pid- Process IDhttp_response_status_code- HTTP status codehttp_method- HTTP methodhttp_route- HTTP route patternurl_full- Complete URLurl_path- URL pathurl_query- URL query stringlog_body- Body of OpenTelemetry log recordsotel_resource_attributes- Resource metadata (JSON)otel_scope_name- Instrumenting library nameotel_scope_version- Instrumenting library versionotel_scope_attributes- Scope metadata (JSON)telemetry_sdk_name- Telemetry SDK nametelemetry_sdk_language- SDK languagetelemetry_sdk_version- SDK version
lfsnag resolves configuration in this priority order: CLI flags > environment variables > config file.
Path: ~/.config/lfsnag/config.json
{
"default": "prod",
"environments": {
"prod": {
"token": "prod-read-token",
"base_url": "https://logfire-us.pydantic.dev",
"project": "my-org/prod-mra"
},
"stage": {
"token": "stage-read-token",
"base_url": "https://logfire-eu.pydantic.dev",
"project": "my-org/stage-mra"
}
}
}Select an environment with -e:
lfsnag -e prod abc123def456789012345678abcdef01Without -e, a Logfire URL argument selects the profile whose project field matches. Otherwise lfsnag uses the "default" field. CLI flags and env vars still override profile values.
LOGFIRE_READ_TOKEN- Logfire read tokenLOGFIRE_BASE_URL- API base URL (default:https://logfire-us.pydantic.dev)
A traceId or URL fetch streams all records into SQLite, then prints a small peek summary including the db path:
lfsnag abc123def456789012345678abcdef01
lfsnag 'https://logfire-us.pydantic.dev/org/proj?traceId=abc123def456789012345678abcdef01&spanId=...'The URL's org/project auto-selects the matching environment profile. The flag -e overrides this. Default file: ~/.cache/lfsnag/<traceId>.sqlite. The flag --save sets a different path:
lfsnag --save /tmp/t.sqlite -e stage abc123def456789012345678abcdef01Cached files are derived data. Clear them with rm -rf -- "${XDG_CACHE_HOME:-$HOME/.cache}/lfsnag" when no lfsnag fetch/query is running.
lfsnag --db /tmp/t.sqlite --peek
lfsnag --db /tmp/t.sqlite --sql "SELECT span_name, count(*) cnt FROM records GROUP BY span_name ORDER BY cnt DESC"
lfsnag --db /tmp/t.sqlite --sql "SELECT span_name FROM records WHERE is_exception = 1"Logfire attribute keys contain dots. Quote the JSON path in SQLite:
lfsnag --db /tmp/t.sqlite --sql "SELECT sum(json_extract(attributes, '\$.\"gen_ai.aggregated_usage.input_tokens\"')) FROM records"lfsnag -e dev --sql "SELECT span_name, count(*) as cnt FROM records GROUP BY span_name ORDER BY cnt DESC LIMIT 10"
lfsnag -e dev --sql "SELECT span_name, duration FROM records WHERE trace_id = '019d05ee9be731d9f95c339fb7b9c6c1' AND is_exception = true"lfsnag -c abc123def456789012345678abcdef01 | jq '.exceptions'
lfsnag -c --db /tmp/t.sqlite --sql "SELECT span_name FROM records WHERE is_exception = 1" | jq '.[].span_name'lfsnag -v abc123def456789012345678abcdef01make build # Build binary to bin/lfsnag
make run # Build and run
make run/quick # Run without rebuild
make test # Run tests
make test-race # Run tests with race detection
make coverage # Run tests with coverage report
make coverage-html # Generate HTML coverage report
make fmt # Format code
make vet # Run go vet
make lint # Run fmt and vet
make security # Scan Go code
make tidy # Tidy Go modules
make clean # Remove build artifacts
make install # Install to GOPATH/bin
make build-all # Build for linux/darwin/windows amd64/arm64# Run all tests
make test
# Run tests with verbose output
go test -v ./...
# Run tests with coverage
make coverage
# Run tests with race detection
make test-racelfsnag includes a Claude Code plugin. Use /lfsnag:trace to investigate Logfire traces directly from Claude Code.
/plugin marketplace add bigbag/lfsnag
/plugin install lfsnag@bigbag-lfsnag/plugin marketplace add /path/to/lfsnag
/plugin install lfsnag@lfsnagThen type /lfsnag:trace to start investigating a trace.
claude --plugin-dir .Use /reload-plugins after making changes to the skill without restarting.
The skill file is skills/trace/SKILL.md. Codex and other agents that follow the Agent Skills spec read .agents/skills/trace. That path is a link to skills/trace.
Open this repository. The agent loads the trace skill. In Codex, type $trace to investigate a trace.
Install the skill for every repository:
mkdir -p ~/.agents/skills
ln -s /path/to/lfsnag/skills/trace ~/.agents/skills/traceRestart the agent if the skill does not appear. On Windows, enable core.symlinks before you clone. The Claude Code plugin uses /lfsnag:trace.
MIT License - see LICENSE file.