可观测性

通过请求关联 ID、结构化日志、指标和分布式追踪,定位订单请求经过多个服务时发生的故障。

🎯 引言

用户点击“创建订单”后,请求可能经过 BFF、订单服务和库存服务。假设页面最终显示“创建失败”,我们该从哪里查起?仅查看订单服务的错误日志,可能只看到一句“库存请求超时”,却不知道这次故障影响了多少用户,也不知道请求在哪个环节花了时间。

本篇沿用订单系统,学习三个排查问题: 哪些请求受到影响、请求经过哪些服务、具体是什么错误 。我们会先让两个 Express 服务的日志使用同一个请求编号,再理解指标和分布式追踪,最后完成一次故障定位。


🧱 为什么只看一个服务的日志不够

假设一名用户创建订单,订单服务需要查询库存。两个服务都有自己的日志,而同一时刻还可能有许多其他用户在下单。只按时间查找,很容易把不同请求的日志混在一起。

解决这个问题,可以给每次请求分配一个 requestId(请求关联 ID) 。订单服务调用库存服务时,把这个编号带过去,两个服务记录日志时都写入它。这样,即使日志分散在不同服务,也能找到属于同一次请求的记录。

注意:requestId 只是帮助我们 关联日志 ,不是用户身份凭据,也不能用它判断请求是否有权限。


🔗 使用关联 ID 找到跨服务日志

下面使用两个小型 Express 服务演示:订单服务接收请求并生成 requestId,再调用库存服务;库存服务沿用该 ID 记录日志。本例使用 Node.js 22 或更新的兼容版本、Express 5,以及 Node.js 内置的 fetch。

1. 创建项目

observability-demo/
├── package.json
└── services/
    ├── orders.mjs
    └── inventory.mjs

在新目录执行:

mkdir -p observability-demo/services
cd observability-demo
npm init -y
npm install express@5

创建两个文件:

import express from 'express';
import { randomUUID } from 'node:crypto';

const app = express();

function log(requestId, message, extra = {}) {
    console.log(JSON.stringify({
        timestamp: new Date().toISOString(),
        service: 'orders',
        requestId,
        message,
        ...extra
    }));
}

// 每个入站请求生成独立 ID,而不是在模块加载时生成一次
app.use((req, res, next) => {
    req.requestId = randomUUID();
    res.setHeader('X-Request-Id', req.requestId);
    next();
});

app.get('/check-inventory', async (req, res) => {
    const { requestId } = req;
    log(requestId, '开始查询库存');

    try {
        const response = await fetch('http://localhost:3003/availability', {
            headers: { 'X-Request-Id': requestId },
            signal: AbortSignal.timeout(800)
        });

        if (!response.ok) {
            throw new Error(`库存接口返回 HTTP ${response.status}`);
        }

        const result = await response.json();
        log(requestId, '库存查询成功');
        res.json({ requestId, ...result });
    } catch (error) {
        log(requestId, '库存查询失败', { error: error.name });
        res.status(503).json({ requestId, message: '库存服务暂时不可用' });
    }
});

app.listen(3002, () => console.log('订单服务:http://localhost:3002'));

2. 运行并观察

分别打开两个终端,在项目根目录执行:

node services/inventory.mjs
node services/orders.mjs

在第三个终端执行:

curl -i http://localhost:3002/check-inventory

由于库存服务故意等待 1200 毫秒,而订单服务只等待 800 毫秒,正常情况下会收到 HTTP 503。响应体中会包含这次请求的 requestId,例如:

{"requestId":"req-example-01","message":"库存服务暂时不可用"}

实际 ID 是随机 UUID,上面的值仅用于说明格式。两个服务日志中的 requestId 应与该响应中的真实 ID 相同。将两边日志放在一起看,效果类似:

{"service":"orders","requestId":"req-example-01","message":"开始查询库存"}
{"service":"inventory","requestId":"req-example-01","message":"收到库存查询"}
{"service":"orders","requestId":"req-example-01","message":"库存查询失败","error":"TimeoutError"}
{"service":"inventory","requestId":"req-example-01","message":"库存查询处理完成"}

这里省略了示意日志中的 timestamp 字段,以突出关联关系。你会发现: 即使订单服务停止等待,库存服务仍可能继续完成处理 。这个现象也呼应了上一篇《容错与可靠性》中讲过的“超时不等于远端操作停止”。

示例在本地通过固定端口通信,重点是演示日志关联,不包含完整的服务间认证。真实环境中,库存服务只能在确认调用方可信后,才按约定接受上游传来的 X-Request-Id;不能把客户端随意填写的请求头当作可信身份或审计依据。

🔍 分布式追踪:不仅知道是谁,还能知道慢在哪里

通过 requestId,我们能找到这次请求的日志,但如果想知道 哪个环节耗时最多 ,仅有相同编号还不够。

