Skip to content

Clarify lastSeenTimestampNs/lastUpdateTimestamp non-monotonicity on v8/v11 feeds - #4032

Open
sebastian-lerner-link wants to merge 3 commits into
mainfrom
docs/timestamp-monotonicity-clarification
Open

Clarify lastSeenTimestampNs/lastUpdateTimestamp non-monotonicity on v8/v11 feeds#4032
sebastian-lerner-link wants to merge 3 commits into
mainfrom
docs/timestamp-monotonicity-clarification

Conversation

@sebastian-lerner-link

Copy link
Copy Markdown
Contributor

Summary

  • Documents a real, observed behavior: on v8 (lastUpdateTimestamp) and v11 (lastSeenTimestampNs) feeds, the timestamp is a median across configured data providers, and can pause or occasionally move backward when the set of providers included in a report changes between reports.
  • Framed as a mechanism (fewer providers means each one carries more weight in the median), not a headcount disclosure — avoids stating or implying a specific provider count and avoids "small/low" framing.
  • Gives integrators a concrete bar for when to act: a single stalled or backward-moving report isn't cause for concern on its own; escalate only if it recurs across multiple consecutive reports or exceeds your own staleness threshold.
  • Drops observationsTimestamp as a suggested fix on the v8 page — it reflects report generation time, not confirmation that the underlying price changed, so it doesn't actually solve freshness detection. The recommendation stays lastUpdateTimestamp, described as reliable in the normal case but not guaranteed monotonic, with reliability improvements called out as active work.
  • Consolidated what was originally two separate branches (v8 and v11 changes) into one, since they're the same root cause and same fix pattern.

Test plan

  • Visually verify the rendered pages once deployed to preview
  • Confirm the "active area of work" line stays accurate as engineering progresses on this

Sebastian Lerner added 3 commits August 6, 2026 16:58
Same root cause (median timestamp over configured data providers),
same fix pattern (expect advancement as the norm; a single stalled or
backward-moving report is expected and fine on its own; only escalate
if it recurs across multiple consecutive reports or exceeds your own
staleness threshold). No reason to ship this as two separate branches.
observationsTimestamp reflects report generation time, not
confirmation that the underlying price changed, so it doesn't actually
solve the freshness question. The recommendation stays
lastUpdateTimestamp: reliable in the normal case, not bulletproof on
low-DP feeds, with reliability improvements in progress.
Replace "small/low number of configured data providers" with a
mechanism-first explanation: fewer providers means each one carries
more weight in the median, without characterizing feeds as thin.
Also drop "expected" from the single-occurrence framing so it reads
as "not concerning" rather than "supposed to happen."
@sebastian-lerner-link
sebastian-lerner-link requested review from a team as code owners August 6, 2026 21:52
@vercel

vercel Bot commented Aug 6, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
documentation Ready Ready Preview Aug 6, 2026 9:52pm

Request Review

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.

1 participant