Skip to content

fix(moq-transport): add time_format and reference_time to mlog header - #315

Open
cameronelliott wants to merge 1 commit into
cloudflare:mainfrom
cameronelliott:mlog-reference-time
Open

cameronelliott wants to merge 1 commit into
cloudflare:mainfrom
cameronelliott:mlog-reference-time

Conversation

@cameronelliott

@cameronelliott cameronelliott commented Nov 12, 2026 •

Copy link
Copy Markdown

The mlog header declares qlog_version 0.3. In qlog 0.3, a missing
common_fields.time_format means "absolute", so each event's 'time'
field should be an absolute timestamp, typically milliseconds since
the Unix epoch. The code instead writes milliseconds since the mlog
writer was created.

The default of "absolute" is explained here:
https://github.com/quicwg/qlog/blob/c2a302d9bf9b97c36e264ff1db42c14aa6e6705e/draft-ietf-quic-qlog-main-schema.md?plain=1#L631-L634

As written, event times cannot be converted to wall clock time. When
they can, mlog traces from different connections or hosts can be placed
on one timeline, which makes tools that analyze them possible.

Write "relative" as the time_format, and reference_time as the Unix
epoch milliseconds at which the writer started. Event times are
already measured from that point, so only the header output changes;
"absolute" or "delta" would change every event.

Update the example header in MLOG_SETUP.md.

Add a unit test:
header_declares_relative_times_anchored_to_wall_clock()

reference_time is rounded to whole microseconds, since an f64 of this
size cannot hold finer digits, and is left out if the clock reads
before 1970.

This only adds fields to the header. Existing fields and event records
are unchanged.

Validation: cargo fmt --check, cargo clippy --no-deps, cargo test and
cargo check --bins pass locally.

The mlog header declares qlog_version 0.3. In qlog 0.3, a missing
common_fields.time_format means "absolute", so each event's 'time'
field should be an absolute timestamp, typically milliseconds since
the Unix epoch. The code instead writes milliseconds since the mlog
writer was created.

The default of "absolute" is explained here:
https://github.com/quicwg/qlog/blob/c2a302d9bf9b97c36e264ff1db42c14aa6e6705e/draft-ietf-quic-qlog-main-schema.md?plain=1#L631-L634

As written, event times cannot be converted to wall clock time. When
they can, mlog traces from different connections or hosts can be placed
on one timeline, which makes tools that analyze them possible.

Write "relative" as the time_format, and reference_time as the Unix
epoch milliseconds at which the writer started. Event times are
already measured from that point, so only the header output changes;
"absolute" or "delta" would change every event.

Update the example header in MLOG_SETUP.md.

Add a unit test:
header_declares_relative_times_anchored_to_wall_clock()
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