telemetry-export

telemetry-export

Turns one run directory's append-only ledgers into a redacted NDJSON stream and pipes it to whatever backend the host project has declared. Read references/observability-adapters.md before touching this skill or its projector — it is the contract that keeps this a thin, replaceable adapter rather than a vendor client.

Deny-by-default. The projector script never forwards summary, verdict.rationale, prior_context, or an artifacts[] path. If a question can't be answered from structural/enum fields, this skill does not answer it. Widening the allowlist is a decision for observability-adapters.md, not an ad-hoc addition here.

Invocation

telemetry-export [run-dir]

run-dir defaults to the newest run under docs/superpowers/runs/ (same discovery ticket-sync uses). Typically invoked by an operator after a run completes, or wired into a host's own Stop hook — this skill never registers itself as a hook in plugin.json, so nothing exports by default.

Steps

1. Read the flow file. Look for .agentic/guides/integration/telemetry-flow.md. If it is absent, or **Status** is not configured, stop — print nothing, append nothing. This is the same warn-and-continue posture as work-item-adapters.md.
2. Resolve the run directory. Use the given path, or the newest meta.json under docs/superpowers/runs/ (maxdepth 2), matching ticket-sync's discovery exactly so the two adapters never disagree about "the current run."
3. Run the projector:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/export-run-telemetry.py" \
     --run <run-dir> --extra-fields "<Extra fields, if declared>"
   

   Capture stdout (the NDJSON batch) and the CURSOR {...} line the script writes to stderr.
4. Nothing new? If stdout is empty, stop without writing any event — a receipt for zero new lines would itself become the next telemetry.* line to exclude, for no benefit.
5. Invoke the declared exporter, piping the NDJSON batch to its stdin, under a timeout (120s, matching ticket-sync). Never let a nonzero exit or a hang block turn-end.
6. Append the outcome to the run's events.jsonl:
   • success → telemetry.export_receipt, data = the CURSOR object plus {"line_count": <lines sent>}.
   • failure/timeout → telemetry.export_warning, data = {"reason": "<short reason>"}. The CURSOR offsets are not advanced on failure, so the same batch is retried next invocation.