如何实现 Apache 反向代理下的全链路分布式追踪-Apache-PHP中文网

apache反向代理需配合mod_unique_id生成unique_id环境变量，显式通过header/requestheader注入x-request-id头并透传下游，写入含%{unique_id}e的日志，且下游服务须识别该id延续追踪，才能构成完整链路。

如何实现 apache 反向代理下的全链路分布式追踪

Apache 反向代理本身不提供分布式追踪能力，它只能作为链路起点或中继节点，需配合 mod_unique_id 生成基础请求 ID，并通过头透传、日志记录和下游服务协同，才能构成完整链路。关键不是“Apache 做追踪”，而是“Apache 如何可靠地参与追踪”。

该模块是 Apache 内置但默认未加载的组件，负责为每个请求生成唯一字符串（如 VxYz1aB2cD3eF4gH5iJ6kL），存入环境变量 UNIQUE_ID。

Debian/Ubuntu：运行 a2enmod unique_id && systemctl reload apache2
RHEL/CentOS：取消 httpd.conf 中 LoadModule unique_id_module modules/mod_unique_id.so 的注释，再重载
验证是否生效：httpd -M | grep unique_id 应输出 unique_id_module (shared)
若启动失败提示 “unable to find IPv4 address of xxx”，说明主机名无法解析，需在 /etc/hosts 补全本机映射（如 127.0.0.1 your-hostname）

UNIQUE_ID 默认不出现在响应头或转发请求中，必须显式配置；否则前端收不到，后端也接不到，链路在第一跳就断了。

Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。

下载

返回给客户端（供前端调试或埋点）：
Header always set X-Request-ID "%{UNIQUE_ID}e"
透传给后端服务（如 PHP/Python/Node.js）：
RequestHeader set X-Request-ID "%{UNIQUE_ID}e" env=UNIQUE_ID
⚠️ 必须加 env=UNIQUE_ID，否则未生成 ID 时会透传空值，下游看到的是 X-Request-ID:（冒号后为空）
若上游已带 ID（例如经负载均衡器转发），可用 setifempty 避免覆盖：
RequestHeader setifempty X-Request-ID "%{UNIQUE_ID}e"

把 ID 写进 access log，是后续做日志聚合与链路还原的基础。只靠响应头发出去还不够，服务器自身也要留痕。

定义含 ID 的日志格式：
LogFormat "%{UNIQUE_ID}e %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" trace_log
应用到虚拟主机：
CustomLog /var/log/apache2/access.log trace_log
验证方式：发起请求后查日志，首字段应为 24 位 Base64 字符串；若看到 -，说明该请求未进入 Apache 完整处理流程（如被 WAF 拦截、SSL 握手失败、缓存直出等）

Apache 只管发，不管下游怎么用。要形成真正“全链路”，下游服务必须识别并延续这个 ID，不能丢、不能改、不能忽略。

后端服务应优先读取 X-Request-ID 作为 trace ID 主键，而非自己生成新 ID
若下游使用 SkyWalking、Zipkin 或 OpenTelemetry，需确认其 SDK 支持从 HTTP 头提取自定义 ID（如 SkyWalking 的 apache.skywalking.plugin.http.httpclient.header.propagation 配置）
建议在下游日志中统一注入该 ID（如通过 MDC 或 structured logging），使业务日志、中间件日志、数据库慢日志都能按此 ID 关联
集群部署时注意：UNIQUE_ID 在单机内唯一，跨机器不保证全局唯一；若需强全局唯一，应在应用层补充时间戳+主机标识，或改用兼容 W3C TraceContext 标准的方案（如 OpenTelemetry 的 traceparent 头）