zotrace

Lightweight structured log analytics for Node.js — stream JSON (or common text) logs from files, stdin, or process pipes and get rolling RPS, error rate, p50/p95 latency, top endpoints, and deduplicated error messages. No Elasticsearch cluster required.

Author: Akum Blaise Acha — Senior DevOps & Platform Engineer.

| Doc | Purpose | |-----|---------| | ARCHITECTURE.md | System design, parsing flow, time semantics, extension points | | CONTRIBUTING.md | Local dev, tests, PRs, release notes for contributors |

npm install -g zotrace
# or
npx zotrace analyze ./logs/app.log

Why this exists

Small and mid-sized teams often run Pino, Winston, or Morgan and still debug production by grep, jq, and intuition. zotrace sits between raw files and a full observability stack: one binary, immediate answers, works over SSH.

Commands

analyze — batch summary (JSON)

Reads a file or stdin and prints one JSON snapshot (good for scripting).

zotrace analyze ./logs/api.log
cat combined.log | zotrace analyze

watch — live terminal dashboard

Pipe Docker, PM2, kubectl, or any JSON-line producer:

docker service logs my_api --follow 2>&1 | zotrace watch --format json
pm2 logs --raw 2>&1 | zotrace watch

Flags:

| Flag | Meaning | |------|---------| | -f, --format <name> | Hint: json, pino, winston, morgan, console-json, generic-json | | --json-only | Never treat lines as Morgan/combined Apache text (recommended for Docker’s JSON driver) | | -w, --window <sec> | Rolling window length (default 60) | | --error-alert <rate> | Alert when error rate ≥ threshold in-window (default 0.15) |

report — self-contained HTML

Scans directories (**/*.log, **/*.jsonl, **/*.txt) or glob patterns, applies --since, and writes a single offline HTML file using Chart.js from a CDN (no local server).

zotrace report ./logs/ --since 24h --output report.html

--since accepts values like 30m, 24h, 7d, 3600s.

Supported shapes

| Source | Detection | |--------|-----------| | Pino | Numeric level, time, msg, optional req/res, responseTime | | Winston | level + message / msg, optional meta fields | | Morgan combined | Apache-style line with method, path, status | | Generic JSON | statusCode, durationMs, path, message, etc. |

Unknown lines are skipped; parsers are ordered to prefer the most specific match.

Programmatic API

The package exports stable types and functions for custom tooling:

import { parseLogLine, AnalyticsEngine } from "zotrace";

See src/index.ts for the full surface.

Development

npm install
npm run build    # emits dist/
npm test
npm run lint
node dist/cli/index.js analyze examples/sample.log

Demo assets (GIFs)

Record watch mode with agg, terminalizer, or a screen recorder, then embed in this README. Keep clips short (under ~15s) and use realistic JSON logs.

Docker / Swarm

With the JSON log driver, container stdout is already JSON per line — use --format json so Morgan parsing is skipped:

docker service logs -f my_stack_api 2>&1 | zotrace watch --format json

For file-based logs mounted into a sidecar or jump host, use analyze / report against the mounted volume path.

License

MIT — see LICENSE.