]> Cloudflare

lucas@lucaspardue.com

Technical University of Munich

mathis.engelbart@gmail.com

Media Over QUIC hi fidelity This document defines a qlog event schema containing concrete events for MoQ. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Media Over QUIC mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction This document defines a qlog event schema () containing concrete events for Media over QUIC Transport . The event namespace with identifier moqt is defined; see . In this namespace multiple events derive from the qlog abstract Event class (), each extending the "data" field and defining their "name" field values and semantics. summarizes the name value of each event type that is defined in this specification. Some event data fields use complex data types. These are represented as enums or re-usable definitions, which are grouped together on the bottom of this document for clarity. MOQT Events

Name value	Importance	Definition
moqt:control_message_created	Core
moqt:control_message_parsed	Core
moqt:stream_type_set	Core
moqt:object_datagram_created	Core
moqt:object_datagram_parsed	Core
moqt:object_datagram_status_created	Core
moqt:object_datagram_status_parsed	Core
moqt:subgroup_header_created	Core
moqt:subgroup_header_parsed	Core
moqt:subgroup_object_created	Core
moqt:subgroup_object_parsed	Core
moqt:fetch_header_created	Core
moqt:fetch_header_parsed	Core
moqt:fetch_object_created	Core
moqt:fetch_object_parsed	Core

When any event from this document is included in a qlog trace, the "protocol_types" qlog array field MUST contain an entry with the value "MOQT":

ProtocolType extension for MOQT

Usage with QUIC The events described in this document can be used with or without logging the related QUIC events defined in . If used with QUIC events, the QUIC document takes precedence in terms of recommended filenames and trace separation setups. If used without QUIC events, it is recommended that the implementation assign a globally unique identifier to each MOQT session. This ID can then be used as the value of the qlog "group_id" field, as well as the qlog filename or file identifier, potentially suffixed by the vantagepoint type (For example, abcd1234_server.qlog would contain the server-side trace of the connection with GUID abcd1234).

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The event and data structure definitions in ths document are expressed in the Concise Data Definition Language and its extensions described in . The following fields from are imported and used: name, namespace, type, data, group_id, protocol_types, RawInfo, and time-related fields. Events are defined with an importance level as described in . As is the case for , the qlog schema definitions in this document are intentionally agnostic to serialization formats. The choice of format is an implementation decision.

Event Schema Definition This document describes how the MOQT protocol is expressed in qlog with an event schema. Per the requirements in , this document registers the moqt namespace. The event schema URI is urn:ietf:params:qlog:events:moqt.

Draft Event Schema Identification Only implementations of the final, published RFC can use the events belonging to the event schema with the URI urn:ietf:params:qlog:events:moqt. Until such an RFC exists, implementations MUST NOT identify themselves using this URI. Implementations of draft versions of the event schema MUST append the string "-" and the corresponding draft number to the URI. For example, draft 99 of this document is identified using the URI urn:ietf:params:qlog:events:moqt-99. The namespace identifier itself is not affected by this requirement.

MOQT Events MOQT events extend the $ProtocolEventData extension point defined in . Additionally, they allow for direct extensibility by their use of per-event extension points via the $$ CDDL "group socket" syntax, as also described in .

MOQTEventData definition and ProtocolEventData extension

MOQT events are logged when a certain condition happens at the application layer, and there isn't always a one to one mapping between HTTP and QUIC events. The exchange of data between the HTTP and QUIC layer is logged via the "stream_data_moved" and "datagram_data_moved" events in . The concrete MOQT event types are further defined below, their type identifier is the heading name. Some MOQT messages include a reason phrase that can provide additional information in the format of a byte sequences. However, these sequences are not guaranteed to be presentable as UTF-8. In order to accomodate various encodings, where the wire image of a message includes a reason phrase, the MOQT qlog event type, includes two option fields: reason (for UTF-8) and reason_bytes (a hex-encoded string representing raw bytes). Implementations SHOULD log at least one format, but MAY log both or none.

control_message_created The control_message_created event is emitted when a control message is created. It has Core importance level. The definition of control message content is in .

MOQTControlMessageCreated definition

