stormlog.infer.server_clock

Place server telemetry timestamps on the client artifact’s clock.

The server join uses the inference clock-alignment model: an infer.clock_alignment record from the client artifact, or one built from --clock-offset-ns and --clock-uncertainty-ns, applied through align_timestamp. Clock domains name a host boot (see wall_clock_domain()), so equal names mean one clock.

Functions

align_samples(samples, clock)	Place every sample; count the ones no single alignment covers.
artifact_alignments(records, run_id)	Parse the artifact's infer.clock_alignment records.
build_server_clock(*, run_id, server_domain, ...)	Choose the clock evidence for one server domain, or say what is missing.
cli_alignment(run_id, server_domain, ...)	Represent operator-supplied flags as an in-memory alignment record.
client_clock_domain(artifact)	Return the client artifact's wall clock domain, naming the boot if known.

Classes

SampleAlignment(aligned, unaligned, applied, ...)	Client-clock times for the samples one clock could place.
ServerClock(server_domain, client_domain, ...)	How one server clock domain maps onto the client artifact's domain.

class stormlog.infer.server_clock.ServerClock(server_domain, client_domain, evidence, alignments=(), same_clock_uncertainty_ns=0, overridden=(), ignored=())

Bases: object

How one server clock domain maps onto the client artifact’s domain.

Parameters:

• server_domain (str)

• client_domain (str)

• evidence (str)

• alignments (tuple[ClockAlignmentEvent, ...])

• same_clock_uncertainty_ns (int)

• overridden (tuple[str, ...])

• ignored (tuple[str, ...])

server_domain: str

client_domain: str

evidence: str

alignments: tuple[ClockAlignmentEvent, ...] = ()

same_clock_uncertainty_ns: int = 0

overridden: tuple[str, ...] = ()

ignored: tuple[str, ...] = ()

align(timestamp_ns)

Return the client-clock time and the record used, or why none applies.

The record is None for one shared clock. A timestamp covered by no alignment, or by several, yields UNCOVERED or AMBIGUOUS.

Parameters:

timestamp_ns (int)

Return type:

tuple[AlignedTimestamp, ClockAlignmentEvent | None] | str

class stormlog.infer.server_clock.SampleAlignment(aligned, unaligned, applied, unplaced)

Bases: object

Client-clock times for the samples one clock could place.

Parameters:

• aligned (dict[TelemetrySample, AlignedTimestamp])

• unaligned (dict[str, int])

• applied (list[dict[str, Any]])

• unplaced (dict[TelemetrySample, str])

aligned: dict[TelemetrySample, AlignedTimestamp]

unaligned: dict[str, int]

applied: list[dict[str, Any]]

unplaced: dict[TelemetrySample, str]

stormlog.infer.server_clock.align_samples(samples, clock)

Place every sample; count the ones no single alignment covers.

Parameters:

• samples (Iterable[TelemetrySample])

• clock (ServerClock)

Return type:

SampleAlignment

stormlog.infer.server_clock.client_clock_domain(artifact)

Return the client artifact’s wall clock domain, naming the boot if known.

Artifacts written before domains carried a boot ID record {host}/unix_epoch_ns and keep the boot ID in metadata; both parts together name the same clock as a boot-qualified domain.

Parameters:

artifact (Mapping[str, Any])

Return type:

str | None

stormlog.infer.server_clock.artifact_alignments(records, run_id)

Parse the artifact’s infer.clock_alignment records.

This run’s records are deduplicated by the correlation resolver; records that name another run follow them unresolved, so a copied calibration can be reported instead of stopping the analysis. build_server_clock never places samples with them.

Parameters:

• records (Iterable[Mapping[str, Any]])

• run_id (str)

Return type:

tuple[ClockAlignmentEvent, …]

stormlog.infer.server_clock.build_server_clock(*, run_id, server_domain, client_domain, recorded, offset_ns, uncertainty_ns)

Choose the clock evidence for one server domain, or say what is missing.

Operator-supplied flags take precedence over artifact records for the same pair of domains; the replaced records are listed in overridden. Records from another run never place samples; they are listed in ignored.

Parameters:

• run_id (str)

• server_domain (str)

• client_domain (str)

• recorded (tuple[ClockAlignmentEvent, ...])

• offset_ns (int | None)

• uncertainty_ns (int | None)

Return type:

ServerClock | str

stormlog.infer.server_clock.cli_alignment(run_id, server_domain, client_domain, offset_ns, uncertainty_ns)

Represent operator-supplied flags as an in-memory alignment record.

Parameters:

• run_id (str)

• server_domain (str)

• client_domain (str)

• offset_ns (int)

• uncertainty_ns (int)

Return type:

ClockAlignmentEvent