C / C++ / 系统课时

用结构化日志追踪请求链路

用结构化日志追踪请求链路

这一节解决“日志很多却还原不了一次 RPC”的问题:统一连接 ID、请求 ID、阶段名和结果字段,让接入、解码、调度、执行、响应这些分散在不同线程中的日志能重新拼成一条链路,并用一个可运行的 C++ 示例验证字段设计。

学习目标

  • 设计能跨线程关联同一次 RPC 的连接 ID 与请求 ID
  • 用固定字段记录请求所处阶段、耗时和结果,而不是拼接随意文本
  • 通过请求 ID 从多行日志还原完整调用路径

一条链路需要哪些字段

纯文本日志的问题不在于“不能搜索”,而在于字段不稳定。同一个请求如果一会儿写“开始处理”,一会儿写“dispatch ok”,机器就很难可靠聚合。结构化日志应固定字段名与含义。

至少保留 connection_id、request_id、stage、event、status 和 elapsed_us。其中连接 ID 用来关联同一 TCP 连接上的多个请求,请求 ID 则必须唯一标识一次 RPC。stage 建议使用有限枚举,如 accept、decode、dispatch、execute、respond,避免自由文本。

错误场景再增加 error_type 与简短 message。业务参数只记录定位必需且允许落盘的内容,密码、Token、身份证号等敏感数据不应进入日志。

一次 RPC 在不同线程中的结构化日志链路

让上下文跨线程传递

Reactor 网络库经常在 IO 线程收包,在工作线程执行 RPC,再回到 IO 线程发送响应。如果只依赖线程 ID,链路会在调度点断掉。因此应显式创建请求上下文,并随任务一起投递。

下面示例直接输出 JSON Lines。它没有引入日志框架,但展示了稳定字段、请求上下文传递和阶段耗时的完整最小实现。

cpp
#include <chrono>
#include <cstdint>
#include <iostream>
#include <sstream>
#include <string>

struct RequestContext {
    std::uint64_t connectionId;
    std::uint64_t requestId;
};

void logEvent(const RequestContext& ctx,
              const std::string& stage,
              const std::string& event,
              const std::string& status,
              std::int64_t elapsedUs) {
    std::ostringstream out;
    out << "{"
        << "\"connection_id\":" << ctx.connectionId << ","
        << "\"request_id\":" << ctx.requestId << ","
        << "\"stage\":\"" << stage << "\","
        << "\"event\":\"" << event << "\","
        << "\"status\":\"" << status << "\","
        << "\"elapsed_us\":" << elapsedUs
        << "}";
    std::cout << out.str() << '\n';
}

int main() {
    RequestContext ctx{42, 1001};

    logEvent(ctx, "decode", "request_decoded", "ok", 35);
    // 请求进入工作线程后仍携带同一份上下文,不能重新生成 request_id。
    logEvent(ctx, "dispatch", "task_enqueued", "ok", 12);
    logEvent(ctx, "execute", "handler_finished", "ok", 680);
    logEvent(ctx, "respond", "response_written", "ok", 91);

    return 0;
}

预期输出:

json
{"connection_id":42,"request_id":1001,"stage":"decode","event":"request_decoded","status":"ok","elapsed_us":35}
{"connection_id":42,"request_id":1001,"stage":"dispatch","event":"task_enqueued","status":"ok","elapsed_us":12}
{"connection_id":42,"request_id":1001,"stage":"execute","event":"handler_finished","status":"ok","elapsed_us":680}
{"connection_id":42,"request_id":1001,"stage":"respond","event":"response_written","status":"ok","elapsed_us":91}

只要按 request_id=1001 检索,就能把这四条来自不同阶段的日志还原为一次调用。真实系统还可以补充时间戳、服务名、RPC 方法和线程名,但核心关联字段不要变化。

记录状态变化而不是重复正文

结构化日志的价值在于“事件可比较”。例如 event=request_decoded 表示完成了解码,event=task_enqueued 表示进入队列,event=handler_finished 表示业务执行结束。每个事件都应该代表明确的状态变化,而不是把同一句“正在处理请求”打印多次。

耗时字段也应绑定阶段。elapsed_us 如果代表当前阶段耗时,就必须始终保持这个语义;如果还需要端到端总耗时,单独增加如 total_elapsed_us 的字段。不要在不同代码路径里让同一个字段有时表示排队时间、有时表示总时间。

用日志还原一次失败请求

排障时先按请求 ID 聚合,再按阶段顺序检查缺口。如果有 decode 和 dispatch,却没有 execute,问题更可能发生在任务队列或线程池;如果 execute 成功但没有 respond,则应继续看连接状态、写缓冲和对端关闭。

错误日志还要保持分类稳定。例如超时统一使用 error_type=timeout,协议解析失败使用 error_type=protocol_error。这样既可以全文追踪单次请求,也可以按错误类型聚合统计。连接 ID、请求 ID、阶段和错误类型一旦稳定下来,日志才能真正承担“还原链路”而不是“堆积文本”的职责。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用结构化日志追踪请求链路

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通