4、QUIC日志基础：如何开启QUIC日志、日志级别设置、常用日志工具

做QUIC排错，第一步就是拿到日志。没有日志，你就像蒙着眼睛修车，全靠猜。我见过太多人一上来就抓包，结果面对一堆加密的QUIC包头发呆——其实很多问题，看日志比看报文快得多。

这一章，咱们就聊聊怎么把QUIC的日志搞出来，怎么设置级别，以及几个趁手的工具。说白了，就是给你配一套“听诊器”。

4.1 为什么要先搞定日志？

QUIC协议本身是加密的。你抓到的包，Payload部分全是密文。虽然Wireshark能通过SSLKEYLOGFILE解密，但那个过程挺折腾的。而应用层或协议栈自己输出的日志，直接就是明文状态信息。

我个人习惯是：先看日志定位方向，再用抓包验证细节。这样效率最高。

4.2 如何开启QUIC日志？

QUIC的实现有很多种（Chromium、lsquic、quiche、msquic等），开启方式大同小异。这里以最常见的Chromium/quic库和Nginx (quiche)为例。

4.2.1 Chromium / 浏览器端

Chrome或Edge浏览器内置了QUIC日志功能。你需要通过环境变量或命令行参数来开启。

# Linux / macOS
export QUIC_LOG_FILE=/tmp/quic.log
export QUIC_LOG_LEVEL=INFO
./chrome --enable-quic

# Windows (PowerShell)
$env:QUIC_LOG_FILE="C:\logs\quic.log"
$env:QUIC_LOG_LEVEL="INFO"
.\chrome.exe --enable-quic

启动后，所有QUIC连接的状态变化、丢包、重传等信息都会写入那个文件。嗯，这里要注意：日志文件会增长很快，生产环境别开太久。

4.2.2 Nginx (quiche) 服务端

Nginx的QUIC模块基于quiche库。日志通过error_log指令控制，但需要编译时开启调试。

# 编译时
./configure --with-http_v3_module --with-debug

# 配置文件中
error_log /var/log/nginx/quic_debug.log debug;
events {
    worker_connections 1024;
}
http {
    quic_log_level info;
    server {
        listen 443 quic;
        # ...
    }
}

我在项目中遇到过，很多人只配了error_log，忘了开--with-debug，结果日志里啥都没有。白忙活半天。

4.3 日志级别设置

日志级别控制信息的详细程度。级别越高，信息越少；级别越低，信息越全，但噪音也越大。

级别	说明	适用场景
FATAL	致命错误，进程即将退出	生产环境告警
ERROR	连接失败、协议错误	日常监控
WARNING	丢包、重传、超时	性能排查
INFO	连接建立、迁移、关闭	常规调试
DEBUG	帧级别细节、状态机转换	深度排错
VERBOSE	最详细，包含原始数据	协议开发

4.4 常用日志工具

光有原始日志还不够，得会用工具分析。我常用的有三个：qlog、Wireshark、自研脚本。

4.4.1 qlog：QUIC的标准化日志格式

qlog是IETF标准化的QUIC日志格式（RFC 9421）。它把日志结构化，方便工具解析。很多QUIC实现（如lsquic、quiche）都支持输出qlog。

// 一个简化的qlog示例
{
  "qlog_version": "0.4",
  "title": "QUIC Connection Log",
  "traces": [
    {
      "title": "Client Trace",
      "events": [
        [1000, "transport", "packet_sent", { "packet_type": "initial", "size": 1200 }],
        [1050, "transport", "packet_received", { "packet_type": "handshake", "size": 400 }],
        [1100, "recovery", "packet_lost", { "packet_number": 5 }]
      ]
    }
  ]
}

你可以用qvis（一个在线可视化工具）把qlog文件拖进去，直接看到连接的时间线、丢包分布、RTT变化。非常直观。

4.4.2 Wireshark：抓包与日志结合

Wireshark是网络排错的瑞士军刀。对于QUIC，它支持两种模式：

• 直接抓包：查看QUIC的头部信息（连接ID、包号、帧类型）。但Payload是加密的。
• 配合SSLKEYLOGFILE：解密后查看完整内容。

设置SSLKEYLOGFILE很简单：

# 设置环境变量
export SSLKEYLOGFILE=/tmp/quic_keys.log

# 启动浏览器或客户端
./chrome --enable-quic

# 在Wireshark中：编辑 -> 首选项 -> TLS -> (Pre)-Master-Secret log filename
# 选择 /tmp/quic_keys.log

解密后，你就能看到STREAM帧里的实际数据了。我个人习惯用Wireshark的“统计 -> 流量图”功能，看QUIC连接的时序，一眼就能发现重传风暴。

4.4.3 自研脚本：快速过滤关键信息

有时候工具太通用，反而不好用。我会写一些简单的Python或awk脚本，从原始日志中提取关键指标。

# 一个简单的bash脚本，统计日志中丢包次数
grep "packet_lost" /tmp/quic.log | wc -l

# 提取所有RTT样本
grep "rtt=" /tmp/quic.log | awk -F'rtt=' '{print $2}' | awk '{print $1}'

你想想看，当你要排查几百个连接时，用脚本批量处理比一条条翻日志快多了。

4.5 知识体系：QUIC日志排错全景图

下面这张图，是我梳理的QUIC日志排错的核心流程。从日志开启到问题定位，每一步都离不开这些基础。

4.6 实战建议：从零开始搭一套日志环境

说了这么多，不如动手试试。我建议你按这个步骤来：

1. 本地起一个QUIC服务端（Nginx或Caddy），开启DEBUG日志。
2. 用Chrome访问，同时开启QUIC_LOG_FILE。
3. 模拟丢包（用tc命令：tc qdisc add dev lo root netem loss 5%）。
4. 观察日志：看看丢包时，日志里出现了什么关键字（packet_lost、retransmission）。
5. 用qvis可视化：把qlog文件拖进去，看看时间线。

做完这一步，你就基本掌握了QUIC日志的“听诊”技巧。后面遇到复杂问题，心里就有底了。