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
Open
fix(mlog): align qlog event output with draft-pardue-moq-qlog-moq-events-03#163englishm-cloudflare wants to merge 2 commits intocloudflare:mainfrom
englishm-cloudflare wants to merge 2 commits intocloudflare:mainfrom
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_schemaURN,serialization_format, versionedevent_schemaswithmoqt-03)event_typefrom event data — thenamefield already carries the event typemessageobject with atypediscriminator, matching the spec's$MOQTControlMessagestructurerequest_idin qlog output (mapped from internalsubscribe_idat the serialization boundary)header_typefromsubgroup_headerevents (not present in any version of the spec)extension_headers_lengthto subgroup object events (required field in -03)track_namespaceas[MOQTByteString],track_nameasMOQTByteString, locations asMOQTLocation(Sections 5.4/5.5),number_of_parameterson all control messages that require itTyped parameters and epoch timestamps (commit 2)
MOQTSetupParameterobjects and message params asMOQTParameterobjects 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 asMOQTExtensionHeaderper Section 5.7.Instant-based relative timestamps (ms since connection start) to absolute epoch-ms via cachedSystemTimeoffset +Instant::elapsed(). The header declarestime_format: "relative_to_epoch"with Unix epoch per qlog-main-schema-13 Section 7.1, so consumers can use thetimefield directly as a native timestamp.DeserializefromEvent/EventData(serialization-only; untagged enum is ambiguous for structurally identical variant pairs), redact authorization token values in qlog output (log onlytoken_length), computeextension_headers_lengthanalytically viavarint_wire_len().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_modeandobject_id_deltathat don't exist in -03; those are intentionally not included here.