第 50 章 调试与诊断组合：日志、统计与故障注入

本章导读

卷五收官章（组合章型）不教新模块——它把分散在三章的观测工具串成调试作战管线：故障注入（第 6 章）主动制造极端条件（OOM、故障路径），内存统计（第 6 章）给出量级与趋势的数字证据，日志（第 38/39 章）还原现场与因果链。三者各司其职：注入制造"病"、统计定位"病在哪一层"、日志回答"当时发生了什么"。组合章的论点：调试能力不是工具箱的堆砌，是工具之间的协作设计——注入点选在哪、统计窗口怎么划、日志记什么字段，这些"怎么串"的决策比工具本身更值得设计。

50.1引入

一个真实的排障场景：服务在production 偶发内存上涨，每周重启一次续命。没有观测体系的排障路径：猜测（"是不是连接没关？"）→ 加 printf → 重启观察 → 再猜——循环数周。有作战管线的路径：先开统计窗口（前后快照对比确认"涨的是什么量级、什么类型"）→ 锁定可疑路径后上调试堆（VisitLive 找到未释放的分配与出生位置）→ 顺手做故障注入验证失败路径（注入 OOM 看回滚是否完整——泄漏常与失败路径不完整伴生）→ 日志的级别与字段早已按结构化部署，时间线直接可查。同一个问题，数周变数小时——差距不是聪明，是管线的三个环节互相供弹。

第二个场景是预防性的：新写的资源管理模块要验收。注入逐次扫描全部分配失败点（第 6 章的 OOM 骨架）、统计验证活跃归零、日志记录每个失败路径的错误链——发布前的体检与事后的尸检用的是同一套管线，只是顺序不同（体检先注入后观察，尸检先观察后注入）。

50.2概念

作战管线全景

注入点选择：不是全部扫一遍

故障注入的暴力答案是"每个分配点都注入一遍"（第 6 章练习的做法，正确但慢）。生产级的选择策略：边界优先——资源获取点（打开/分配/连接）的失败回滚最复杂，优先扫；新增优先——新代码的失败路径没被生产验证过，发布前必扫；改动优先——重构过的路径重扫。三个优先级把扫描预算（时间）花在刀刃上——第 26 章"边界值先于覆盖面"的测试观在资源维度的投影。

统计窗口与日志字段的联动设计

观测工具的字段联动是组合设计的核心一课。统计窗口的边界（Reset/Get 两个时刻）应该与日志的时间戳可对齐——"窗口内发生了什么"由日志的时间线回答；日志的结构化字段应该包含统计关心的维度——每条请求日志带分配量级字段（alloc_bytes），统计异常时能从日志反查是哪类请求贡献的；注入测试的断言输出应该走日志（结构化）而不是 printf——测试报告因此可检索、可对比。三个工具的字段设计在动手前统一规划——这是"组合章"存在的意义：单章教你用工具，组合章教你设计它们的接口。

调试堆的伦理：开销与时机

调试堆（memory_debug）的明细记录有可观开销——生产环境长期开启是奢侈的。时机策略：按需开启（收到告警或排查时开一段窗口）、窗口内复现（开堆后跑触发负载）、及时关闭（取到证据就关，别让它影响性能测量）。统计模块则相反——几乎零开销、生产可常开（趋势监控的哨兵）。两者配合的形态：统计常开做"有没有问题"的哨兵，调试堆按需做"问题在哪"的放大镜——便宜的常开、昂贵的按需，这是观测体系的经济学。

错误链在诊断中的位置

第 4 章错误链（原因链）在诊断管线里有专属位置：日志的错误字段（xrtLogFieldError）携带完整原因链——资源释放失败 → 底层 IO 错误 → 系统错误码三节链一次看全。排障时"表面错误"（资源释放失败）与"根因"（磁盘满）在同一对象里——不需要跨日志行拼凑因果。错误链的层级设计（第 4 章"边界包装"纪律）直接决定日志的诊断价值——包装得好，一层日志看全案；包装得差，三层日志拼不出因果。

50.3示例

完整程序：三环联动体检

体检管线的最小实现——统计开窗、注入失败、日志记录，三环走完：

