Skip to content

fix(mlog): align qlog event output with draft-pardue-moq-qlog-moq-events-03 - #163

Open
englishm-cloudflare wants to merge 2 commits into
cloudflare:mainfrom
englishm-cloudflare:me/mlog-qlog-compliance
Open

fix(mlog): align qlog event output with draft-pardue-moq-qlog-moq-events-03#163
englishm-cloudflare wants to merge 2 commits into
cloudflare:mainfrom
englishm-cloudflare:me/mlog-qlog-compliance

Conversation

@englishm-cloudflare

Copy link
Copy Markdown
Contributor

Summary

Align mlog event output with draft-pardue-moq-qlog-moq-events-03 (the qlog events spec matching our MoQT draft-14 implementation) and switch to epoch-relative timestamps.

Addresses feedback from @LPardue who reviewed sample mlog output during IETF 125.

Changes

Event structure alignment (commit 1)

  • File header: update to qlog-main-schema-13 format (file_schema URN, serialization_format, versioned event_schemas with moqt-03)
  • Remove redundant event_type from event data — the name field already carries the event type
  • Nest control messages under a message object with a type discriminator, matching the spec's $MOQTControlMessage structure
  • Use request_id in qlog output (mapped from internal subscribe_id at the serialization boundary)
  • Remove header_type from subgroup_header events (not present in any version of the spec)
  • Add extension_headers_length to subgroup object events (required field in -03)
  • Format data types per spec: track_namespace as [MOQTByteString], track_name as MOQTByteString, locations as MOQTLocation (Sections 5.4/5.5), number_of_parameters on all control messages that require it

Typed parameters and epoch timestamps (commit 2)

  • Typed parameters: format setup params as MOQTSetupParameter objects and message params as MOQTParameter objects per spec Sections 5.2/5.3. Known types (path, max_request_id, delivery_timeout, max_cache_duration) get named objects; unknown parameters use the spec's fallback format. Extension headers formatted as MOQTExtensionHeader per Section 5.7.
  • Epoch-relative timestamps: switch from Instant-based relative timestamps (ms since connection start) to absolute epoch-ms via cached SystemTime offset + Instant::elapsed(). The header declares time_format: "relative_to_epoch" with Unix epoch per qlog-main-schema-13 Section 7.1, so consumers can use the time field directly as a native timestamp.
  • Serialization cleanup: remove Deserialize from Event/EventData (serialization-only; untagged enum is ambiguous for structurally identical variant pairs), redact authorization token values in qlog output (log only token_length), compute extension_headers_length analytically via varint_wire_len().
  • Update MLOG_SETUP.md examples to match the new format throughout.

Example output

Header:

{"file_schema":"urn:ietf:params:qlog:file:sequential","serialization_format":"JSON-SEQ","title":"moq-relay","description":"MoQ Transport events","trace":{"vantage_point":{"type":"server"},"common_fields":{"time_format":"relative_to_epoch","reference_time":{"clock_type":"system","epoch":"1970-01-01T00:00:00.000Z"}},"event_schemas":["urn:ietf:params:qlog:events:moqt-03"]}}

CLIENT_SETUP parsed:

{"time":1775794492056.19,"name":"moqt:control_message_parsed","data":{"stream_id":0,"message":{"type":"client_setup","number_of_supported_versions":1,"supported_versions":["DRAFT_14"],"number_of_parameters":1,"setup_parameters":[{"name":"max_request_id","value":100}]}}}

PUBLISH_NAMESPACE parsed:

{"time":1775794492057.16,"name":"moqt:control_message_parsed","data":{"stream_id":0,"message":{"type":"publish_namespace","request_id":0,"track_namespace":[{"value":"moq-test"},{"value":"interop"}],"number_of_parameters":0,"parameters":[]}}}

Version targeting

This targets moq-qlog-moq-events-03 (Oct 2025), which references moq-transport-14 and qlog-main-schema-13. Later draft versions (-05, -06) introduce fields like subgroup_id_mode and object_id_delta that don't exist in -03; those are intentionally not included here.

Align mlog event serialization with the qlog MoQ events spec (draft-03,
matching our MoQT draft-14 implementation). Addresses feedback from Lucas
Pardue who reviewed sample logs during IETF 125.

Changes:
- Update file header to qlog-main-schema-13 format (file_schema URN,
  serialization_format, versioned event_schemas moqt-03)
- Remove redundant event_type from event data (name field is sufficient)
- Nest control message fields under a "message" object with "type"
  discriminator, matching the spec's $MOQTControlMessage structure
- Use request_id in qlog output (map from internal subscribe_id at the
  serialization boundary)
- Remove header_type from subgroup_header events (not in any spec version)
- Add required extension_headers_length field to subgroup object events
- Format track_namespace as [MOQTByteString], track_name as MOQTByteString,
  locations as MOQTLocation per spec Section 5.4/5.5
- Add number_of_parameters to all control messages that require it
…anup

Complete qlog data type compliance and switch to absolute timestamps:

- Format parameters as typed MOQTSetupParameter and MOQTParameter objects
  per draft-pardue-moq-qlog-moq-events-03 Sections 5.2/5.3 (known types
  get named objects; unknown parameters use the spec fallback format)
- Format extension headers as MOQTExtensionHeader objects per Section 5.7
- Switch from Instant-based relative timestamps to epoch-relative
  timestamps (cached SystemTime offset + Instant::elapsed). Header
  declares time_format "relative_to_epoch" with Unix epoch per
  qlog-main-schema-13 Section 7.1, so consumers can use the time field
  as a native timestamp without any transform.
- Compute extension_headers_length analytically via varint_wire_len()
  instead of encoding to a temp buffer
- Remove Deserialize from Event/EventData (serialization-only; untagged
  enum makes structurally identical variants ambiguous for deser)
- Redact authorization token values in qlog output (log only token_length)
- Update all MLOG_SETUP.md examples to match new format
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants