1// Copyright 2018 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// https://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto2"; 16 17package quic_trace; 18 19enum FrameType { 20 UNKNOWN_FRAME = 0; 21 22 STREAM = 1; 23 ACK = 2; 24 RESET_STREAM = 3; 25 CONNECTION_CLOSE = 4; 26 MAX_DATA = 5; 27 MAX_STREAM_DATA = 6; 28 PING = 7; 29 BLOCKED = 8; 30 STREAM_BLOCKED = 9; 31 PADDING = 10; 32 CRYPTO = 11; 33}; 34 35// Metadata for STREAM frames. 36message StreamFrameInfo { 37 optional uint64 stream_id = 1; 38 optional bool fin = 2; 39 optional uint64 length = 3; 40 optional uint64 offset = 4; 41}; 42 43// Metadata for CRYPTO frames. 44message CryptoFrameInfo { 45 optional uint64 length = 1; 46 optional uint64 offset = 2; 47} 48 49// The intervals are closed, i.e. the interval represented here is 50// [first_packet, last_packet]. 51message AckBlock { 52 optional uint64 first_packet = 1; 53 optional uint64 last_packet = 2; 54}; 55 56// Metadata for ACK frames. 57message AckInfo { 58 repeated AckBlock acked_packets = 1; 59 optional uint64 ack_delay_us = 2; 60}; 61 62// Metadata for RST_STREAM frames. 63message ResetStreamInfo { 64 optional uint64 stream_id = 1; 65 optional uint32 application_error_code = 2; 66 optional uint64 final_offset = 3; 67}; 68 69// Metadata for CONNECTION_CLOSE frames. 70// Close_type will indicate whether the close is a Google QUIC close, 71// IETF QUIC Transport CONNECTION CLOSE, or IETF QUIC Application 72// Connection Close, frame. 73enum CloseType { 74 GOOGLE_QUIC_CONNECTION_CLOSE = 0; 75 IETF_QUIC_TRANSPORT_CONNECTION_CLOSE = 1; 76 IETF_QUIC_APPLICATION_CONNECTION_CLOSE = 2; 77}; 78 79// Metadata for CONNECTION_CLOSE/APPLICATION_CLOSE frames. 80message CloseInfo { 81 optional uint32 error_code = 1; 82 optional string reason_phrase = 2; 83 optional CloseType close_type = 3; 84 optional uint64 transport_close_frame_type = 4; 85}; 86 87// Metadata for MAX_DATA/MAX_STREAM_DATA frames. 88message FlowControlInfo { 89 optional uint64 max_data = 1; 90 optional uint64 stream_id = 2; 91}; 92 93// A message representing a frame, either sent or received. 94message Frame { 95 optional FrameType frame_type = 1; 96 97 optional StreamFrameInfo stream_frame_info = 2; 98 optional AckInfo ack_info = 3; 99 optional ResetStreamInfo reset_stream_info = 4; 100 optional CloseInfo close_info = 5; 101 optional FlowControlInfo flow_control_info = 6; 102 optional CryptoFrameInfo crypto_frame_info = 7; 103}; 104 105// Metadata that represents transport stack's understanding of the current state 106// of the transport channel. 107message TransportState { 108 optional uint64 min_rtt_us = 1; 109 // Smoothed RTT, usually computed using EWMA. 110 optional uint64 smoothed_rtt_us = 2; 111 // The latest RTT measureent available. 112 optional uint64 last_rtt_us = 3; 113 114 optional uint64 in_flight_bytes = 4; 115 optional uint64 cwnd_bytes = 5; 116 // Pacing rate, in bits per second. 117 optional uint64 pacing_rate_bps = 6; 118 119 // Any arbitrary information about congestion control state that is not 120 // representable via parameters above. 121 optional string congestion_control_state = 7; 122}; 123 124// Documents external network parameters supplied to the sender. Typically not 125// all of those would be supplied (e.g. if bandwidth and RTT are supplied, you 126// can infer the suggested CWND), but there are no restrictions on which fields 127// may or may not be set. 128message ExternalNetworkParameters { 129 optional uint64 bandwidth_bps = 1; // in bits per second 130 optional uint64 rtt_us = 2; 131 optional uint64 cwnd_bytes = 3; 132}; 133 134enum EncryptionLevel { 135 ENCRYPTION_UNKNOWN = 0; 136 137 ENCRYPTION_INITIAL = 1; 138 ENCRYPTION_0RTT = 2; 139 ENCRYPTION_1RTT = 3; 140 ENCRYPTION_HANDSHAKE = 4; 141}; 142 143enum EventType { 144 UNKNOWN_EVENT = 0; 145 146 PACKET_SENT = 1; 147 PACKET_RECEIVED = 2; 148 PACKET_LOST = 3; 149 150 // An APPLICATION_LIMITED event occurs when the sender is capable of sending 151 // more data and tries to send it, but discovers that it does not have any 152 // outstanding data to send. Such events are important to some congestion 153 // control algorithms (for example, BBR) since they are trying to measure the 154 // largest achievable throughput, but it is impossible to measure it when the 155 // application does not send anything. 156 APPLICATION_LIMITED = 4; 157 158 // Record when external information about expected network conditions 159 // (available bandwidth, RTT, congestion window, etc) is supplied to the 160 // sender. 161 EXTERNAL_PARAMETERS = 5; 162}; 163 164enum TransmissionReason { 165 // Indicates that there was not any particular special reason the packet was 166 // sent. 167 NORMAL_TRANSMISSION = 0; 168 169 // Indicates that the packet sent is a tail loss probe, cf. 170 // https://tools.ietf.org/html/draft-ietf-quic-recovery-14#section-4.3.2 171 TAIL_LOSS_PROBE = 1; 172 173 // Indicates that the packet is sent due to retransmission timeout, cf 174 // https://tools.ietf.org/html/draft-ietf-quic-recovery-14#section-4.3.3 175 RTO_TRANSMISSION = 2; 176 177 // Indicates that the packet is sent in order to probe whether there is extra 178 // bandwidth available in cases where the sender needs an estimate of 179 // available bandwidth, but the application does not provide enough data for 180 // such estimate to become naturally available. This is usually only used in 181 // real-time protocols. 182 PROBING_TRANSMISSION = 3; 183}; 184 185// An event that has occurred over duration of the connection. 186message Event { 187 optional uint64 time_us = 1; 188 optional EventType event_type = 2; 189 190 optional uint64 packet_number = 3; 191 repeated Frame frames = 4; 192 optional uint64 packet_size = 5; 193 optional EncryptionLevel encryption_level = 6; 194 // State of the transport stack after the event has happened. 195 optional TransportState transport_state = 7; 196 // For event_type = EXTERNAL_PARAMETERS, record parameters specified. 197 optional ExternalNetworkParameters external_network_parameters = 8; 198 199 // For sent packets, indicate if there is a special reason for why the packet 200 // in question was transmitted. 201 optional TransmissionReason transmission_reason = 9 202 [default = NORMAL_TRANSMISSION]; 203}; 204 205message Trace { 206 // QUIC version tag, as represented on wire. Should be always 4 bytes long. 207 optional bytes protocol_version = 1; 208 209 // Source and destination connection ID. If multiple connection IDs are used, 210 // record the first one used with short-form header. 211 optional bytes source_connection_id = 2; 212 optional bytes destination_connection_id = 3; 213 214 repeated Event events = 4; 215}; 216