Skip to content

Commit

Permalink
Remove Configuration and Summary fields (#308)
Browse files Browse the repository at this point in the history
See #187 for explanation about the motivation. We could possibly be less
lethal and add some colour commentary about how applications could
capture details in their own optional fields but I think that's pretty
obvious from the extensible nature of the format.

Closes #187
  • Loading branch information
LPardue authored Jul 5, 2023
1 parent 54091f6 commit 4b8d1f7
Showing 1 changed file with 1 addition and 123 deletions.
124 changes: 1 addition & 123 deletions draft-ietf-quic-qlog-main-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,6 @@ QlogFile = {
? qlog_format: text .default "JSON"
? title: text
? description: text
? summary: Summary
? traces: [+ Trace /
TraceError]
}
Expand All @@ -233,56 +232,11 @@ JSON serialization example:
"qlog_format": "JSON",
"title": "Name of this particular qlog file (short)",
"description": "Description for this group of traces (long)",
"summary": {
...
},
"traces": [...]
}
~~~
{: #qlog-file-ex title="QlogFile example"}

## Summary

In a real-life deployment with a large amount of generated logs, it can be useful
to sort and filter logs based on some basic summarized or aggregated data (e.g.,
log length, packet loss rate, log location, presence of error events, ...). The
summary field (if present) SHOULD be on top of the qlog file, as this allows for
the file to be processed in a streaming fashion (i.e., the implementation could
just read up to and including the summary field and then only load the full logs
that are deemed interesting by the user).

As the summary field is highly deployment-specific, this document does not specify
any default fields or their semantics. Some examples of potential entries are
shown in {{summary}}.

Definition:

~~~ cddl
Summary = {

; summary can contain any type of custom information
; text here doesn't mean the type text,
; but the fact that keys/names in the objects are strings
* text => any
}
~~~
{: #summary-def title="Summary definition"}


JSON serialization example:

~~~~~~~~
{
"trace_count": 1,
"max_duration": 5006,
"max_outgoing_loss_rate": 0.013,
"total_event_count": 568,
"error_count": 2
}
~~~~~~~~
{: #summary-ex title="Summary example"}


## traces

It is often advantageous to group several related qlog traces together in a single
Expand Down Expand Up @@ -354,7 +308,6 @@ Definition:
Trace = {
? title: text
? description: text
? configuration: Configuration
? common_fields: CommonFields
? vantage_point: VantagePoint
events: [* Event]
Expand All @@ -368,9 +321,6 @@ JSON serialization example:
{
"title": "Name of this particular trace (short)",
"description": "Description for this trace (long)",
"configuration": {
"time_offset": 150
},
"common_fields": {
"ODCID": "abcde1234",
"time_format": "absolute"
Expand All @@ -384,45 +334,6 @@ JSON serialization example:
~~~~~~~~
{: #trace-ex title="Trace example"}

### Configuration

A qlog file is usually not used in isolation but by
means of various tools. Especially when aggregating various traces together or
preparing traces for a demonstration, one might wish to persist certain tool-based
settings inside the qlog file itself. For this, the configuration field is used.

The configuration field can be viewed as a generic metadata field that tools can
fill with their own fields, based on per-tool logic. It is best practice for tools
to prefix each added field with their tool name to prevent collisions across
tools. This document only defines two optional, standard, tool-independent
configuration settings: "time_offset" and "original_uris".

Definition:

~~~ cddl
Configuration = {

; time_offset is in milliseconds
time_offset: float64
original_uris:[* text]
* text => any
}
~~~
{: #configuration-def title="Configuration definition"}

JSON serialization example:

~~~~~~~~
{
"time_offset": 150,
"original_uris": [
"https://example.org/trace1.qlog",
"https://example.org/trace2.qlog"
]
}
~~~~~~~~
{: #configuration-ex title="Configuration example"}


#### time_offset

Expand All @@ -440,33 +351,6 @@ an array instead of a single string, since a single qlog trace can be made up ou
of an aggregation of multiple component qlog traces as well. The default value is
an empty array.


#### custom fields
Tools can add optional custom metadata to the "configuration" field to store state
and make it easier to share specific data viewpoints and view configurations.

Two examples from the [qvis toolset](https://qvis.edm.uhasselt.be) are shown in
{{qvis-config}}.

~~~
{
"configuration" : {
"qvis" : {
"congestion_graph": {
"startX": 1000,
"endX": 2000,
"focusOnEventIndex": 124
}

"sequence_diagram" : {
"focusOnEventIndex": 555
}
}
}
}
~~~
{: #qvis-config title="Custom configuration fields example"}

### vantage_point {#vantage-point}

The vantage_point field describes the vantage point from which the trace
Expand Down Expand Up @@ -1257,8 +1141,7 @@ the name of the heading in lowercase (e.g., the "name" of the scenario event is
Importance: Extra

Used to specify which specific scenario is being tested at this particular
instance. This could also be reflected in the top-level qlog's `summary` or
`configuration` fields, but having a separate event allows easier aggregation of
instance. This supports, for example, aggregation of
several simulations into one trace (e.g., split by `group_id`).

Definition:
Expand Down Expand Up @@ -1473,7 +1356,6 @@ Definition:
TraceSeq = {
? title: text
? description: text
? configuration: Configuration
? common_fields: CommonFields
? vantage_point: VantagePoint
}
Expand All @@ -1488,7 +1370,6 @@ QlogFileSeq = {
qlog_version: text
? title: text
? description: text
? summary: Summary
trace: TraceSeq
}
~~~
Expand All @@ -1507,9 +1388,6 @@ JSON-SEQ serialization examples:
"qlog_format": "JSON-SEQ",
"title": "Name of JSON Text Sequence qlog file (short)",
"description": "Description for this trace file (long)",
"summary": {
...
},
"trace": {
"common_fields": {
"protocol_type": ["QUIC","HTTP3"],
Expand Down

0 comments on commit 4b8d1f7

Please sign in to comment.