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 intocloudflare: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 intocloudflare: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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants