richiexec/amber-backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Telemetry contract: the real session_summary shape, and the duplicate warning

Browse source 
The documented meta was the THIN row -- the leftover second writer that
amber-app just removed. It also never said that watchedS (elapsed watch
clock) and positionS (where playback reached) are different numbers, which
is exactly the distinction that made a never-started session readable.

Records that aggregates over rows before 2026-08-07 double-count Android
sessions, and gives the filter that excludes them.
This commit is contained in:
Claude 2026-08-07 12:40:49 +02:00
parent dc4f85fd4f
commit 8d3cefa3f5
1 changed files with 23 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
docs/telemetry-contract.md
View file

@ -21,11 +21,33 @@ older than 14 days nightly.
| `error` | `uncaught` | `{library}` — Flutter framework errors | | `error` | `uncaught` | `{library}` — Flutter framework errors |
| `player` | `exo_error` | `{host, anime}` — native player error | | `player` | `exo_error` | `{host, anime}` — native player error |
| `player` | `av_delay_applied` | `{audioMs, host}` — user dialed in an audio offset (the "a track falls behind" signal) | | `player` | `av_delay_applied` | `{audioMs, host}` — user dialed in an audio offset (the "a track falls behind" signal) |
| `session` | `session_summary` | `{host, durationS, watchedS, stalls, audioDelayMs, anime}` on player close | | `session` | `session_summary` | one row per playback — see below. **Written only by `SessionFeedbackService._write`.** |
| `qa` | `qa_session` | `{sid, lines[], truncated?}` — the QA decision log for one playback (issue #92), off by default |
`host` is only the stream's `scheme://host` — **never** a full signed URL or an `host` is only the stream's `scheme://host` — **never** a full signed URL or an
addon token (redacted client-side in `TelemetryService.redactUrl` before write). addon token (redacted client-side in `TelemetryService.redactUrl` before write).
### `session_summary`, and the two numbers that are not the same
`{sessionId, title, probeKey, host, durationS, watchedS, positionS, stalls,
droppedFrames, renderedFrames, maxConsecutiveDropped, problemAtS[], promptOutcome,
rating?}` plus the player's provenance fields (`forcedAudio`, `sideloadedSubs`,
`resumed`, `seeks`, `seekStormMax`, codec/height/bitrate).
- **`watchedS` is elapsed watch-clock time. `positionS` is where playback got to.**
They differ whenever someone seeks, rewatches, or stares at a spinner — a session
that never started reads `watchedS: 48, positionS: 0`.
- **`sessionId` is on every row**, and is what joins a summary to its `qa_session`
lines and to the amber-api health record.
**Before 2026-08-07 this was written twice per Android playback**, by the native
player *and* by the feedback service, and the two disagreed: the extra row had no
`sessionId`, `title` or `probeKey`, and put the *position* in `watchedS`. In one
14-day window that was 542 rows of which only 294 were real. **Any aggregate over
this collection computed before that date counts Android sessions twice**, and
rows older than the fix still carry the duplicate. `sessionId:isset = true` is the
filter that excludes them.
## How Claude queries it ## How Claude queries it
Superuser token (same as releases publishing), then filter/sort the collection: Superuser token (same as releases publishing), then filter/sort the collection: