telemetry.md

Telemetry

Runtime usage telemetry is best effort: an available usage event gets at most one asynchronous attempt through gentle-ai telemetry runtime send --json. Busy, failed, disabled, or cancelled attempts are discarded silently. There is no metrics disk storage, outbox, retry, backoff, cooldown, daemon, or session reconstruction.

The production encoder uses the byte-identical native schema mirror. The synthetic fixture pins its SHA-256 and exact one-shot stdin bytes. No old intake fallback is used. These are fake-subprocess tests, not a live collector or deployment verification.

Runtime usage flow

1. A finalized primary assistant message or child completion supplies available usage. Child-host extensions do not independently consume primary usage.
2. Pi builds event-local sanitized rows, not cumulative session totals. An occupied attempt slot discards the event; it never queues it for later.
3. One cancellable immediate defers binary verification and subprocess launch beyond the provider callback. The native command owns fresh policy and exactly one POST.
4. Only stored, duplicate, discarded, or disabled results are recognized. All are terminal. stored and duplicate reflect collector acknowledgement, not client persistence; Pi retains nothing and never retries.

There is no policy or capability subprocess before send, and no ingest or flush call. The packaged binary is verified; development overrides are refused for runtime usage. Missing binaries and unsupported commands discard without installation or fallback.

Replacement and shutdown cancel an unstarted attempt or request termination of its child immediately, without a wait loop or final send. The process slot remains busy until actual close, preventing overlap even if a cancelled process is slow to exit. A one-second process timeout requests termination; it is not a retry timer or a hard bound on synchronous binary verification or event-loop stalls.

Data and source limits

Wire fields are the schema/registry, host, public model with evidence, available selected/effective effort, orchestrator or known built-in subagent class, source launch/response occurrence coverage, six token coverages, explicitly reported typed duration, and a sanitized error category. Occurrences never represent sessions. Prompts, responses, code, paths, private names, source IDs, and raw errors never enter the payload. There is no batch_id; native creates the remote delivery_id.

One event produces 1–32 rows within 16 KiB. Oversized or invalid events discard whole rather than splitting into multiple sends. Child launch selection is a separate row with zero response-token coverage, never substituted for per-response evidence.

• Token coverage distinguishes reported, unavailable, and unsupported values. Pi's SDK-positive counters are usable; zero defaults and absence do not prove reported zero.
• Selected model/effort is captured at the request hook, separately from response model and effective-effort evidence. Ambiguous request sequences discard selection.
• Pi hooks do not correlate requests/retries reliably, so this adapter does not infer duration.
• Child configuration classification uses packaged built-in definitions, not agent names. Launch configuration is not proof of the model or selected effort of each child response.
• Bounded live child observations remain in RAM until completion. No completed child event is retained for forwarding. A completion without usage creates no usage send.
• Primary object deduplication uses weak tombstones; copied objects are distinct. Child completion tombstones are capped at 256 per extension session. Source IDs stay local and are never exported. No session history is read or reconstructed.

What Gentle Pi does

On activation of a primary session (not a named-agent session), Gentle Pi resolves the package-local gentle-ai binary (honoring a registered dev-binary override, same as every other native call) and spawns:

gentle-ai telemetry trigger --json

• detached, with stdout/stderr discarded (stdio: "ignore");
• a 3 s deadline: a runaway process is killed, but Gentle Pi never waits for it to exit;
• at most once per process, regardless of how many sessions or sub-agents run afterward.

Rate limiting, enrollment, and every opt-out live entirely in gentle-ai; calling the trigger once per session start is safe by construction. A missing binary, an older binary without the telemetry verb (which prints unknown telemetry command and exits non-zero), or a spawn failure are all treated as "nothing to do" and never affect activation or surface an error to the user.

Install counts for gentle-pi and gentle-engram come from npm download statistics; neither package emits an install event of its own.

The trigger contract

gentle-ai telemetry trigger --json always exits 0 and prints one line of JSON:

{"schema":"gentle-ai.telemetry-trigger/v1","decision":"enrolled|sent_install|sent_heartbeat|rate_limited|backoff|disabled","source":"<deciding source>"}

gentle-ai telemetry status|enable|disable|preview [--json] exist for the opt-out flow; status --json prints gentle-ai.telemetry-status/v1. Gentle Pi's /gentle:telemetry slash command runs these in the foreground (bounded to 5 s) through the same binary resolver and relays the result.

Opting out

Any of the following disables the nudge or the underlying telemetry:

• /gentle:telemetry disable — asks the local gentle-ai binary to disable telemetry. /gentle:telemetry status and /gentle:telemetry preview inspect it without leaving Pi.
• DO_NOT_TRACK=1 — Gentle Pi does not spawn the trigger at all; gentle-ai also honors this standard independently.
• GENTLE_AI_TELEMETRY=0 — same effect, gentle-ai's own environment switch.
• CI=true — Gentle Pi does not spawn the trigger in automated/CI runs, since they are not a real usage signal.