/* health_check.c —— 发布前体检：注入 → 统计 → 日志联动 */
#define XRT_MODULE_ALL
#define XRT_IMPLEMENTATION
#include <xrt.h>
#include <stdio.h>

static xlogger* gLog;

static bool businessRun(void)
{
	/* 被检业务：分配两块、正常路径释放一块、失败路径应释放全部 */
	ptr pA = xrtMalloc(64);
	ptr pB = xrtMalloc(128);
	bool bOk = false;

	if ( (pA != NULL) && (pB != NULL) ) {
		bOk = true;
	}
	xrtFree(pA);
	xrtFree(pB);
	return bOk;
}

int main(void)
{
	xmemstats Stats;
	int iPass = 0;
	int iFail = 0;

	gLog = xrtLogCreate(XRT_STR_LITERAL("health"), XLOG_DEBUG);
	if ( gLog == NULL ) {
		return 1;
	}

	/* 第一环：统计开窗 */
	xrtMemStatsEnable();
	xrtMemStatsReset();

	/* 第二环：注入扫描（前 N 次成功第 N+1 次失败的语义） */
	for ( uint64 N = 0; N < 3; ++N ) {
		xrtMemDebugEnable(true);
		xrtMemDebugFailAfter(N);
		if ( businessRun() ) {
			++iPass;
		} else {
			++iFail;
			/* 第四环：失败走结构化日志（错误链随行） */
			xrtLog(gLog, XLOG_WARN, XRT_STR_LITERAL("inject point failed"));
		}
		xrtMemDebugFailClear();
		xrtMemDebugEnable(false);
	}

	/* 第三环：窗口读数——活跃应为零（失败路径回滚完整） */
	xrtMemStatsGet(&Stats);
	printf("pass=%d fail=%d live=%llu\n",
		iPass, iFail,
		(unsigned long long)(Stats.MallocBytes - Stats.FreeBytes));
	xrtLogFree(gLog);
	return (Stats.MallocBytes - Stats.FreeBytes) == 0 ? 0 : 1;
}

这段代码的站位。 三环的紧凑合体：统计的 Reset/Get 划出测量窗口（业务跑之前与之后）；注入的 FailAfter(N) 循环扫描前三个分配点（businessRun 恰好分配两次——第三个注入点无事发生、天然通过）；日志在失败分支留下结构化记录（真实项目里这里带错误链字段）。live=0 是整段代码的核心断言：任何注入点下业务失败后，资源全部归还——这就是"失败路径回滚完整"的机器证言。把这段骨架换成你的业务函数，就是模块级的发布前体检。

完整程序：泄漏定位器

尸检管线——统计发现异常后，调试堆定位泄漏来源：

/* leak_hunt.c —— VisitLive 找未释放分配与出生位置 */
#define XRT_MODULE_ALL
#define XRT_IMPLEMENTATION
#include <xrt.h>
#include <stdio.h>

static bool reportLeak(const xmemdebugallocation* pAlloc, ptr pData)
{
	size_t* pCount = (size_t*)pData;

	++(*pCount);
	printf("leak: %zu bytes at %s:%d\n",
		pAlloc->Size, pAlloc->File, (unsigned)pAlloc->Line);
	return true;   /* 继续遍历 */
}

int main(void)
{
	size_t iLeaks = 0;

	xrtMemDebugEnable(true);

	/* 模拟被检业务：一块故意不释放 */
	(void)xrtMalloc(256);

	iLeaks = xrtMemDebugVisitLive(reportLeak, &iLeaks);
	printf("total leaks=%zu\n", iLeaks);
	xrtMemDebugEnable(false);
	return 0;
}

这段代码的站位。 尸检的核心一环：xrtMemDebugVisitLive 遍历当前仍存活的分配——每笔带尺寸与出生位置（文件:行号，第 5 章 At 族的功劳）；回调里打印清单与计数。真实用法里把"模拟业务"换成复现负载，leak 清单就是修复路线图。与体检管线的配合：统计发现 live 不归零（哨兵响）→ 上调试堆跑复现（放大镜）→ VisitLive 出清单（证据链）→ 修复后回归体检（验证）。两段程序合起来就是完整的"防-诊-治"闭环——发布前体检拦新病、运行期哨兵报异常、按需定位出清单。

