尧图网页设计 
Envoy 访问日志新增 DS_RX_HDR_END 时间点用 %COMMON_DURATION% 精确统计下游请求头接收耗时【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本篇技术指南聚焦 Envoy 在%COMMON_DURATION%访问日志格式化器中新增的DS_RX_HDR_ENDDownstream request headers fully received下游请求头完全接收时间点说明它如何帮助你精确测量从请求开始到请求头完整到达的耗时并结合 stream_info_formatter.cc 源码与 substitution_formatter.rst 官方文档给出完整的语法、时间点参考表与可落地的访问日志配置方案。一、功能背景什么是 DS_RX_HDR_ENDEnvoy 的访问日志格式化器允许在日志模板中嵌入大量命令操作符command operator来提取请求生命周期中的各类数据详见 usage.rst。其中%COMMON_DURATION%是一个专用的耗时计算操作符它允许你指定任意两个时间点计算它们之间的时间差。本次变更记录于 access_log__added-ds-rx-hdr-end-time-point.rst为该格式化器新增了一个时间点DS_RX_HDR_END下游请求头完全接收downstream request headers fully received的时间点。此前下游请求接收相关的可用时间点只有DS_RX_BEG下游请求接收开始和DS_RX_END下游请求接收结束无法单独观察请求头接收完成这一中间里程碑。DS_RX_HDR_END的加入使你可以将耗时拆分为更细的语义区间例如DS_RX_BEG:DS_RX_HDR_END请求头接收耗时可用于评估头部大小、连接带宽对首字节处理的影响DS_RX_HDR_END:DS_RX_END请求头接收完成到请求体接收完成的耗时。二、%COMMON_DURATION% 语法速览%COMMON_DURATION%的完整语法为%COMMON_DURATION(START:END:PRECISION)%三个参数的含义完整说明见 substitution_formatter.rst 的config_access_log_format_common_duration章节START起始时间点END结束时间点PRECISION精度可选ms毫秒、us微秒、ns纳秒默认值为ms。例如要记录从请求开始到请求头完全接收的毫秒级耗时格式串中写入%COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:ms)%所有时间点与精度值都是大小写敏感的。从源码实现看CommonDurationFormatter::create会按:将子命令切分为 23 段少于 2 段或多于 3 段都会返回Invalid common duration configuration错误若传入第三个参数但不在ms/us/ns之列则返回Invalid common duration precision错误见 stream_info_formatter.cc。三、完整时间点参考表%COMMON_DURATION%支持的时间点HTTP 场景全部列举如下其中DS_RX_HDR_END即为本次新增项时间点语义DS_CX_BEG下游连接建立被 Envoy 接受的时间点即连接开始时间。注意与US_CX_BEG/US_CX_END不同后者标记的是上游连接建立过程的起止DS_CX_END下游连接关闭的时间点即连接关闭时间DS_HS_BEG下游 TLS 握手开始即收到 ClientHello 的时间DS_HS_END下游 TLS 握手结束DS_RX_BEG下游请求接收开始DS_RX_HDR_END下游请求头接收完成本次新增DS_RX_END下游请求接收结束US_CX_BEG上游 TCP 连接建立开始US_CX_END上游 TCP 连接建立结束US_HS_END上游 TLS 握手结束US_TX_BEG上游请求发送开始US_TX_END上游请求发送结束US_RX_BEG上游响应接收开始US_RX_BODY_BEG上游响应体接收开始US_RX_END上游响应接收结束DS_TX_BEG下游响应发送开始DS_TX_END下游响应发送结束此外未在上表中列出的其他值会被当作自定义时间点处理即按命名键从DownstreamTiming中读取见 stream_info_formatter.cc。TCP 场景下仅支持连接级别的时间点DS_CX_BEG、DS_CX_END、DS_HS_BEG、DS_HS_END、US_CX_BEG、US_CX_END。四、精度控制ms / us / nsPRECISION参数控制最终渲染的耗时单位三个取值全部大小写敏感ms毫秒精度默认值us微秒精度ns纳秒精度。在 stream_info_formatter.cc 的getDurationCount中耗时由单调时钟MonotonicTime相减得到再按精度做duration_cast后返回整数。因此%COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:us)%会输出微秒级整数ns则输出纳秒级整数。高精度选项尤其适合对慢请求头、大头部场景做性能剖析。五、源码实现剖析DS_RX_HDR_END的完整实现链路分为两层。1. 格式化器层的注册与取值在 stream_info_formatter.h 中CommonDurationFormatter定义了三个下游接收相关的时间点常量FirstDownstreamRxByteReceived DS_RX_BEG LastDownstreamHeaderRxByteReceived DS_RX_HDR_END LastDownstreamRxByteReceived DS_RX_END在 stream_info_formatter.cc 的KnownTimePointGetters注册表中DS_RX_HDR_END对应的取数逻辑为先从StreamInfo获取downstreamTiming()若存在则返回其中的lastDownstreamHeaderRxByteReceived()时间点若downstreamTiming不存在则返回空值{LastDownstreamHeaderRxByteReceived, [](const StreamInfo::StreamInfo stream_info) - std::optionalMonotonicTime { const auto downstream_timing stream_info.downstreamTiming(); if (downstream_timing.has_value()) { return downstream_timing-lastDownstreamHeaderRxByteReceived(); } return {}; }},2. 时间点数据的来源lastDownstreamHeaderRxByteReceived的实际读取逻辑位于 utility.cc从stream_info.downstreamTiming()中取出DownstreamTiming再获取lastDownstreamHeaderRxByteReceived()时间点若该时间点尚未被记录则返回nullopt。该时间点由 Envoy 在网络接收路径上调用DownstreamTiming::onLastDownstreamHeaderRxByteReceived记录在 substitution_formatter_test.cc 的测试中通过stream_info.downstream_timing_.onLastDownstreamHeaderRxByteReceived(time_system)触发。可以推断当请求头尚未接收完毕例如连接在头部传输中途被断开时该时间点缺失%COMMON_DURATION%将无法计算出有效耗时。3. 缺失时间点的渲染行为当START或END任一时间点不可用时getDurationCount返回nulloptformat返回空格式化器不会渲染出数值字符串模式下通常呈现为-在 typed JSON 模式下则渲染为 JSONnull。这一行为在 substitution_formatter_test.cc 中得到了完整覆盖在没有任何时间点被设置的情况下除DS_RX_BEG到DS_RX_BEG这种起点等于终点的组合输出0外其余组合均输出空值/null。六、访问日志配置实战%COMMON_DURATION%既可用于传统格式字符串format也可用于结构化 JSON 格式json_format/typed_json_format见 usage.rst。1. 格式字符串format string示例在访问日志配置中将DS_RX_BEG:DS_RX_HDR_END的耗时与默认格式结合输出access_log: - name: envoy.access_loggers.file typed_config: type: type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog path: /dev/stdout format: [%START_TIME%] \%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\ %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% header_rx_ms%COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:ms)%每条日志末尾的header_rx_ms字段即为请求开始到请求头完全接收的毫秒耗时。2. 结构化 JSON 示例使用typed_json_format可以将耗时渲染为 JSON 数字便于日志采集与告警系统直接解析access_log: - name: envoy.access_loggers.file typed_config: type: type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog path: /dev/stdout typed_json_format: start_time: %START_TIME% request_header_rx_ms: %COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:ms)% request_body_rx_ms: %COMMON_DURATION(DS_RX_HDR_END:DS_RX_END:ms)% total_request_rx_ms: %COMMON_DURATION(DS_RX_BEG:DS_RX_END:ms)%输出示例request_header_rx_ms与request_body_rx_ms为数字类型{start_time: 2026-09-12T00:38:54.000Z, request_header_rx_ms: 3, request_body_rx_ms: 2, total_request_rx_ms: 5}注意typed_json_format下操作符必须是字典值中的唯一字符串才会输出类型化数值例如%DURATION%输出数字而%DURATION%.0输出字符串参见 usage.rst。七、边界行为与注意事项大小写敏感DS_RX_HDR_END必须全大写写成小写或混写会被当作自定义时间点名称处理从而取不到值。TCP 场景限制TCP 连接日志仅支持连接级别时间点DS_RX_HDR_END属于 HTTP 请求级别时间点仅适用于 HTTP/THRIFT 访问日志。时间点缺失请求头尚未接收完毕时DS_RX_HDR_END时间点不存在耗时字段将渲染为-或 JSONnull而非0。END 早于 START从当前实现看当END时间点早于START时间点时getDurationCount返回空值而不输出耗时见 stream_info_formatter.cc官方文档同时提示在启用 H/2、H/3 独立半关闭half-close行为时可能出现*_TX_END早于*_RX_END的场景需避免将这类端点作为起止组合。连接复用语义US_CX_*、US_HS_END等上游连接建立时间点在同一连接上的所有请求中重复出现DS_CX_END仅对连接关闭时仍活跃的请求填充其余请求渲染为-。八、测试验证新增时间点并非孤例实现在 substitution_formatter_test.cc 中DS_RX_HDR_END与其余 14 个时间点一起被纳入组合测试矩阵所有时间点、三种精度ms/us/ns两两组合验证时间点未设置时的空值输出为 15 个时间点逐一设置单调时钟时间戳如DS_RX_HDR_END被设为 2ms 处随后验证COMMON_DURATION两两组合的差值计算正确。该测试同时覆盖了非法参数如 4 段子命令、非法精度zs的报错路径保证了格式化器在错误配置下的行为可预期。九、小结DS_RX_HDR_END时间点的加入让 Envoy 访问日志具备了请求头接收完成这一关键里程碑的观测能力。配合%COMMON_DURATION(START:END:PRECISION)%的任意起止组合你可以将下游请求接收阶段细分为请求头接收与请求体接收两段独立耗时从而更精准地定位慢请求是出在头部传输、头部处理还是请求体阶段。配置时只需记住时间点大小写敏感、精度默认毫秒、时间点缺失时输出空值即可安全地在生产访问日志中启用这一新指标。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Envoy 访问日志新增 DS_RX_HDR_END 时间点：用 %COMMON_DURATION% 精确统计下游请求头接收耗时
Envoy 访问日志新增 DS_RX_HDR_END 时间点用 %COMMON_DURATION% 精确统计下游请求头接收耗时【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本篇技术指南聚焦 Envoy 在%COMMON_DURATION%访问日志格式化器中新增的DS_RX_HDR_ENDDownstream request headers fully received下游请求头完全接收时间点说明它如何帮助你精确测量从请求开始到请求头完整到达的耗时并结合 stream_info_formatter.cc 源码与 substitution_formatter.rst 官方文档给出完整的语法、时间点参考表与可落地的访问日志配置方案。一、功能背景什么是 DS_RX_HDR_ENDEnvoy 的访问日志格式化器允许在日志模板中嵌入大量命令操作符command operator来提取请求生命周期中的各类数据详见 usage.rst。其中%COMMON_DURATION%是一个专用的耗时计算操作符它允许你指定任意两个时间点计算它们之间的时间差。本次变更记录于 access_log__added-ds-rx-hdr-end-time-point.rst为该格式化器新增了一个时间点DS_RX_HDR_END下游请求头完全接收downstream request headers fully received的时间点。此前下游请求接收相关的可用时间点只有DS_RX_BEG下游请求接收开始和DS_RX_END下游请求接收结束无法单独观察请求头接收完成这一中间里程碑。DS_RX_HDR_END的加入使你可以将耗时拆分为更细的语义区间例如DS_RX_BEG:DS_RX_HDR_END请求头接收耗时可用于评估头部大小、连接带宽对首字节处理的影响DS_RX_HDR_END:DS_RX_END请求头接收完成到请求体接收完成的耗时。二、%COMMON_DURATION% 语法速览%COMMON_DURATION%的完整语法为%COMMON_DURATION(START:END:PRECISION)%三个参数的含义完整说明见 substitution_formatter.rst 的config_access_log_format_common_duration章节START起始时间点END结束时间点PRECISION精度可选ms毫秒、us微秒、ns纳秒默认值为ms。例如要记录从请求开始到请求头完全接收的毫秒级耗时格式串中写入%COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:ms)%所有时间点与精度值都是大小写敏感的。从源码实现看CommonDurationFormatter::create会按:将子命令切分为 23 段少于 2 段或多于 3 段都会返回Invalid common duration configuration错误若传入第三个参数但不在ms/us/ns之列则返回Invalid common duration precision错误见 stream_info_formatter.cc。三、完整时间点参考表%COMMON_DURATION%支持的时间点HTTP 场景全部列举如下其中DS_RX_HDR_END即为本次新增项时间点语义DS_CX_BEG下游连接建立被 Envoy 接受的时间点即连接开始时间。注意与US_CX_BEG/US_CX_END不同后者标记的是上游连接建立过程的起止DS_CX_END下游连接关闭的时间点即连接关闭时间DS_HS_BEG下游 TLS 握手开始即收到 ClientHello 的时间DS_HS_END下游 TLS 握手结束DS_RX_BEG下游请求接收开始DS_RX_HDR_END下游请求头接收完成本次新增DS_RX_END下游请求接收结束US_CX_BEG上游 TCP 连接建立开始US_CX_END上游 TCP 连接建立结束US_HS_END上游 TLS 握手结束US_TX_BEG上游请求发送开始US_TX_END上游请求发送结束US_RX_BEG上游响应接收开始US_RX_BODY_BEG上游响应体接收开始US_RX_END上游响应接收结束DS_TX_BEG下游响应发送开始DS_TX_END下游响应发送结束此外未在上表中列出的其他值会被当作自定义时间点处理即按命名键从DownstreamTiming中读取见 stream_info_formatter.cc。TCP 场景下仅支持连接级别的时间点DS_CX_BEG、DS_CX_END、DS_HS_BEG、DS_HS_END、US_CX_BEG、US_CX_END。四、精度控制ms / us / nsPRECISION参数控制最终渲染的耗时单位三个取值全部大小写敏感ms毫秒精度默认值us微秒精度ns纳秒精度。在 stream_info_formatter.cc 的getDurationCount中耗时由单调时钟MonotonicTime相减得到再按精度做duration_cast后返回整数。因此%COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:us)%会输出微秒级整数ns则输出纳秒级整数。高精度选项尤其适合对慢请求头、大头部场景做性能剖析。五、源码实现剖析DS_RX_HDR_END的完整实现链路分为两层。1. 格式化器层的注册与取值在 stream_info_formatter.h 中CommonDurationFormatter定义了三个下游接收相关的时间点常量FirstDownstreamRxByteReceived DS_RX_BEG LastDownstreamHeaderRxByteReceived DS_RX_HDR_END LastDownstreamRxByteReceived DS_RX_END在 stream_info_formatter.cc 的KnownTimePointGetters注册表中DS_RX_HDR_END对应的取数逻辑为先从StreamInfo获取downstreamTiming()若存在则返回其中的lastDownstreamHeaderRxByteReceived()时间点若downstreamTiming不存在则返回空值{LastDownstreamHeaderRxByteReceived, [](const StreamInfo::StreamInfo stream_info) - std::optionalMonotonicTime { const auto downstream_timing stream_info.downstreamTiming(); if (downstream_timing.has_value()) { return downstream_timing-lastDownstreamHeaderRxByteReceived(); } return {}; }},2. 时间点数据的来源lastDownstreamHeaderRxByteReceived的实际读取逻辑位于 utility.cc从stream_info.downstreamTiming()中取出DownstreamTiming再获取lastDownstreamHeaderRxByteReceived()时间点若该时间点尚未被记录则返回nullopt。该时间点由 Envoy 在网络接收路径上调用DownstreamTiming::onLastDownstreamHeaderRxByteReceived记录在 substitution_formatter_test.cc 的测试中通过stream_info.downstream_timing_.onLastDownstreamHeaderRxByteReceived(time_system)触发。可以推断当请求头尚未接收完毕例如连接在头部传输中途被断开时该时间点缺失%COMMON_DURATION%将无法计算出有效耗时。3. 缺失时间点的渲染行为当START或END任一时间点不可用时getDurationCount返回nulloptformat返回空格式化器不会渲染出数值字符串模式下通常呈现为-在 typed JSON 模式下则渲染为 JSONnull。这一行为在 substitution_formatter_test.cc 中得到了完整覆盖在没有任何时间点被设置的情况下除DS_RX_BEG到DS_RX_BEG这种起点等于终点的组合输出0外其余组合均输出空值/null。六、访问日志配置实战%COMMON_DURATION%既可用于传统格式字符串format也可用于结构化 JSON 格式json_format/typed_json_format见 usage.rst。1. 格式字符串format string示例在访问日志配置中将DS_RX_BEG:DS_RX_HDR_END的耗时与默认格式结合输出access_log: - name: envoy.access_loggers.file typed_config: type: type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog path: /dev/stdout format: [%START_TIME%] \%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\ %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% header_rx_ms%COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:ms)%每条日志末尾的header_rx_ms字段即为请求开始到请求头完全接收的毫秒耗时。2. 结构化 JSON 示例使用typed_json_format可以将耗时渲染为 JSON 数字便于日志采集与告警系统直接解析access_log: - name: envoy.access_loggers.file typed_config: type: type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog path: /dev/stdout typed_json_format: start_time: %START_TIME% request_header_rx_ms: %COMMON_DURATION(DS_RX_BEG:DS_RX_HDR_END:ms)% request_body_rx_ms: %COMMON_DURATION(DS_RX_HDR_END:DS_RX_END:ms)% total_request_rx_ms: %COMMON_DURATION(DS_RX_BEG:DS_RX_END:ms)%输出示例request_header_rx_ms与request_body_rx_ms为数字类型{start_time: 2026-09-12T00:38:54.000Z, request_header_rx_ms: 3, request_body_rx_ms: 2, total_request_rx_ms: 5}注意typed_json_format下操作符必须是字典值中的唯一字符串才会输出类型化数值例如%DURATION%输出数字而%DURATION%.0输出字符串参见 usage.rst。七、边界行为与注意事项大小写敏感DS_RX_HDR_END必须全大写写成小写或混写会被当作自定义时间点名称处理从而取不到值。TCP 场景限制TCP 连接日志仅支持连接级别时间点DS_RX_HDR_END属于 HTTP 请求级别时间点仅适用于 HTTP/THRIFT 访问日志。时间点缺失请求头尚未接收完毕时DS_RX_HDR_END时间点不存在耗时字段将渲染为-或 JSONnull而非0。END 早于 START从当前实现看当END时间点早于START时间点时getDurationCount返回空值而不输出耗时见 stream_info_formatter.cc官方文档同时提示在启用 H/2、H/3 独立半关闭half-close行为时可能出现*_TX_END早于*_RX_END的场景需避免将这类端点作为起止组合。连接复用语义US_CX_*、US_HS_END等上游连接建立时间点在同一连接上的所有请求中重复出现DS_CX_END仅对连接关闭时仍活跃的请求填充其余请求渲染为-。八、测试验证新增时间点并非孤例实现在 substitution_formatter_test.cc 中DS_RX_HDR_END与其余 14 个时间点一起被纳入组合测试矩阵所有时间点、三种精度ms/us/ns两两组合验证时间点未设置时的空值输出为 15 个时间点逐一设置单调时钟时间戳如DS_RX_HDR_END被设为 2ms 处随后验证COMMON_DURATION两两组合的差值计算正确。该测试同时覆盖了非法参数如 4 段子命令、非法精度zs的报错路径保证了格式化器在错误配置下的行为可预期。九、小结DS_RX_HDR_END时间点的加入让 Envoy 访问日志具备了请求头接收完成这一关键里程碑的观测能力。配合%COMMON_DURATION(START:END:PRECISION)%的任意起止组合你可以将下游请求接收阶段细分为请求头接收与请求体接收两段独立耗时从而更精准地定位慢请求是出在头部传输、头部处理还是请求体阶段。配置时只需记住时间点大小写敏感、精度默认毫秒、时间点缺失时输出空值即可安全地在生产访问日志中启用这一新指标。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考