Skip to content

Commit 25ba55e

Browse files
committed
Move trigger section under concrete data field section
1 parent 88cc7f8 commit 25ba55e

File tree

1 file changed

+37
-38
lines changed

1 file changed

+37
-38
lines changed

draft-ietf-quic-qlog-main-schema.md

Lines changed: 37 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -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

633633
Each 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

637637
Multiple 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}}.
773773
Typically however, all events in a single trace are of the same few protocols, and
774774
this 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

814778
As discussed in {{trace}}, a single qlog file can contain several traces taken
@@ -1083,7 +1047,6 @@ Description:
10831047
Reference:
10841048
: \[to a specification defining the event schema defining the event category\]
10851049

1086-
10871050
## Extending the Data Field {#data-field}
10881051

10891052
An 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

12361235
Depending on how events are designed, it may be that several events allow the

0 commit comments

Comments
 (0)