Skip to content

Add nanosecond timestamp support#659

Merged
KavanPrice merged 10 commits into
mainfrom
kp/ns-timestamps
Jun 1, 2026
Merged

Add nanosecond timestamp support#659
KavanPrice merged 10 commits into
mainfrom
kp/ns-timestamps

Conversation

@KavanPrice
Copy link
Copy Markdown
Contributor

@KavanPrice KavanPrice commented May 28, 2026

Summary

Adds end-to-end nanosecond timestamp support throughout the ACS data pipeline, from edge agent to InfluxDB. Implements Option B from issue #652, repurposing the existing Sparkplug uint64 timestamp field to carry nanoseconds rather than adding a new metric.

A value-check heuristic (< 10¹⁵ = milliseconds, ≥ 10¹⁵ = nanoseconds) ensures backward compatibility during the transition period where old and new edge agents coexist.

  • lib/js-service-client - decoder populates timestampNs: bigint alongside timestamp: Date on all decoded Sparkplug packets; existing consumers are unaffected
  • acs-edge - encodes outgoing timestamps as nanoseconds; auto-stamps all incoming driver data at nanosecond precision via process.hrtime.bigint(); extracts timestampNs from JSON driver payloads
  • uns-ingester-sparkplug - modifies UNS JSON payloads to reflect nanosecond precision in timestamp
  • historian-sparkplug - writes nanosecond timestamps to InfluxDB at ns precision
  • historian-uns - reads timestamp from UNS payloads and writes to InfluxDB at ns precision

Driver usage

No changes required for existing drivers. To supply a source nanosecond timestamp from a new driver, include timestampNs as a numeric string in the JSON payload:

{ "value": 123.45, "timestampNs": "1779983216100923659" }

If absent, the edge agent automatically stamps values using process.hrtime.bigint().

How to test

  1. Deploy updated images for acs-edge, uns-ingester-sparkplug, historian-sparkplug, historian-uns
  2. Subscribe to UNS/v1/# - payloads should include a modified timestamp that now has nanosecond precision
  3. Query InfluxDB with Flux, adding map(fn: (r) => ({r with ns: string(v: uint(v: r._time))})) - verify sub-millisecond digits are non-zero
  4. Confirm existing millisecond-only drivers continue to work (no timestamp breakage)
image

Known gaps

  • Tests in acs-edge/tests/lib/helpers/typeHandler.test.ts need updating for new timestampNs parameter in setValueBy* signatures
  • Individual driver updates to surface actual source nanosecond timestamps are deferred
  • Subscription-based drivers using emit('data', ...) with non-JSON payloads fall back to now_ns() auto-stamping

Closes #652

@KavanPrice KavanPrice self-assigned this May 28, 2026
@KavanPrice KavanPrice marked this pull request as ready for review June 1, 2026 10:32
@KavanPrice KavanPrice merged commit 74ed191 into main Jun 1, 2026
1 check passed
@KavanPrice KavanPrice deleted the kp/ns-timestamps branch June 1, 2026 13:23
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.

Add nanosecond timestamp support

2 participants