agent-telemetry

An append-only event log for agent pipelines, and a dashboard that infers which pipeline actually ran from the stages it observed.

Two files. The point of both is refusing to report anything that wasn't measured.

---

log_event.sh — 24 lines, with a contract

./log_event.sh <agent> <stage> <status> <note> [job_id]

The header states the contract, and the code keeps it:

Design contract: NEVER block or fail a caller. Always exits 0.

That is the whole reason it is a shell script wrapping a heredoc rather than an import. Instrumentation that can throw is instrumentation that will one day take down the thing it was supposed to be watching. Called with no arguments at all, on a full disk, with a malformed note — it appends what it can and exits 0.

$ ./log_event.sh worker transform done "transform complete" job-0002
$ ./log_event.sh          # zero args, nonsense input
$ echo $?
0

Each call appends one JSON object:

{"ts":"2026-03-02T09:04:35+00:00","agent":"worker","stage":"transform",
 "status":"done","note":"transform complete","job_id":"job-0002"}

render_dashboard.py — infers the pipeline, doesn't ask

Given a log and an optional manifest declaring pipelines as stage lists, it scores each job's observed stage set against each declared pipeline and takes the best overlap:

def match_pipeline(job_stages, plists):
    js = set(job_stages)
    best, best_score = None, 0
    for name, stages in plists.items():
        score = len(js & set(stages))
        if score > best_score:
            best, best_score = name, score
    return best

So a job is classified by what it did, not by what it was labelled. A run that claimed to be a repair but only ever emitted ingest stages is reported as an ingest run — which is usually the moment you find the bug.

It emits dashboard-data.json plus a self-contained dashboard.html that polls the JSON every 3 seconds, and falls back to a snapshot baked in at render time when that fetch is blocked (opening the file directly, or embedding it somewhere sandboxed).

Run it

export TELEMETRY_DIR=./telemetry
mkdir -p "$TELEMETRY_DIR"
cp examples/events.example.jsonl  "$TELEMETRY_DIR/events.jsonl"
cp examples/manifest.example.json "$TELEMETRY_DIR/manifest.json"

python3 render_dashboard.py
# Agent Pipeline Telemetry — dashboard rendered
# Current/last job: job-0002 [ingest]
# Jobs shipped: 2 | in-progress: 2

TELEMETRY_DIR defaults to ~/.agent-telemetry. The manifest is optional — without one, agents and jobs are still tracked, but pipelines can't be named because nothing declared them.

Design notes

• Append-only. Nothing rewrites history. A wrong event stays and is corrected by a later one, because a log you can edit is a log you can't trust.
• No fabrication. If telemetry never logged a stage, the dashboard shows it as never having run. It will not interpolate a plausible middle.
• Status vocabulary is a set, not an enum. done/ready/pass/ship/ok all count as success. Agents written by different people at different times spell success differently, and rejecting their events would lose real data to a naming quarrel.

Files

File	Lines	What
log_event.sh	24	The logger. Never blocks, never fails, always exits 0.
render_dashboard.py	433	Snapshot builder + self-contained HTML dashboard.
examples/	—	A synthetic 14-event log and a two-pipeline manifest.

MIT licensed.