From 4b8d1f77989d708eb63359712af9671737b01380 Mon Sep 17 00:00:00 2001 From: Lucas Pardue Date: Wed, 5 Jul 2023 19:30:35 +0100 Subject: [PATCH] Remove Configuration and Summary fields (#308) 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 --- draft-ietf-quic-qlog-main-schema.md | 124 +--------------------------- 1 file changed, 1 insertion(+), 123 deletions(-) diff --git a/draft-ietf-quic-qlog-main-schema.md b/draft-ietf-quic-qlog-main-schema.md index 351cf687..c782f817 100644 --- a/draft-ietf-quic-qlog-main-schema.md +++ b/draft-ietf-quic-qlog-main-schema.md @@ -218,7 +218,6 @@ QlogFile = { ? qlog_format: text .default "JSON" ? title: text ? description: text - ? summary: Summary ? traces: [+ Trace / TraceError] } @@ -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 @@ -354,7 +308,6 @@ Definition: Trace = { ? title: text ? description: text - ? configuration: Configuration ? common_fields: CommonFields ? vantage_point: VantagePoint events: [* Event] @@ -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" @@ -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 @@ -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 @@ -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: @@ -1473,7 +1356,6 @@ Definition: TraceSeq = { ? title: text ? description: text - ? configuration: Configuration ? common_fields: CommonFields ? vantage_point: VantagePoint } @@ -1488,7 +1370,6 @@ QlogFileSeq = { qlog_version: text ? title: text ? description: text - ? summary: Summary trace: TraceSeq } ~~~ @@ -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"],