Envoy AI Protocol Manager 新增请求路径统计让解码链路Decode Path的每个结果可观测【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本文基于 Envoy 仓库当前版本的变更记录changelogs/current/new_features/ai_protocol_manager__request-path-stats.rst展开介绍 AI Protocol Manager 过滤器HTTP filter新引入的一批请求路径统计指标。此前该过滤器的计数器只覆盖响应路径token usage 提取等如今request_parsed、request_parse_error、request_schema_invalid、request_passthrough、request_external_buffer_error、response_external_buffer_error六个计数器让解码路径的处置结果完全可见尤其是把畸形载荷与能解析但违反 API 载荷 schema这两类都返回 400 的场景区分开来——它们对运维来说意味着完全不同的处置动作。读完本文你将理解这六个计数器的语义、触发时机与源码实现位置并能据此搭建 AI 网关的监控与告警维度。AI Protocol Manager 的请求/响应双路径背景AI Protocol Manager 过滤器alpha在流的两个方向同时管理 AI API 流量见 docs/root/configuration/http/http_filters/ai_protocol_manager_filter.rst请求decode路径将已声明 AI endpoint 的载荷从连接管理器的热路径上卸荷offload到外部缓冲边到达边解析从而让路由与准入决策基于完整收到的 body 做出响应encode路径从各提供商的响应中提取归一化的 LLM token usageOpenAI Chat Completions / Responses、Anthropic Messages、Gemini generateContent 等以类型化动态元数据发布供下游消费。在本次变更之前响应路径已有response_parse_error、response_body_too_large、sse_*、token_usage_*等一批计数器而请求路径上的处理结果在统计上几乎是黑盒请求是否被成功解析、是否因格式错误被拒绝、是否走 passthrough都没有对应指标。本次新增的计数器补上了这一缺口。六个新增计数器定义、触发时机与源码依据所有统计都位于ai_protocol_manager.命名空间下。六个新增计数器在 source/extensions/filters/http/ai_protocol_manager/stats.h 中统一声明通过ALL_AI_PROTOCOL_MANAGER_STATS(COUNTER)宏生成AiProtocolManagerStats结构体。计数器类型语义触发位置request_parsedCounter被持有的请求载荷成功解析为文档且在声明了 schema 的 API 上通过了载荷 schema 校验filter.cc#L307request_parse_errorCounter已声明 AI endpoint 的载荷不是格式良好的 JSON以 400 拒绝filter.cc#L277request_schema_invalidCounter已声明 AI endpoint 的载荷能解析但违反其 API 的载荷 schema以 400 拒绝filter.cc#L301request_passthroughCounter未配置路由上的载荷在parse_unconfigured_routes下解析失败原样转发绝不构成请求失败filter.cc#L283request_external_buffer_errorCounter外部缓冲在请求路径上发生不可恢复失败以 500 应答流filter_chain_bridge.cc#L24-L28response_external_buffer_errorCounter外部缓冲在响应路径上发生不可恢复失败以 500 应答流filter_chain_bridge.cc#L44-L54解析与校验的触发点filter.cc 的 feedParser 流程请求载荷的解析发生在 filter.cc#L256-L310 的feedParser()中整个判定逻辑清晰体现了三个计数器的分工解析失败request_parser_-feed(...)返回非 OK 状态时若当前路由是声明过的 AI endpointisAiEndpoint()则request_parse_error_.inc()并调用rejectInvalidPayload()filter.cc#L312-L318通过sendLocalReply(Http::Code::BadRequest, ...)返回 400细节字符串为ai_protocol_manager_invalid_jsonpassthrough若解析失败但路由未声明仅parse_unconfigured_routes开启时才会走到解析则request_passthrough_.inc()payload 原样转发——这印证了文档中绝不因解析失败拒绝未配置路由的请求的设计schema 校验失败仅在end_stream且是已声明 AI endpoint 时用AdapterRegistry::get(route_request_protocol_).schema()取到载荷 schema当前为OPENAI_CHAT_COMPLETIONS调用payload_schema-validateRequest(request_json_)校验不通过则request_schema_invalid_.inc()并以 400 拒绝ai_protocol_manager_invalid_json成功只有走到这里才request_parsed_.inc()。从源码结构看解析是增量incremental进行的与 offload 共享同一字节流因此非法载荷会在出错字节到达时立即失败而不是等整个上传完成后再判定这也意味着request_parse_error反映的是流式解析过程中即被拒绝的场景。两个 400 的含义差异为什么值得分开统计这是本次变更的核心价值所在request_parse_error与request_schema_invalid最终都以 400 拒绝请求但对运营人员意味着不同的问题request_parse_error增长 → 客户端发送的根本不是合法 JSON可能是 Content-Type 谎报、body 被截断、非 JSON 请求打到了 AI endpoint——通常是客户端侧的错误或上游代理对 body 的破坏request_schema_invalid增长 → 载荷是合法 JSON但不符合该 wire API 的 schema缺必填字段、字段类型错误、枚举值非法、metadata 字段未保持在 inline 阈值内等——通常是 API 契约演进导致的客户端与服务端不同步或模型调用参数被错误拼装。区分这两者后告警与排查路径完全不同前者优先查网络/内容层后者优先查客户端 SDK 版本与 API 参数构造。schema 校验覆盖必填字段、数据类型、枚举值与 offload 规则确保model、role等 metadata 字段留在 DOM 内同时允许大段消息内容驻留外部缓冲。外部缓冲不可恢复错误两个方向的 500request_external_buffer_error与response_external_buffer_error都对应 500实现在 filter_chain_bridge.cc 的onUnrecoverableError()中解码方向filter_chain_bridge.cc#L24-L28DecoderFilterChainBridge::onUnrecoverableError()计数并sendLocalReply(Http::Code::InternalServerError, AI protocol buffer error, ..., ai_protocol_manager_external_buffer_error)编码方向filter_chain_bridge.cc#L44-L54EncoderFilterChainBridge::onUnrecoverableError()在响应头可能部分 body已在途的情况下尽力调用sendLocalReply——若响应尚未开始则生成本地回复否则直接发送回复给下游 codec 或重置流避免发出被截断的载荷。这里的外部缓冲指 filter 将请求 body 从连接管理器内存缓冲卸荷到的独立存储BufferManagerExternalBufferImpl。值得注意的是响应方向计数器的语义响应路径本来就是 observe-only正常情况下绝不应失败因此response_external_buffer_error一旦出现往往指示存储后端如磁盘或自定义 external buffer 实现的真实故障是比request_external_buffer_error更值得立即关注的健康信号。配置方式让请求路径统计真正生效需要澄清的是本次 changelog 只新增统计指标不引入新的配置项。让这些统计产生数据的开关早已存在于过滤器配置中。相关配置示例见 docs/root/configuration/http/http_filters/ai_protocol_manager_filter.rst。路由级声明 AI endpoint严格解析 schema 校验routes: - match: path: /chat/completions route: cluster: openai typed_per_filter_config: envoy.filters.http.ai_protocol_manager: type: type.googleapis.com/envoy.extensions.filters.http.ai_protocol_manager.v3.AiProtocolManagerPerRoute request: api_protocol: OPENAI_CHAT_COMPLETIONS此时该路由的请求会被严格解析畸形 JSON 触发request_parse_error400解析成功但违反 schema 触发request_schema_invalid400两者都成功才计入request_parsed。过滤器级解析未配置路由宽松模式http_filters: - name: envoy.filters.http.ai_protocol_manager typed_config: type: type.googleapis.com/envoy.extensions.filters.http.ai_protocol_manager.v3.AiProtocolManager request_handling: parse_unconfigured_routes: true设置parse_unconfigured_routes后未声明为 AI endpoint 的路由也会被卸荷与解析但解析失败只会触发request_passthrough原样转发绝不返回 4xx/5xx。运维上可据此区分严格拒绝的 AI endpoint 流量与宽松放行的普通路由流量。一个实用的观测技巧把request_passthrough的速率变化当作宽松路由上开始出现非 JSON body的信号——它不破坏业务但可能意味着某条路由的客户端行为发生了变化。监控与告警建议基于上述语义可针对性地组织告警400 的归因分流request_parse_error与request_schema_invalid分别告警不要笼统地按 HTTP 400 状态码聚合两者的 SLA 责任方不同内容传输层 vs 客户端契约层500 的紧急度分级response_external_buffer_error是响应路径observe-only上不该出现的异常一旦增长优先排查存储后端与内存账户memory account配置request_external_buffer_error则影响请求处理本身同样需要即时关注正常度基线以request_parsed作为 AI endpoint 请求处理成功的基准量用它归一化其他计数器观察拒绝率的变化趋势而不是只看绝对值。小结本次变更把 AI Protocol Manager 的统计面从只覆盖响应路径扩展到了完整的请求生命周期解析成功request_parsed、JSON 格式错误request_parse_error、schema 违规request_schema_invalid、宽松路由透传request_passthrough以及双向的外部缓冲致命错误request/response_external_buffer_error。尤其关键的是它把两种都会产生 400 的失败路径拆成独立计数器让 AI 网关的运维能从统计上直接回答这个 400 是内容坏了还是客户端不懂契约——这正是 AI 网关可观测性最实用的增量之一。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Envoy AI Protocol Manager 新增请求路径统计：让解码链路（Decode Path）的每个结果可观测
Envoy AI Protocol Manager 新增请求路径统计让解码链路Decode Path的每个结果可观测【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本文基于 Envoy 仓库当前版本的变更记录changelogs/current/new_features/ai_protocol_manager__request-path-stats.rst展开介绍 AI Protocol Manager 过滤器HTTP filter新引入的一批请求路径统计指标。此前该过滤器的计数器只覆盖响应路径token usage 提取等如今request_parsed、request_parse_error、request_schema_invalid、request_passthrough、request_external_buffer_error、response_external_buffer_error六个计数器让解码路径的处置结果完全可见尤其是把畸形载荷与能解析但违反 API 载荷 schema这两类都返回 400 的场景区分开来——它们对运维来说意味着完全不同的处置动作。读完本文你将理解这六个计数器的语义、触发时机与源码实现位置并能据此搭建 AI 网关的监控与告警维度。AI Protocol Manager 的请求/响应双路径背景AI Protocol Manager 过滤器alpha在流的两个方向同时管理 AI API 流量见 docs/root/configuration/http/http_filters/ai_protocol_manager_filter.rst请求decode路径将已声明 AI endpoint 的载荷从连接管理器的热路径上卸荷offload到外部缓冲边到达边解析从而让路由与准入决策基于完整收到的 body 做出响应encode路径从各提供商的响应中提取归一化的 LLM token usageOpenAI Chat Completions / Responses、Anthropic Messages、Gemini generateContent 等以类型化动态元数据发布供下游消费。在本次变更之前响应路径已有response_parse_error、response_body_too_large、sse_*、token_usage_*等一批计数器而请求路径上的处理结果在统计上几乎是黑盒请求是否被成功解析、是否因格式错误被拒绝、是否走 passthrough都没有对应指标。本次新增的计数器补上了这一缺口。六个新增计数器定义、触发时机与源码依据所有统计都位于ai_protocol_manager.命名空间下。六个新增计数器在 source/extensions/filters/http/ai_protocol_manager/stats.h 中统一声明通过ALL_AI_PROTOCOL_MANAGER_STATS(COUNTER)宏生成AiProtocolManagerStats结构体。计数器类型语义触发位置request_parsedCounter被持有的请求载荷成功解析为文档且在声明了 schema 的 API 上通过了载荷 schema 校验filter.cc#L307request_parse_errorCounter已声明 AI endpoint 的载荷不是格式良好的 JSON以 400 拒绝filter.cc#L277request_schema_invalidCounter已声明 AI endpoint 的载荷能解析但违反其 API 的载荷 schema以 400 拒绝filter.cc#L301request_passthroughCounter未配置路由上的载荷在parse_unconfigured_routes下解析失败原样转发绝不构成请求失败filter.cc#L283request_external_buffer_errorCounter外部缓冲在请求路径上发生不可恢复失败以 500 应答流filter_chain_bridge.cc#L24-L28response_external_buffer_errorCounter外部缓冲在响应路径上发生不可恢复失败以 500 应答流filter_chain_bridge.cc#L44-L54解析与校验的触发点filter.cc 的 feedParser 流程请求载荷的解析发生在 filter.cc#L256-L310 的feedParser()中整个判定逻辑清晰体现了三个计数器的分工解析失败request_parser_-feed(...)返回非 OK 状态时若当前路由是声明过的 AI endpointisAiEndpoint()则request_parse_error_.inc()并调用rejectInvalidPayload()filter.cc#L312-L318通过sendLocalReply(Http::Code::BadRequest, ...)返回 400细节字符串为ai_protocol_manager_invalid_jsonpassthrough若解析失败但路由未声明仅parse_unconfigured_routes开启时才会走到解析则request_passthrough_.inc()payload 原样转发——这印证了文档中绝不因解析失败拒绝未配置路由的请求的设计schema 校验失败仅在end_stream且是已声明 AI endpoint 时用AdapterRegistry::get(route_request_protocol_).schema()取到载荷 schema当前为OPENAI_CHAT_COMPLETIONS调用payload_schema-validateRequest(request_json_)校验不通过则request_schema_invalid_.inc()并以 400 拒绝ai_protocol_manager_invalid_json成功只有走到这里才request_parsed_.inc()。从源码结构看解析是增量incremental进行的与 offload 共享同一字节流因此非法载荷会在出错字节到达时立即失败而不是等整个上传完成后再判定这也意味着request_parse_error反映的是流式解析过程中即被拒绝的场景。两个 400 的含义差异为什么值得分开统计这是本次变更的核心价值所在request_parse_error与request_schema_invalid最终都以 400 拒绝请求但对运营人员意味着不同的问题request_parse_error增长 → 客户端发送的根本不是合法 JSON可能是 Content-Type 谎报、body 被截断、非 JSON 请求打到了 AI endpoint——通常是客户端侧的错误或上游代理对 body 的破坏request_schema_invalid增长 → 载荷是合法 JSON但不符合该 wire API 的 schema缺必填字段、字段类型错误、枚举值非法、metadata 字段未保持在 inline 阈值内等——通常是 API 契约演进导致的客户端与服务端不同步或模型调用参数被错误拼装。区分这两者后告警与排查路径完全不同前者优先查网络/内容层后者优先查客户端 SDK 版本与 API 参数构造。schema 校验覆盖必填字段、数据类型、枚举值与 offload 规则确保model、role等 metadata 字段留在 DOM 内同时允许大段消息内容驻留外部缓冲。外部缓冲不可恢复错误两个方向的 500request_external_buffer_error与response_external_buffer_error都对应 500实现在 filter_chain_bridge.cc 的onUnrecoverableError()中解码方向filter_chain_bridge.cc#L24-L28DecoderFilterChainBridge::onUnrecoverableError()计数并sendLocalReply(Http::Code::InternalServerError, AI protocol buffer error, ..., ai_protocol_manager_external_buffer_error)编码方向filter_chain_bridge.cc#L44-L54EncoderFilterChainBridge::onUnrecoverableError()在响应头可能部分 body已在途的情况下尽力调用sendLocalReply——若响应尚未开始则生成本地回复否则直接发送回复给下游 codec 或重置流避免发出被截断的载荷。这里的外部缓冲指 filter 将请求 body 从连接管理器内存缓冲卸荷到的独立存储BufferManagerExternalBufferImpl。值得注意的是响应方向计数器的语义响应路径本来就是 observe-only正常情况下绝不应失败因此response_external_buffer_error一旦出现往往指示存储后端如磁盘或自定义 external buffer 实现的真实故障是比request_external_buffer_error更值得立即关注的健康信号。配置方式让请求路径统计真正生效需要澄清的是本次 changelog 只新增统计指标不引入新的配置项。让这些统计产生数据的开关早已存在于过滤器配置中。相关配置示例见 docs/root/configuration/http/http_filters/ai_protocol_manager_filter.rst。路由级声明 AI endpoint严格解析 schema 校验routes: - match: path: /chat/completions route: cluster: openai typed_per_filter_config: envoy.filters.http.ai_protocol_manager: type: type.googleapis.com/envoy.extensions.filters.http.ai_protocol_manager.v3.AiProtocolManagerPerRoute request: api_protocol: OPENAI_CHAT_COMPLETIONS此时该路由的请求会被严格解析畸形 JSON 触发request_parse_error400解析成功但违反 schema 触发request_schema_invalid400两者都成功才计入request_parsed。过滤器级解析未配置路由宽松模式http_filters: - name: envoy.filters.http.ai_protocol_manager typed_config: type: type.googleapis.com/envoy.extensions.filters.http.ai_protocol_manager.v3.AiProtocolManager request_handling: parse_unconfigured_routes: true设置parse_unconfigured_routes后未声明为 AI endpoint 的路由也会被卸荷与解析但解析失败只会触发request_passthrough原样转发绝不返回 4xx/5xx。运维上可据此区分严格拒绝的 AI endpoint 流量与宽松放行的普通路由流量。一个实用的观测技巧把request_passthrough的速率变化当作宽松路由上开始出现非 JSON body的信号——它不破坏业务但可能意味着某条路由的客户端行为发生了变化。监控与告警建议基于上述语义可针对性地组织告警400 的归因分流request_parse_error与request_schema_invalid分别告警不要笼统地按 HTTP 400 状态码聚合两者的 SLA 责任方不同内容传输层 vs 客户端契约层500 的紧急度分级response_external_buffer_error是响应路径observe-only上不该出现的异常一旦增长优先排查存储后端与内存账户memory account配置request_external_buffer_error则影响请求处理本身同样需要即时关注正常度基线以request_parsed作为 AI endpoint 请求处理成功的基准量用它归一化其他计数器观察拒绝率的变化趋势而不是只看绝对值。小结本次变更把 AI Protocol Manager 的统计面从只覆盖响应路径扩展到了完整的请求生命周期解析成功request_parsed、JSON 格式错误request_parse_error、schema 违规request_schema_invalid、宽松路由透传request_passthrough以及双向的外部缓冲致命错误request/response_external_buffer_error。尤其关键的是它把两种都会产生 400 的失败路径拆成独立计数器让 AI 网关的运维能从统计上直接回答这个 400 是内容坏了还是客户端不懂契约——这正是 AI 网关可观测性最实用的增量之一。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考