This repository contains a format for recording a trace of QUIC connection, together with the tools for analyzing the resulting traces. This format of traces is currently partially supported by Chromium, and we hope for more implementations to adopt it in the future.

The primary focus of this format is debugging congestion-control related issues, but other transport aspects (e.g. flow control) and transport-related aspects of the application (e.g. annotations for the types of data carried by the streams) are also within the scope.

The traces are represented as a Protocol Buffer, which is completely described in quic_trace/quic_trace.proto. Projects that use Bazel can embed this repository directly and use the provided Bazel rules.

This repository contains two different tools to visualize the trace:

1. A simple gnuplot-based trace renderer.
2. A fully featured OpenGL-based renderer.

The OpenGL-based is the current preferred way of rendering traces. It supports Linux and macOS, though Windows support is coming soon. OpenGL 3.3 or later is required. Most of its dependencies are shipped using Bazel build files, but for Linux, system SDL2 is used.

Building trace renderer on Linux:

1. Install SDL2 with headers (libsdl2-dev on Debian and related systems).
2. Install OpenGL headers (on Debian, libsdl2-dev pulls those in).
3. Install Bazel from https://bazel.build
4. Build the renderer by running bazel build -c opt //tools/render/...
5. Run the renderer by running, for example, bazel-bin/tools/render/render_trace examples/example.qtr.

Building trace renderer on macOS:

1. Install Bazel from https://bazel.build
2. Build the renderer by running bazel build -c opt --apple_platform_type=macos --cpu=darwin_x86_64 //tools/render/...
3. Run the renderer by running, for example, bazel-bin/tools/render/render_trace examples/example.qtr.

Note that macOS build requires a specific set of flags, because by default Bazel on macOS targets iOS.

The OpenGL-based renderer was built with the goal of rendering large traces in mind, and our testing has shown that it performs quite well with traces as large as 120MiB worth of data transferred (that's approximately 90,000 packets sent), even when ran on a machine with high-resolution screen and an integrated GPU.

This rendering script was originally built as a simple proof of concept for rendering the trace format, but still might be useful if other tools are not available. Instructions:

1. Build the helper tool by running bazel build //tools/quic_trace_to_time_sequence_gnuplot.
2. Generate the graph by running tools/time_sequence_gnuplot.sh trace_file trace.png.