分布式追踪(Tracing) 把一次跨服务请求记录为一条 Trace(追踪链) ;其中每个具体操作称为 Span(追踪片段) 。Span 通常记录开始时间、持续时间、结果,以及它与其他 Span 的父子关系。

例如,一次订单请求的追踪结果可能是:

正在加载流程图…

上图时间为假设数据,只表示调用关系。通过 Span 的实际时间信息,可以看出订单服务的大部分等待发生在库存查询,而不只是看到“订单接口很慢”。各 Span 的时间范围可能重叠, 不能把全部 Span 耗时简单相加当作总耗时 。

requestId 和 traceId 也不是同一概念:前者是我们自行约定的日志关联编号;后者属于追踪上下文,配合 Span ID、父子关系等信息构成追踪链。生产系统通常使用 OpenTelemetry 自动采集与传播这些信息,本篇先理解读懂追踪结果的方法,不重复讲监控平台部署。


📊 指标:判断故障影响有多大

日志可以解释某一次错误,追踪可以指出慢在哪一步,但它们不能直接回答: 这是不是偶发问题,还是已经影响大量订单? 这需要观察 指标(Metrics) ,也就是对一段时间内运行情况的统计。订单服务至少值得关注请求量、错误率、P95 请求耗时,以及库存调用超时次数。

例如,假设监控显示:

指标平时库存故障时
订单请求量(次/分钟)600600
订单接口错误率0.5%18%
订单接口 P95 耗时300ms2500ms
库存调用超时(次/分钟)290

这些都是 假设数据 ,不来自上面的 Express 小示例。P95 表示在统计样本中,约 95% 的请求耗时不超过该数值。它可以帮助观察较慢的一部分请求,但也应结合错误率和请求量判断。

从表中可以先作出一个判断:订单请求量没有明显上升,但错误率、P95 和库存超时次数一起升高, 很可能是库存依赖出现了问题 。这还是排查线索,而不是最终结论;下一步要通过追踪和日志验证。


🛠 一次完整的跨服务故障排查

现在把三个工具连起来。假设有用户反馈:“创建订单一直失败。”

排查步骤看到什么得到什么结论
1. 查看指标订单错误率上升、P95 变高,库存超时增加故障并非单个用户偶发,优先关注库存依赖
2. 查看追踪多个失败请求的库存调用 Span 耗时异常找到主要耗时发生在哪个服务调用
3. 查看日志使用同一 requestId 找到订单超时和库存处理记录确认订单服务停止等待,但库存接口响应过慢

至此,我们能回答开头的三个问题: 影响范围 可以从指标判断; 调用路径和慢点 可以从追踪判断; 具体异常 可以用关联日志进一步确认。

需要注意,现实中未必严格按这个顺序:如果用户直接提供 requestId,也可以先搜索日志,再回看追踪和指标。重点是让三种信息互相验证,而不是单凭某一条日志猜测原因。


⚠️ 日志与追踪不能泄露敏感信息

不要把完整 JWT、密码、支付凭据、数据库连接串或敏感个人信息写入日志;追踪属性也需要遵守相同规则。requestId 可用于查找单次请求,但不能替代认证和授权。

监控指标通常按接口、服务、状态码等维度聚合。不要随意把每个不同的订单编号设置成指标标签,否则会产生大量不同的标签组合,增加监控系统的存储与查询负担。

可观测性的目标不是记录越多越好,而是在出现问题时,能够找到受影响的请求、定位故障环节并确认原因。

❓ 知识问答

Q1:requestId 和 traceId 是一回事吗?

不是。requestId 是应用约定的请求关联编号;traceId 是分布式追踪使用的标识,配合 Span 关系描述整条调用链。它们可以同时写入日志,方便关联查询。

Q2:已经有日志,为什么还需要指标?

日志适合查看具体事件,指标适合观察一段时间内有多少请求失败、请求变慢是否普遍存在。两者解决的问题不同。

Q3:为什么不能把每个 Span 的耗时直接相加?

因为部分操作存在包含关系或并行关系,例如订单服务的处理时间中已经包含等待库存服务的时间,直接相加会重复计算。


🧪 小练习

  1. 启动订单服务与库存服务,连续执行两次 curl,确认 两次请求的 requestId 不同 ,但每次请求在两个服务中的 ID 一致。
  2. 将库存服务的等待时间从 1200 改为 100 毫秒,再次请求,观察订单接口响应与日志的变化。
  3. 根据本篇的假设指标表,依次说明应该看哪类追踪信息、使用什么字段查找日志,以及如何确认库存服务是慢点。

验收标准: 能用同一个 requestId 关联多个服务的日志,并说明指标、追踪、日志分别解决什么排查问题。


🎉 恭喜你完成本篇学习!现在你已经能够结合关联日志、指标和分布式追踪,分析一笔订单请求在多个服务之间出现的故障。