如何配置 Apache 为动态应用提供全链路追踪-Apache-PHP中文网

apache可通过mod_unique_id为每个请求生成唯一id并透传至下游，需启用模块、用header和requestheader注入x-request-id头、通过%{unique_id}e写入日志，且集群须ntp同步与主机名可解析。

如何配置 apache 为动态应用提供全链路追踪

Apache 本身不直接提供全链路追踪能力，但可作为入口网关，为后端动态应用（如 PHP、Python、Node.js、Java 等）生成并透传统一请求 ID，构成链路追踪的起点。关键不是让 Apache “做追踪”，而是让它可靠地“种下 trace ID”并确保它贯穿整个调用链。

这是最轻量、最原生的 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）

只生成 ID 没用，必须显式暴露和传递：

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

下载

返回给客户端（供前端调试或埋点）：Header always set X-Request-ID "%{UNIQUE_ID}e"
透传给后端服务（如通过 ProxyPass 反代）：RequestHeader set X-Request-ID "%{UNIQUE_ID}e" env=UNIQUE_ID —— env=UNIQUE_ID 条件不可省略，否则未生成 ID 时会透传空值
若上游（如 LB）可能已带 ID，可用 RequestHeader setifempty X-Request-ID "%{UNIQUE_ID}e" 避免覆盖

将 ID 写进 access.log，是日志聚合与链路对齐的基础：

定义日志格式：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 失败、缓存直出）

若后端已集成 SkyWalking、OpenTelemetry 等，Apache 不需额外埋点，只需保证 ID 透传一致：

后端服务应读取 X-Request-ID 并将其设为 trace ID 的基础（如 SkyWalking Agent 支持 agent.ignore_suffix 或自定义 context extractor）
避免混用：UNIQUE_ID 是纯字符串，不兼容 W3C traceparent 格式；若需标准兼容，建议后端生成 traceparent，并由 Apache 透传该头（而非 UNIQUE_ID）
集群部署时，所有 Apache 节点须启用 NTP 时间同步（误差 ≤1 秒），且主机名唯一可解析，以保障 ID 全局唯一性