晚上八点,网关开始报 502,错误率从 0.2% 涨到 18%。值班的三个人分别打开三套界面:一个人看 nginx 日志,满屏是 upstream timeout;一个人看应用日志,只有零散的 error,时间戳还和网关差了两分钟;第三个人看监控大盘,CPU 40%、内存 65%,一切正常。四十分钟后,才有人在应用日志里翻到一条「调用风控接口超时 30000ms」,而那条日志没有任何请求 ID,无法确认它和用户投诉的那批订单是不是同一个请求。
最后定位是风控服务的一个依赖变慢,导致应用线程池被占满,网关排队超时。问题本身不复杂,慢的是「找」。日志、指标、追踪三套数据都在,但彼此对不上:日志没有请求标识,指标没有分接口的延迟,追踪到了网关就断了。
可观测性不是「多打日志」,而是让这三类数据能互相指认。这篇按「各自回答什么、字段怎么带、出事先看哪个」讲。
三类数据的分工
三者的关系可以这样理解:指标告诉你「有事」,追踪告诉你「哪条链路」,日志告诉你「具体为什么」。只做其中一层,排查时就会缺一环。
把它们串起来的是一枚共享的标识。请求进入系统时生成一个 request ID,同时作为 trace ID;日志每行都带它,追踪的每个 span 也带它,指标虽然不存这个值,但可以在示例里挂上。用户报障时提供一个 ID,你就能从指标跳到追踪、再到日志,而不是在三套系统里各查一遍。没有这枚标识,三套数据只是三堆各自为政的文件。
很多团队只做日志和 CPU 监控,出了故障却不知道从哪下手。原因不是数据少,而是没有把「一次请求」串起来。下面这张表是常见的缺失。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 报警了,但不知道是哪个接口 | 指标按服务聚合,没有路由维度 | 看指标标签里有没有 route、method、status |
| 日志里找不到用户投诉的那次请求 | 没有请求 ID,或 ID 没返回给客户端 | 查响应头是否带 request id,日志是否打印同一个值 |
| 调用链在网关处断开 | 网关没有透传 trace 头,或服务没有继续传播 | 抓一次请求的入站与出站头,看 traceparent 是否一致 |
| 平均值正常,用户却一直喊慢 | 只看平均延迟,尾部请求被平均掉 | 看 P95、P99 和最大延迟,而不是 average |
| 日志磁盘一天涨几十 GB | info 级别打印请求体和响应体,没有采样和轮转 | 看日志量最大的几个字段和级别分布 |
| 三套系统时间对不上 | 容器时区不一致,或日志用了本地时间 | 对比各服务的 date -u 与日志时间戳 |
| 加了标签后监控查询越来越慢 | 标签用了用户 ID、订单号这类高基数值 | 看指标的标签基数与存储成本 |
这些问题的共同点是:数据存在,但缺少关联键。修复顺序应该是先加关联键,再考虑换更贵的平台。
日志:结构化,带请求标识
日志的第一条规则是结构化。不要拼字符串,直接输出一行 JSON,字段固定。这样日志系统才能按字段检索,而不是靠正则捞。
{"ts":"2026-11-07T08:30:00.123Z","level":"error","service":"order-api",
"trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7",
"route":"POST /v1/orders","status":502,"duration_ms":30012,
"error":"upstream timeout","upstream":"risk-service"}
必须有的字段:UTC 时间、级别、服务名、trace_id、span_id、路由、状态码、耗时。可选但常用的:用户 ID(脱敏或哈希)、租户 ID、下游服务名、重试次数。不要打印密码、token、完整身份证号、银行卡号,日志系统往往比业务库更容易被更多人访问。
级别要克制。debug 只在本地或临时排障时开;info 记录关键业务事件,不要每个函数进出都打;warn 记录可恢复的异常;error 记录需要人看的失败。一个请求打十几条 info,量上来后成本很高,真正出事时反而被噪声淹没。
日志要能轮转和保留。按天或按大小切分,保留七天到三十天,冷数据归档。不要把日志当数据库用,更不要用日志做业务统计;需要统计就写指标或落库。
高流量服务还要做日志采样。成功请求只保留一小部分,错误和慢请求全留;采样要按 trace ID 稳定哈希,保证同一条请求的日志要么都留、要么都不留,不能一半有一半没有。采样的比例写进配置,随流量调整。日志少了会丢线索,多了会拖慢写入、撑爆磁盘,采样是在两者之间找平衡。
指标:看分位值,不看平均值
指标的第一条规则是选对维度。服务级指标至少要有四个方向:流量(QPS)、错误(错误率、错误码分布)、延迟(P50、P95、P99)、饱和度(线程池、连接池、队列长度、CPU、内存)。这四个方向常被称为 RED 和 USE 的组合,够用来判断「是不是整体出问题」。
延迟一定要看分位值。假设 100 个请求里 99 个耗时 10 毫秒,1 个耗时 3 秒,平均值是 39.9 毫秒,看起来很好;但那个 3 秒的请求对应的用户已经准备关页面了。P99 才能反映尾部体验。分位值也不要只存一个,P95 和 P99 一起看,能判断是少量极端还是大面积变慢。
指标标签要控制基数。route、method、status、service 这类有限集合可以打;用户 ID、订单号、URL 里的完整路径参数不能打。一个标签有十万个不同值,监控系统的存储和查询会先崩,比故障本身更难处理。
直方图的分桶也要按业务定。桶边界设得太粗,P99 落在两个大区间之间,看不出具体变化;设得太细,序列数量暴涨。通常按目标延迟设几个关键边界,比如 50 毫秒、100 毫秒、300 毫秒、1 秒、3 秒,覆盖正常、变慢、故障三档。平均值可以算,但只能当参考,不能当告警依据。
告警最好和用户体验挂钩。可以用「错误预算」的思路:一个月允许 0.1% 的请求失败,消耗速度超过预期就报警,而不是盯着某个瞬时错误率。这样能过滤掉几秒钟的抖动,也能在持续劣化时提前发现。阈值要按接口的重要程度分别设,支付接口和头像接口不该共用一个标准。
告警要基于「用户能感知的信号」,而不是「资源阈值」。CPU 80% 不一定有事,错误率 5% 或 P99 超过 1 秒通常已经影响用户。资源指标可以用来解释原因,不适合作为唯一的报警条件。
链路追踪:把一次请求串起来
链路追踪的核心是一个 trace ID,从请求进入系统开始生成,沿途每个服务、每个下游调用都带上它。每段处理叫一个 span,记录开始时间、耗时、状态和关键属性。最后这些 span 组成一棵树,一眼能看出哪一跳最慢。
传播靠 HTTP 头。业界通用的是 W3C Trace Context,请求头叫 traceparent,值里包含版本、trace ID、parent span ID 和采样标志。服务收到后继续用这个 trace ID,给下游发请求时再带上新的 parent span ID。异步消息也要传播:把 trace 信息写进消息头,消费者取出后继续,否则链路在入队处就断了。
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
全量采集成本高,通常要采样。头部采样是在入口决定采不采,整条链路要么全采要么全不采,实现简单;尾部采样是先收集所有 span,再按错误、慢请求、特定用户保留,能保住关键样本,但需要先缓存。多数系统用「低比例头部采样 + 错误全采」的组合,既控制成本,又不漏掉故障。
追踪不要只记录「成功」,失败和超时更要记录。一个 span 如果只有开始时间没有结束时间,或者状态是 unknown,排障时反而添乱。异步任务、后台线程、消息消费都要显式结束 span,否则会出现大量悬挂节点。
span 上要带足够但不过量的属性:服务名、操作名、状态、错误类型、下游地址、重试次数。不要把完整请求体塞进属性,那会让追踪系统变成第二个日志库。需要看具体参数时,用 trace ID 去查日志,两边靠 ID 对齐。属性命名也要统一,http.status_code 和 status 混着用,查询时就得写两套条件。
跨异步边界时,trace 上下文要显式传递。发消息前把 trace ID 写进消息头,消费时取出来继续;线程池里提交任务时,把上下文一起带过去,不能依赖线程本地变量自动继承。很多「链路断在队列」的问题,都是因为消息生产者没有把上下文写进去,消费者自然接不上。
出事了,按什么顺序看
第一步看指标大盘,确认影响面:是全局还是某个接口,是错误率涨还是延迟涨,从几点开始。不要一上来就翻日志,日志量太大,没有方向会翻到天亮。
第二步看追踪,找一条失败或慢的请求,看它经过哪些服务、哪一段耗时最长、哪一段返回错误。trace ID 拿到后,第三步再去日志系统按这个 ID 过滤,看具体的错误信息和上下文。这个顺序能把「大海捞针」变成「按图索骥」。
如果连 trace 都没有,退而求其次:先用指标定位接口和时间段,再用日志里的路由、状态码、用户 ID 缩小范围。这也要求日志字段齐全,否则只能靠时间戳硬猜。
跨系统排查时,先校准时间。网关、应用、数据库的时钟可能差几秒,日志时间戳又有的是本地时间、有的是 UTC。先看各系统的时间戳格式和时区,把范围对齐,再按 trace ID 或用户 ID 过滤。时间对不上,后面所有关联都是错的,越查越乱。
排查完之后要补缺口:这次缺请求 ID,就加请求 ID;这次 trace 断了,就补网关透传;这次指标没有路由维度,就加标签。每次故障都应该让下一次更快,而不是只修好当下。
X-Request-Id,并在日志里打印同一个值。用户报障时让他提供这个 ID,比问「你几点点的」有效得多。这个改造成本很低,收益却很直接。一套可落地的骨架
先用一个中间件把请求标识和耗时打出来,不依赖任何第三方平台也能落地。
const crypto = require("crypto");
app.use((req, res, next) => {
const traceId = req.get("traceparent")?.split("-")[1]
|| crypto.randomUUID().replace(/-/g, "");
const started = process.hrtime.bigint();
res.set("X-Request-Id", traceId);
res.on("finish", () => {
const ms = Number(process.hrtime.bigint() - started) / 1e6;
console.log(JSON.stringify({
ts: new Date().toISOString(),
level: res.statusCode >= 500 ? "error" : "info",
service: "order-api",
trace_id: traceId,
route: req.method + " " + req.route?.path,
status: res.statusCode,
duration_ms: Math.round(ms)
}));
});
next();
});
指标用 Prometheus 的文本格式暴露,最小实现只需要一个 /metrics 接口。下面只示意格式,采集与展示需要 Prometheus 和 Grafana,未在本机实测。
# HELP http_request_duration_seconds 请求耗时
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{route="/v1/orders",le="0.1"} 980
http_request_duration_seconds_bucket{route="/v1/orders",le="0.5"} 995
http_request_duration_seconds_bucket{route="/v1/orders",le="1"} 999
http_request_duration_seconds_bucket{route="/v1/orders",le="+Inf"} 1000
http_request_duration_seconds_sum{route="/v1/orders"} 42.5
http_request_duration_seconds_count{route="/v1/orders"} 1000
从这组直方图能读出:1000 个请求里 999 个在 1 秒内,剩下 1 个超过 1 秒;平均值是 42.5 毫秒,看起来正常,但尾部确实有一个慢请求。只看 sum 和 count 算平均,会把这个信号抹掉。
更进一步,可以给直方图挂 exemplar:在每个桶里附一个具体的 trace ID。这样从监控面板看到「1 秒以上有 1 个」,可以直接点进那条 trace,看到它慢在哪一跳、对应哪行日志。exemplar 让指标、追踪、日志真正连成一条线,比在三套系统之间手工复制 ID 高效得多。
日志收集可以用 Filebeat 或 Fluent Bit 采集到 Loki、Elasticsearch;追踪可以用 OpenTelemetry SDK 自动埋点。部署配置这里不展开,未在本机实测。无论用哪套,字段名和 trace 传播格式要先统一,否则后期迁移成本很高。
验证方法:本机起服务,请求一次,确认响应头有 X-Request-Id,日志里有同一个 trace_id;人为让下游超时,确认日志级别变成 error、耗时字段正确;连续请求 100 次,确认 /metrics 的 count 增加 100。
边界与代价
可观测性是有成本的。日志存储、指标基数、追踪采样,都会直接变成账单。小系统一天几十 GB 日志、几百万条 span,成本可能超过服务器本身。先保留关键字段和关键链路,比全量收集更可持续。
数据多不等于看得清。没有统一字段、没有 trace 传播、没有告警分级,收集再多也只是把噪声集中起来。先定字段规范,再谈采集方案;先让一次请求可追踪,再谈全量覆盖。顺序反了,投入会一直增加,排障时间却下不来。
采样会漏掉长尾。低比例采样下,一个罕见的慢请求可能根本没被记录。对错误和超时要单独提高采样率或全采,不能和正常请求一个比例。
追踪不能替代日志。span 能告诉你哪一段慢,但通常不记录完整的业务上下文。定位到具体原因,还是要回到日志。
指标不能太细。给每个用户、每个订单打标签,短期看起来方便,长期会把监控系统压垮。需要细粒度分析时,应该把数据落到数据仓库,而不是塞进指标。
过度设计的信号:系统只有两个服务、日请求量几万,却自建了日志平台、追踪平台、指标平台三套集群。先用云服务或开源单机版,把字段和 trace 打通,规模上来再拆。
当天可以自验的五件事
- 随便调一个接口,看响应头有没有请求 ID;没有就加,成本最低、收益最直接。
- 把应用日志改成一行 JSON,至少包含时间、级别、trace_id、路由、状态、耗时六个字段。
- 查一次线上指标,确认延迟看的是 P95/P99 而不是平均值;如果只有平均值,先加直方图。
- 抓一次跨服务请求,检查
traceparent是否从入口透传到下游;断在哪一跳就补哪一跳。 - 模拟一次下游超时,按「指标、追踪、日志」的顺序走一遍,记录每一步花了多久;超过十分钟的环节就是要补的地方。
下一篇讲容器化与部署。观测手段解决「出事能看见」,部署方式决定「出事多不多」。镜像怎么打、反向代理怎么配、健康检查怎么做、配置怎么注入,这些基础动作做错,前面的限流和追踪都会打折扣。