control_message_parsed The control_message_parsed event is emitted when a control message is parsed. It has Core importance level. The definition of control message content is in .

MOQTControlMessageParsed definition

stream_type_set The stream_type_set event conveys when a MOQT stream type becomes known. It has Base importance level.

MOQTStreamTypeSet definition

object_datagram_created The object_datagram_created event is emitted when the OBJECT_DATAGRAM message is created. It has Core importance level.

MOQTObjectDatagramCreated definition

object_datagram_parsed The object_datagram_parsed event is emitted when the OBJECT_DATAGRAM message is parsed. It has Core importance level.

MOQTObjectDatagramParsed definition

object_datagram_status_created The object_datagram_status_created event is emitted when the OBJECT_DATAGRAM_STATUS message is created. It has Core importance level; see .

MOQTObjectDatagramStatusCreated definition

object_datagram_status_parsed The object_datagram_status_parsed event is emitted when the OBJECT_DATAGRAM_STATUS message is parsed. It has Core importance level; see .

MOQTObjectDatagramStatusParsed definition

subgroup_header_created The subgroup_header_created event is emitted when a stream begins and a SUBGROUP_HEADER is created. It has Core importance level; see .

MOQTSubgroupHeaderCreated definition

subgroup_header_parsed The subgroup_header_parsed event is emitted when the SUBGROUP_HEADER is parsed. It has Core importance level.

MOQTSubgroupHeaderParsed definition

subgroup_object_created The subgroup_object_created event is emitted when a subgroup object is created. It has Core importance level.

MOQTSubgroupObjectCreated definition

subgroup_object_parsed The subgroup_object_parsed event is emitted when a subgroup object is parsed. It has Core importance level.

MOQTSubgroupObjectParsed definition

fetch_header_created The fetch_header_created event is emitted when a stream begins and a FETCH_HEADER is created. It has Core importance level.

MOQTFetchHeaderCreated definition

fetch_header_parsed The fetch_header_parsed event is emitted when the SUBGROUP_HEADER is parsed. It has Core importance level.

MOQTFetchHeaderParsed definition

fetch_object_created The fetch_object_created event is emitted when a fetch object is created. It has Core importance level.

MOQTFetchObjectCreated definition

fetch_object_parsed The fetch_object_parsed event is emitted when a fetch object is parsed. It has Core importance level.

MOQTFetchObjectParsed definition

MOQT Data Type Definitions The following data type definitions can be used in MOQT events.

Owner

Owner definition

MOQTSetupParameter The generic $MOQTSetupParameter is defined here as a CDDL "type socket" extension point. It can be extended to support additional MOQT Setup Parameters.

MOQTSetupParameter type socket definition any } ]]>

MOQTBaseSetupParameters definition

MOQTPathSetupParameter

MOQTPathSetupParameter definition

MOQTMaxRequestIdSetupParameter

MOQTMaxRequestIdSetupParameter definition

MOQTUnknownSetupParameter

MOQTUnknownSetupParameter definition

MOQTParameter The generic $MOQTParameter is defined here as a CDDL "type socket" extension point. It can be extended to support additional MOQT Parameters.

MOQTParameter type socket definition any } ]]>

MOQTBaseParameters definition

MOQTAuthorizationTokenParameter

MOQTAuthorizationTokenParameter definition

MOQTDeliveryTimeoutParameter

MOQTDeliveryTimeoutParameter definition

MOQTMaxCacheDurationParameter

MOQTMaxCacheDurationParameter definition

MOQTUnknownParameter

MOQTUnknownParameter definition

MOQTByteString The MOQTByteString type allows representing MOQT bytestrings, such as the value of a Track or Track Namespace tuple field, using two different encodings. The value field can be used for bytestrings that can be encoded in UTF-8. The value_bytes field can be used for bytestrings of any type by using the hexstring encoding. Implementations SHOULD populate one of either the value or value_bytes field. Populating both fields is redundant.

MOQTByteString definition

MOQTLocation A Location, as defined in

MOQTControlMessage The generic $MOQTControlMessage is defined here as a CDDL "type socket" extension point. It can be extended to support additional MOQT control message types.

