Skip to content

telemetry: add timestamp index for latency sample gap correction - #3237

Closed
snormore wants to merge 1 commit into
mainfrom
snor/telemetry-timestamp-index
Closed

telemetry: add timestamp index for latency sample gap correction#3237
snormore wants to merge 1 commit into
mainfrom
snor/telemetry-timestamp-index

Conversation

@snormore

@snormore snormore commented Mar 11, 2026

Copy link
Copy Markdown
Contributor

Summary of Changes

  • Add a companion TimestampIndex PDA account that records per-write-batch timestamps, enabling accurate wall-clock reconstruction even when agents experience downtime gaps
  • Implement onchain program (new instruction + write-time updates), Go SDK instruction builders, device telemetry and internet latency collector submitters, and read-only deserialization in Go/Python/TypeScript SDKs
  • Include timestamp reconstruction helpers using binary search (single sample, O(log m)) and single-pass cursor (batch, O(n+m)) in all three SDK languages

RFC: rfcs/rfc18-telemetry-write-timestamp-index.md

Closes #877

Diff Breakdown

Category Files Lines (+/-) Net
Core logic 28 +1378 / -7 +1371
Tests 10 +337 / -5 +332
Docs/RFC 2 +232 / -0 +232
Other 1 +5 / -0 +5

~70% core logic, ~17% tests, ~12% RFC/docs. Note: this PR exceeds the ~500-line guideline due to cross-language SDK parity (Go + Python + TypeScript) and the onchain program changes — splitting further would leave incomplete functionality.

Key files (click to expand)
  • smartcontract/programs/doublezero-telemetry/src/state/timestamp_index.rs — New TimestampIndex account type: header struct, serialization, and 10K-entry ring buffer
  • smartcontract/programs/doublezero-telemetry/src/processors/telemetry/initialize_timestamp_index.rs — New instruction: creates the companion PDA derived from the samples account
  • smartcontract/programs/doublezero-telemetry/src/processors/telemetry/write_timestamp_index.rs — Appends a (sample_index, timestamp) entry on each write batch
  • smartcontract/programs/doublezero-telemetry/src/processors/telemetry/write_device_latency_samples.rs — Optionally accepts 4th account (timestamp index) for backward compat
  • sdk/telemetry/go/state.go — Go read-only SDK: DeserializeTimestampIndex + ReconstructTimestamp(s)
  • sdk/telemetry/python/telemetry/state.py — Python read-only SDK: TimestampIndex.from_bytes + reconstruct helpers
  • sdk/telemetry/typescript/telemetry/state.ts — TypeScript read-only SDK: deserializeTimestampIndex + reconstruct helpers
  • controlplane/telemetry/internal/telemetry/submitter.go — Device telemetry submitter: derives timestamp index PDA, passes on writes, initializes after new account creation

Testing Verification

  • Rust onchain program tests cover initialization, write-time appending, ring buffer wrap-around, and backward compatibility (writes without timestamp index account)
  • Cross-language fixture tests verify binary compatibility: Rust generates .bin/.json fixtures, Go/Python/TypeScript deserialize and assert field values match
  • Timestamp reconstruction unit tests in all three SDK languages validate binary search, single-pass cursor, entry boundary transitions, and empty-entries fallback

@snormore
snormore force-pushed the snor/telemetry-timestamp-index branch 5 times, most recently from eea0f20 to 4b0384c Compare March 21, 2026 14:56
Comment thread smartcontract/programs/doublezero-telemetry/src/error.rs Outdated
@martinsander00

Copy link
Copy Markdown
Contributor

In both submitters, when InitializeTimestampIndex fails, the code logs "writes will proceed without it" but retries the write with TimestampIndexPK` still set

@martinsander00

martinsander00 commented Mar 23, 2026

Copy link
Copy Markdown
Contributor

will approve, not sure if nik or karl want to take a looks since they were involved in the initial convo in #877

@snormore
snormore marked this pull request as ready for review March 23, 2026 13:20
@snormore
snormore requested review from karl-dz and nikw9944 March 23, 2026 13:20
@snormore
snormore force-pushed the snor/telemetry-timestamp-index branch from cbc657b to 32569cd Compare March 24, 2026 23:20
@snormore
snormore requested a review from ben-dz March 27, 2026 17:21
Comment thread smartcontract/programs/doublezero-telemetry/src/state/timestamp_index.rs Outdated
Comment thread smartcontract/programs/doublezero-telemetry/tests/timestamp_index_tests.rs Outdated
@snormore
snormore force-pushed the snor/telemetry-timestamp-index branch 2 times, most recently from cc8e5f1 to 1c6f316 Compare April 9, 2026 18:34
@snormore
snormore force-pushed the snor/telemetry-timestamp-index branch 2 times, most recently from 3a930d3 to 7f2746d Compare April 17, 2026 15:10
@snormore
snormore force-pushed the snor/telemetry-timestamp-index branch from 7f2746d to b2a1f29 Compare May 18, 2026 15:03
Add a TimestampIndex account that tracks sample index → timestamp
mappings as a companion to device and internet latency sample accounts.

- New onchain account type (AccountTypeTimestampIndex = 5) with PDA
  derived from samples account PK
- InitializeTimestampIndex and WriteLatencySamples instructions updated
  to optionally append index entries
- Read-only deserialization in Go, Python, and TypeScript SDKs with
  fixture generation and cross-language compat tests
- Timestamp reconstruction helpers using binary search and single-pass
  for efficient sample timestamp lookups
- Timestamp index full condition is non-fatal in write path
@snormore
snormore force-pushed the snor/telemetry-timestamp-index branch from b2a1f29 to 9e149e9 Compare May 18, 2026 15:20
@snormore snormore closed this May 20, 2026
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.

device/telemetry: consider storing timestamps with samples

3 participants