@@ -631,7 +631,7 @@ the specific values and semantics of common fields, in particular the `name` and
631631` data` fields. Furthermore, they can optionally add custom fields.
632632
633633Each qlog event MAY contain the optional fields : " time_format"
634- ({{time-based-fields}}), "protocol_types " ({{protocol-type-field}}), "trigger"
634+ ({{time-based-fields}}), "protocol_type " ({{protocol-type-field}}), "trigger"
635635({{trigger-field}}), and "group_id" ({{group-ids}}).
636636
637637Multiple events can appear in a Trace or TraceSeq and they might contain fields
@@ -773,42 +773,6 @@ entry values, see {{QLOG-QUIC}} and {{QLOG-H3}}.
773773Typically however, all events in a single trace are of the same few protocols, and
774774this array field is logged once in "common_fields", see {{common-fields}}.
775775
776- # # Triggers {#trigger-field}
777-
778- Sometimes, additional information is needed in the case where a single event can
779- be caused by a variety of other events. In the normal case, the context of the
780- surrounding log messages gives a hint as to which of these other events was the
781- cause. However, in highly-parallel and optimized implementations, corresponding
782- log messages might separated in time. Another option is to explicitly indicate
783- these "triggers" in a high-level way per-event to get more fine-grained
784- information without much additional overhead.
785-
786- In qlog, the optional "trigger" field contains a string value describing
787- the reason (if any) for this event instance occurring, see
788- {{data-field}}. While this "trigger" field could be a property of the
789- qlog Event itself, it is instead a property of the "data" field instead.
790- This choice was made because many event types do not include a trigger
791- value, and having the field at the Event-level would cause overhead in
792- some serializations. Additional information on the trigger can be added
793- in the form of additional member fields of the "data" field value, yet
794- this is highly implementation-specific, as are the trigger field's
795- string values.
796-
797- One purely illustrative example of some potential triggers for QUIC's
798- " packet_dropped" event is shown in {{trigger-ex}}:
799-
800- ~~~~~~~~
801- TransportPacketDropped = {
802- ? packet_type : PacketType
803- ? raw_length : uint16
804- ? trigger : " key_unavailable" /
805- " unknown_connection_id" /
806- " decrypt_error" /
807- " unsupported_version"
808- }
809- ~~~~~~~~
810- {: # trigger-ex title="Trigger example"}
811-
812776# # Grouping {#group-ids}
813777
814778As discussed in {{trace}}, a single qlog file can contain several traces taken
@@ -1083,7 +1047,6 @@ Description:
10831047Reference :
10841048: \[to a specification defining the event schema defining the event category\]
10851049
1086-
10871050# # Extending the Data Field {#data-field}
10881051
10891052An event's "data" field is a generic key-value map (e.g., JSON object). It
@@ -1231,6 +1194,42 @@ $$transport-packetsent-extension //= (
12311194~~~~~~~~
12321195{: # data-ex title="Example of an extended 'data' field for a conceptual QUIC packet_sent event"}
12331196
1197+ # ## Triggers {#trigger-field}
1198+
1199+ Sometimes, additional information is needed in the case where a single event can
1200+ be caused by a variety of other events. In the normal case, the context of the
1201+ surrounding log messages gives a hint as to which of these other events was the
1202+ cause. However, in highly-parallel and optimized implementations, corresponding
1203+ log messages might separated in time. Another option is to explicitly indicate
1204+ these "triggers" in a high-level way per-event to get more fine-grained
1205+ information without much additional overhead.
1206+
1207+ In qlog, the optional "trigger" field contains a string value describing
1208+ the reason (if any) for this event instance occurring, see
1209+ {{data-field}}. While this "trigger" field could be a property of the
1210+ qlog Event itself, it is instead a property of the "data" field instead.
1211+ This choice was made because many event types do not include a trigger
1212+ value, and having the field at the Event-level would cause overhead in
1213+ some serializations. Additional information on the trigger can be added
1214+ in the form of additional member fields of the "data" field value, yet
1215+ this is highly implementation-specific, as are the trigger field's
1216+ string values.
1217+
1218+ One purely illustrative example of some potential triggers for QUIC's
1219+ " packet_dropped" event is shown in {{trigger-ex}}:
1220+
1221+ ~~~~~~~~
1222+ TransportPacketDropped = {
1223+ ? packet_type : PacketType
1224+ ? raw_length : uint16
1225+ ? trigger : " key_unavailable" /
1226+ " unknown_connection_id" /
1227+ " decrypt_error" /
1228+ " unsupported_version"
1229+ }
1230+ ~~~~~~~~
1231+ {: # trigger-ex title="Trigger example"}
1232+
12341233# # Event Importance Levels {#importance}
12351234
12361235Depending on how events are designed, it may be that several events allow the
0 commit comments