环节设计的四个检查项（第 36 章的观测版）

第 36 章给数据管线定了四个环节检查项，观测管线有它的镜像版。检查一：观测问题明确吗——每件观测工具回答一个明确问题（统计答"有没有/多大"、调试答"在哪"、注入答"极端下会怎样"、日志答"何时/为何"）——回答两个问题的工具不存在，需要两个观测的也不该塞进一个。检查二：字段规划了吗——窗口边界、关联 ID、量级字段、错误链在设计期统一（坑 1 的执法对象）。检查三：开销付对地方了吗——哨兵常开、放大镜按需（坑 2 的执法对象）。检查四：断言可机器化吗——体检的结论（live=0、注入点清单）是可 grep 的结构化输出，不是人眼看的报表。四项过完，观测体系就是"可运维的"，而不是"能跑的"。

从组合章回望卷五：系统服务的观测面

卷五收官，回望本卷会发现调试管线其实是全卷的浓缩：日志两章给了时间线与结构化字段、第 6 章（卷一）给了注入与统计、第 4 章给了因果链、文件族给了"窗口快照落盘对比"的载体（把统计窗口数据写文件做前后 diff）、异步与信号给了"观测不停服"的部署形态（重载观测配置用 SIGHUP 路径）。系统服务的每个模块都在为观测能力供弹——这是"可观测性不是模块而是架构属性"的具体含义。带着这个视角回看卷五各章契约区，你会发现至少一半的条款在为诊断服务。

一个工作观：观测是付费保险

观测体系的投入像保险：不出事时是纯成本（开销、字段设计时间、体检脚本维护），出事时是全部回报（小时级定位 vs 周级猜测）。三个投保建议：基础险必买——统计哨兵常开 + 结构化日志带关联 ID，成本最低、覆盖最广；重灾区加保——资源密集模块（池/连接/缓存）加体检脚本与 leak 定位演练；理赔流程演练——告警触发后的开堆-复现-取证路径每季度演练一次（没有演练的保险等于没买）。保险观把观测从"技术决策"升维成"风险决策"——预算紧张时砍哪项保哪项，答案与保险精算同构。

50.4契约

• 管线次序：侦察（统计）→ 定位（调试堆）→ 验证（注入）→ 时间线（日志）——每环的产出是下环的输入。
• 注入预算：边界优先、新增优先、改动优先——扫描花在刀刃上，不是全量遍历。
• 字段联动：窗口边界对齐日志时间戳、日志带统计维度字段、断言输出走结构化日志——动手前统一规划。
• 观测经济学：统计常开（哨兵）、调试堆按需（放大镜）——便宜的常开、昂贵的按需。
• 错误链位置：日志错误字段携带完整原因链——包装层级决定诊断价值（第 4 章边界纪律）。
• 体检与尸检同构：同一套管线、不同次序——发布前与运行期不学两套。

演进路径：从无到有的观测建设

观测体系不是一天建成的，四级演进各有投入产出。第一级（能用）：printf 换结构化日志 + 统计哨兵常开——一周工作量，覆盖"出了事至少有时间线"。第二级（可诊）：关联 ID 进全部日志字段 + 错误链规范包装 + 统计窗口例行化——时间线能串起因果。第三级（可验）：核心模块发布体检（注入扫描+归零断言）+ leak 定位演练——新病发布前被拦。第四级（可自愈）：告警驱动自动开窗取证 + 观测配置热重载（SIGHUP 路径）+ 体检回归进 CI——观测本身成为服务的一部分。多数团队停在第一级半；三级是性价比拐点（新病拦截的收益开始超过投入）；四级适合规模化服务。你的团队在几级、下一个里程碑是什么——这是技术负责人该答的问题。

逐站精讲：注入扫描的实战形态

第 6 章 OOM 骨架的"逐次扫描"在实战中的完整形态值得展开。扫描范围测定：先跑一次统计窗口拿到分配总量（比如 200 次），扫描预算按注入预算裁（边界优先选前 50 个资源获取点）。断言三件套：每个注入点下——失败如期发生（注入点生效）、错误链完整（日志可查）、活跃归零（回滚完整）。误报甄别：某些"失败"是正常业务降级（重试成功）——断言要区分"失败被正确处理"与"失败被错误吞掉"，前者 pass 后者 fail。产物归档：扫描结果写文件（注入点清单+三件套结果），回归时对比差异——第 46 章原子交付保证归档本身完整。这个形态把"注入"从玩具升级为可回归的测试资产。

