1# QUIC trace utilities 2 3This repository contains a format for recording a trace of QUIC connection, 4together with the tools for analyzing the resulting traces. This format of 5traces is currently partially supported by Chromium, and we hope for more 6implementations to adopt it in the future. 7 8The primary focus of this format is debugging congestion-control related 9issues, but other transport aspects (e.g. flow control) and transport-related 10aspects of the application (e.g. annotations for the types of data carried by 11the streams) are also within the scope. 12 13## How to record this format 14 15The traces are represented as a Protocol Buffer, which is completely described 16in `quic_trace/quic_trace.proto`. Projects that use Bazel can embed this 17repository directly and use the provided Bazel rules. 18 19## OpenGL-based renderer 20 21This repository contains two different tools to visualize the trace: 22 231. A simple gnuplot-based trace renderer. 241. A fully featured OpenGL-based renderer. 25 26The OpenGL-based is the current preferred way of rendering traces. It supports 27Linux and macOS, though Windows support is coming soon. OpenGL 3.3 or later is 28required. Most of its dependencies are shipped using Bazel build files, but for 29Linux, system SDL2 is used. 30 31 32 33### Build instructions 34 35Building trace renderer on Linux: 36 371. Install SDL2 with headers (`libsdl2-dev` on Debian and related systems). 381. Install OpenGL headers (on Debian, `libsdl2-dev` pulls those in). 391. Install Bazel from https://bazel.build 401. Build the renderer by running `bazel build -c opt //tools/render/...` 411. Run the renderer by running, for example, 42 `bazel-bin/tools/render/render_trace examples/example.qtr`. 43 44Building trace renderer on macOS: 451. Install Bazel from https://bazel.build 461. Build the renderer by running `bazel build -c opt --apple_platform_type=macos 47 --cpu=darwin_x86_64 //tools/render/...` 481. Run the renderer by running, for example, 49 `bazel-bin/tools/render/render_trace examples/example.qtr`. 50 51Note that macOS build requires a specific set of flags, because by default Bazel 52on macOS targets iOS. 53 54### Scalability 55 56The OpenGL-based renderer was built with the goal of rendering large traces in 57mind, and our testing has shown that it performs quite well with traces as large 58as 120MiB worth of data transferred (that's approximately 90,000 packets sent), 59even when ran on a machine with high-resolution screen and an integrated GPU. 60 61## Legacy gnuplot-based renderer 62 63This rendering script was originally built as a simple proof of concept for 64rendering the trace format, but still might be useful if other tools are not 65available. Instructions: 66 671. Build the helper tool by running `bazel build 68 //tools/quic_trace_to_time_sequence_gnuplot`. 691. Generate the graph by running `tools/time_sequence_gnuplot.sh trace_file 70 trace.png`. 71