MOQTControlMessage type socket definition any } ]]>

The MOQT control message types defined in this document are as follows:

MOQTBaseControlMessages definition

MOQTClientSetupMessage

MOQTClientSetupMessage definition

MOQTServerSetupMessage

MOQTServerSetupMessage definition

MOQTGoaway

MOQTGoaway definition

MOQTMaxRequestId

MOQTMaxRequestId definition

MOQTRequestsBlocked

MOQTRequestsBlocked definition

MOQTSubscribe

MOQTSubscribe definition

MOQTSubscribeOk

MOQTSubscribeOk definition

MOQTSubscribeError

MOQTSubscribeError definition

MOQTSubscribeUpdate

MOQTSubscribeUpdate definition

MOQTUnsubscribe

MOQTUnsubscribe definition

MOQTSubscribeDone

MOQTSubscribeDone definition

MOQTPublish

MOQTPublish definition

MOQTPublishOk

MOQTPublishOk definition

MOQTPublishError

MOQTPublishError definition

MOQTFetch

MOQTFetch definition

MOQTFetchOk

MOQTFetchOk definition

MOQTFetchError

MOQTFetchError definition

MOQTFetchCancel

MOQTFetchCancel definition

MOQTTrackStatusRequest

MOQTTrackStatusRequest definition

MOQTTrackStatus

MOQTTrackStatus definition

MOQTAnnounce

MOQTAnnounce definition

MOQTAnnounceOk

MOQTAnnounceOk definition

MOQTAnnounceError

MOQTAnnounceError definition

MOQTUnannounce

MOQTAnnounce definition

MOQTAnnounceCancel

MOQTAnnounceCancel definition

MOQTSubscribeAnnounces

MOQTSubscribeAnnounces definition

MOQTSubscribeAnnouncesOk

MOQTSubscribeAnnouncesOk definition

MOQTSubscribeAnnouncesError

MOQTSubscribeAnnouncesError definition

MOQTUnsubscribeAnnounces

MOQTUnsubscribeAnnounces definition

MOQTExtensionHeader

Extension Header definition

Security Considerations The security and privacy considerations discussed in apply to this document as well.

IANA Considerations This document registers a new entry in the "qlog event schema URIs" registry (created in ).

Event schema URI:

urn:ietf:params:qlog:events:moqt

Namespace

moqt

Event Types

control_message_created, control_message_parsed, stream_type_set, object_datagram_created, object_datagram_parsed, object_datagram_status_created, object_datagram_status_parsed, subgroup_header_created, subgroup_header_parsed, subgroup_object_created, subgroup_object_parsed, fetch_header_created, fetch_header_parsed, fetch_object_created, fetch_object_parsed

Description:

Event definitions related to the MOQT protocol.

Reference:

This Document

Normative References Akamai Meta Cloudflare qlog provides extensible structured logging for network protocols, allowing for easy sharing of data that benefits common debug and analysis methods and tooling. This document describes key concepts of qlog: formats, files, traces, events, and extension points. This definition includes the high-level log file schemas, and generic event schemas. Requirements and guidelines for creating protocol- specific event schemas are also presented. All schemas are defined independent of serialization format, allowing logs to be represented in various ways such as JSON, CSV, or protobuf. Note to Readers Note to RFC editor: Please remove this section before publication. Feedback and discussion are welcome at https://github.com/quicwg/qlog (https://github.com/quicwg/qlog). Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document. Akamai Meta Cloudflare This document describes a qlog event schema containing concrete qlog event definitions and their metadata for the core QUIC protocol and selected extensions. Note to Readers Note to RFC editor: Please remove this section before publication. Feedback and discussion are welcome at https://github.com/quicwg/qlog (https://github.com/quicwg/qlog). Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document. Cisco Google Google Meta This document defines the core behavior for Media over QUIC Transport (MOQT), a media transport protocol designed to operate over QUIC and WebTransport, which have similar functionality. MOQT allows a producer of media to publish data and have it consumed via subscription by a multiplicity of endpoints. It supports intermediate content distribution networks and is designed for high scale and low latency distribution. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON.

Acknowledgments Thanks to Sujay Patel for contributions to this document.