逐站精讲：日志字段的诊断字典

结构化日志的字段设计是观测体系的"数据模型"，一份诊断字典收尾：关联字段——request_id（请求全链路）、trace_id（跨服务）、session_id（用户会话）——时间线串接的主键；量级字段——alloc_bytes/duration_us/count——统计异常的反查维度；状态字段——level、error（错误链）、result——分布与失败率的统计源；上下文字段——module、source（代码位置）、endpoint——定位的落点。字段命名稳定（日志是下游依赖，改名是破坏性变更）；字段集合有版本（新字段可加、老字段不改义）；字典本身进文档——新成员看得懂日志，才能用好时间线。这份字典与第 32 章 JSON Schema 的精神一致：数据模型先于数据积累。

三个高频诊断剧本

三个剧本把管线落到具体症状上。剧本一：内存缓慢上涨——统计哨兵确认（窗口对比：涨的是 pooled 还是 direct）→ 按上涨类型排查（pooled 涨查池泄漏、direct 涨查裸分配）→ 调试堆开窗复现 → VisitLive 出清单 → 修复后注入回归。剧本二：偶发失败无规律——日志按错误类别过滤（第 38 章级别策略）→ 关联 ID 串起失败请求的完整时间线 → 定位到共享状态 → 注入并发压力复现（竞争类）或注入 IO 失败复现（环境类）。剧本三：启动即崩——注入最早的几个分配点（启动路径的 OOM 常被漏测）→ 错误链看第一环 → 修复后全启动路径扫描。三个剧本的共同结构：症状 → 管线入口选择 → 环节次序 → 证据形态——把它们抄进团队的排障手册，新人第一次值班的慌张至少减半。

一个反模式警示：观测驱动设计

最后一条警示平衡本章的立场：观测很重要，但观测不能替代设计。反模式的形状：错误处理乱写（"反正日志能看到"）、资源纪律松散（"反正统计能发现"）、失败路径跳过（"反正注入能拦"）——把观测当成了设计缺陷的补偿器。正确的分工：设计保证正确，观测验证正确——第 4 章错误链先按边界纪律包装好，日志才有可读的链；第 5 章所有权先配平，统计才归零；失败路径先写完整，注入才通过。观测体系的价值建立在设计质量之上——地基是设计，保险是观测，顺序不能反。带着这条警示离开卷五，你在卷六会看到它以更强形式出现：并发的正确性靠设计（锁协议/消息传递），观测只能发现违例。

常见错误

/* 统计窗口随手开、注入结果 printf、日志想到再补 */
xrtMemStatsReset();
RunLoad();
printf("done\n");                    /* 注入/结果走 printf——时间线之外 */

/* 窗口边界、日志字段、断言输出三者在设计期对齐 */
xrtLog(gLog, XLOG_INFO, XRT_STR_LITERAL("window start"));   /* 窗口边界入日志 */
xrtMemStatsReset();
RunLoad();
xrtMemStatsGet(&Stats);
xrtLogFieldInt(gLog, XLOG_INFO, XRT_STR_LITERAL("live_bytes"),
	(int64)(Stats.MallocBytes - Stats.FreeBytes));   /* 读数进结构化日志——时间线可查 */

int main(void)
{
	xrtMemDebugEnable(true);   /* 启动即开——全程付明细开销 */
	/* ... 数月的生产运行 ... */
}

int main(void)
{
	xrtMemStatsEnable();        /* 哨兵常开：几乎零开销 */
	/* ... 生产运行 ... */
}
void onMemoryAlert(void)        /* 告警触发时 */
{
	xrtMemDebugEnable(true);    /* 放大镜按需：开窗复现取证 */
	RunRepro();
	xrtMemDebugVisitLive(...);  /* 取证后即关 */
	xrtMemDebugEnable(false);
}

编程练习

小结