Skip to content

Commit c140ce4

Browse files
Sayan-cursoragent
andcommitted
docs: correct gotcha #13 in-process producer example and hazard wording
Address PR review nits: supervisord-shim is an HTTP producer (stamped at ingest), not an in-process one; use cdpmonitor as the real example. Clarify the hazard is a non-zero, non-wall-clock Ts since publishLocked already defaults a zero Ts to wall-clock. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 0b909ed commit c140ce4

1 file changed

Lines changed: 1 addition & 1 deletion

File tree

AGENTS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,4 @@ The Cloud VM runs inside a Firecracker microVM. Docker requires:
4949

5050
12. **All telemetry producers must publish through `TelemetrySession`, never directly to the raw `EventStream`.** Producers take a `func(events.Event) (events.Envelope, bool)` callback wired to `telemetrySession.Publish` in `cmd/api/main.go`; this is what enforces category gating from `PUT /telemetry`. Publishing straight to `EventStream` bypasses the customer's telemetry config. The only legitimate `EventStream.Publish` callers are `TelemetrySession` itself and tests.
5151

52-
13. **`events.Event.Ts` must be wall-clock (`time.Now()`) captured at emit/observe — never a monotonic or source-derived clock.** On scale-to-zero VMs, `CLOCK_MONOTONIC` freezes during suspend, so any timestamp derived from it (notably the kmsg envelope timestamp behind OOM events) skews backward by the suspended duration. HTTP-published events get stamped by the API handler at ingest; in-process producers (sysmon kmsg reader, supervisord shim, etc.) must stamp `time.Now()` themselves.
52+
13. **`events.Event.Ts` must be wall-clock (`time.Now()`) captured at emit/observe — never a monotonic or source-derived clock.** On scale-to-zero VMs, `CLOCK_MONOTONIC` freezes during suspend, so any timestamp derived from it (notably the kmsg envelope timestamp behind OOM events) skews backward by the suspended duration. `publishLocked` already defaults a zero `Ts` to wall-clock at ingest, so the real hazard is a producer setting `Ts` to a *non-zero, non-wall-clock* value (exactly the envelope bug). HTTP-published events leave `Ts` unset and get stamped by the API handler at ingest; in-process producers that set `Ts` themselves (sysmon kmsg reader, cdpmonitor, etc.) must use `time.Now()`.

0 commit comments

Comments
 (0)