# Telemetry — Structured Runtime Samples

This directory contains append-only JSONL telemetry files for low-level runtime timings.

These records are separate from `usage/`:

- `usage/` is scoped to one `drainMailboxOnce()` execution and focuses on per-session work.
- `telemetry/` is for cross-cutting transport and gateway timings that do not fit cleanly into a single drain record.

## Layout

Files are partitioned by UTC day:

```text
telemetry/
  2026-03-14.jsonl
  2026-03-15.jsonl
```

## Record Format

Each line is one JSON object. The current metric records look like:

```jsonc
{
  "kind": "metric",
  "metric": "ingress_snapshot_ms",
  "value": 4.2,
  "ts": 1773475200000,
  "eventId": "evt_123",
  "sessionKey": "stdio:alice",
  "sourceKind": "stdio"
}
```

Current metric names:

- `ingress_snapshot_ms` — gateway snapshot persistence latency
- `replay_scan_ms` — unread outbox scan latency during pull/replay
- `cursor_load_ms` — delivery cursor read latency
- `cursor_store_ms` — delivery cursor write latency

Extra fields may vary by metric. They are for debugging context and may grow over time.

## Reporting

Use the report helper to aggregate recent samples:

```bash
pnpm run telemetry:report -- --since 30m
```

Bare numeric values are treated as minutes, so `--since 90` means the last 90 minutes.

The report prints `count`, `avg`, `p50`, `p95`, and `max` for each known metric.

To disable telemetry file persistence entirely on a host, set:

```bash
ALADUO_TELEMETRY_ENABLED=false
```

When disabled, duoduo still emits in-process debug telemetry logs when log level allows it, but it skips appending JSONL files under this directory.

## Guarantees

- **Append-only**: telemetry files are never rewritten in place.
- **Best-effort**: failed telemetry writes never block the main runtime path.
- **Low ceremony**: records are plain JSONL so they are easy to inspect with shell tools.