Skip to content

Add the telemetry hook recording facade - #356

Open
gmemuriuki wants to merge 3 commits into
telemetry/recording-maintenancefrom
telemetry/recording-facade
Open

gmemuriuki wants to merge 3 commits into
telemetry/recording-maintenancefrom
telemetry/recording-facade

Conversation

@gmemuriuki

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR adds the inactive recording facade for hook-invocation telemetry. It does not connect the facade to production hook dispatch yet.

The state layer now produces one opaque RecordingChange containing the observed private state, optional aggregate snapshot, optional event request, and scheduled maintenance token. Storage alone can unwrap that change, which prevents callers from persisting a bare state or manufacturing an empty metric snapshot after an unsafe load.

LockedStorage owns the recording spine: load state, accept the timestamp, schedule maintenance, load the accepted day's snapshot, stage, persist, publish, then maintain. Snapshot failures remain fail-closed for aggregates without replacing surviving rows, while bounded outcomes distinguish contention, lifecycle rejection, state failure, snapshot unavailability, staging failure, and persisted publication results.

Tests cover accepted-day snapshot selection, future high-water rejection, lock contention, malformed state and metric snapshots, persistence and publication failures, maintenance deferral, and the outer facade path.

Disclosure questions

AI disclosure.

  • The AI tool authored large parts of the code

Questions for reviewers.

Does the opaque change boundary keep lifecycle, persistence, publication, and maintenance correctly ordered while preserving existing snapshots on unsafe input?

@gmemuriuki
gmemuriuki added this pull request to stack #331 October 17, 2026 06:35
@gmemuriuki gmemuriuki self-assigned this Oct 17, 2026
@gmemuriuki
gmemuriuki force-pushed the telemetry/recording-facade branch 3 times, most recently from d49ab99 to 64a183b Compare October 21, 2026 07:23
Err(error) => return not_recorded(NotRecordedReason::Persistence(error)),
};
let (publication, maintenance_due) = persisted.publish();
let maintenance = maintenance_due.map(|due| self.maintain(due));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the only path that runs maintenance, so expired files only get deleted after a recording reaches persist_recording. Lock contention, unreadable state, an unsafe snapshot, etc. all skip it, and with telemetry disabled old files never expire. The RFD change in this PR also drops "or telemetry command" from when cleanup runs. Is that intended? Running maintenance from telemetry status or disable would keep D31 retention independent of recording.

@nikomatsakis
nikomatsakis force-pushed the telemetry/recording-facade branch 8 times, most recently from be789ba to 52c8808 Compare October 27, 2026 12:47
@gmemuriuki
gmemuriuki force-pushed the telemetry/recording-facade branch 2 times, most recently from d40948b to 8a73c64 Compare October 28, 2026 13:24
Keep the production empty constructor private to the validated snapshot
loader and expose an explicit test-only constructor.

Project load failures into a bounded, content-free Copy reason so state
can retain fail-closed degradation without carrying I/O errors.
Let private state mint one opaque change containing its state, metric
decision, optional event request, and maintenance token. Keep binding
and per-operation assembly inside the state layer.

Teach locked storage to consume that unit, skip metric preparation when
no aggregate snapshot was requested, and report the bounded reason.
Cover both publication shapes and same-day maintenance throttling.
Run hook recordings through one locked orchestration spine that loads
and observes private state, stages the accepted day's aggregate work,
and persists before best-effort publication and maintenance.

Return bounded outcomes for contention and each fail-closed boundary.
Keep serializer errors out of retained diagnostics while preserving
content-free detail for debugging.
@gmemuriuki
gmemuriuki force-pushed the telemetry/recording-facade branch from 8a73c64 to 3c778ba Compare October 29, 2026 12:58
@gmemuriuki
gmemuriuki removed this pull request from stack #331 November 15, 2026 17:01
@gmemuriuki
gmemuriuki added this pull request to stack #504 November 15, 2026 17:01
@gmemuriuki
gmemuriuki removed this pull request from stack #504 November 15, 2026 18:26
@gmemuriuki
gmemuriuki added this pull request to stack #506 November 15, 2026 18:26

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants