Higress AI可观测_ai-statistics插件扩展设计

[miniceM]

设计背景

Higress作为AI大模型的请求入口，可以通过在网关上扩展插件能力，对所有通过 AI网关的请求信息完成指标和链路观测等一系列的监控行为，完善Higress的可观测体系。

当前Higress 通过ai-statistics插件，提供AI可观测基础能力。扩展ai-statistics插件后，可以同各种链路可观测组件进行集成，完成 AI 请求都链路监控和追踪。

内容摘要

在 Higress 网关上开启插件ai-statistics，扩展插件将token 开销、延时（包括首字节响应、完整响应时间）、用户请求问题等指标信息通过 span tag 进行采集，将采集到的指标推送至Higress tracing配置的tracing 观测服务，实现对 AI请求的链路追踪，方便问题的查找和分析。

实现思路

设计要点如下：

1. 用户请求进入ai-statistics插件后，可根据插件配置判断是否获取用户本次 http 请求数据中的问题原始数据，进行记录；

2. 用户应答经ai-proxy插件流回ai-statistics插件后，通过 http 请求头中的自定义头数据req-arrive-time以及req-cost-time等计算出延时（包括首字节响应、完整响应时间）数据，同时从应答内容中获取 token 使用情况；

3. 将获取到的 tracing 数据通过调用proxywasm.SetProperty([]string{"trace_span_tag.指标名"}, []byte(指标数据)) 方法增加统计插件的 tracing span tag ；

4. 通过配置文件用户自定义 tracing label的方式，支持用户自定义扩展监控链路数据，如用户关注AI 请求链路中的会话 id 信息，可通过配置文件定义设置session_id为额外tracing tag 。

   配置规则定义如下：

   • 每项自定义配置包含 3 个要素：key（tracing tag 名称），value_source（tag 取值来源），value （tag 取值 key value/path）。
   • value_source为 tag 值的取值来源，可选配置值有 4 个：
     • property ： tag 值通过proxywasm.GetProperty()方法获取，value配置GetProperty()方法要提取的key名
     • requeset_header ： tag 值通过http请求头获取，value配置为header key
     • request_body ：tag 值通过请求body获取，value配置格式为 gjson的 GJSON PATH 语法
     • response_header ： tag 值通过http响应头获取，value配置为header key

​ 举例如下：

tracing_label:
   - key: "session_id"
     value_source: "requeset_header"
     value: "session_id"
   - key: "user_content"
     value_source: "request_body"
     value: "input.messages.1.content"

Tracing 集成

完成指标的采集和暴漏之后，可通过tracing 服务进行链路监测，tracing可以对接skywalking、zipkin、OTel等多种方案，下面以对接Skywalking为例。

在Higress 的全局配置 ConfigMap 对象 higress-config 增加 higress 项，激活 Higress 集成 Skywalking 调用链路跟踪添加 skywalking 相关配置如下：

apiVersion: v1
data:
  higress: |-
    tracing:
      enable: true
      sampling: 100
      timeout: 500
      skywalking:
       service: skywalking-oap-server.op-system.svc.cluster.local
       port: 11800

Tracing 配置说明

字段	类型	说明	配置值
enable	boolean	是否开启 tracing 功能	true
sampling	float	采样率，0.0 - 100.0 之间	100.0
timeout	int	链路跟踪中间件 grpc 连接超时，单位毫秒	500
skywalking		skywalking 配置

skywalking 配置

字段	类型	说明	配置示例
service	string	Skywalking grpc 服务地址	skywalking-oap-server.op-system.svc.cluster.local
port	string	Skywalking grpc 服务端口	11800

[johnlanni]

几个问题和建议：

1. 支持 tracing 不需要增加metrics上报
2. 增加 tracing span tag 需要通过 setProperty，参考：

   higress/plugins/wasm-go/extensions/ai-rag/main.go

   Line 150 in 4307f88

   proxywasm.SetProperty([]string{"trace_span_tag.rag_docs"}, []byte(traceStr))

3. ai statistics 里增加 tracing span tag 的能力，跟用什么tracing方案无关，不管skywalking、zipkin、OTel都可以支持的
4. ai statistics 里增加的 tracing span tag 能力，需要考虑用户的自定义扩展能力，例如用户可以选择将 LLM 请求的问题加入到 span tag 里

[miniceM]

几个问题和建议：

1. 支持 tracing 不需要增加metrics上报
2. 增加 tracing span tag 需要通过 setProperty，参考：

   higress/plugins/wasm-go/extensions/ai-rag/main.go

   Line 150 in 4307f88

   proxywasm.SetProperty([]string{"trace_span_tag.rag_docs"}, []byte(traceStr))

3. ai statistics 里增加 tracing span tag 的能力，跟用什么tracing方案无关，不管skywalking、zipkin、OTel都可以支持的
4. ai statistics 里增加的 tracing span tag 能力，需要考虑用户的自定义扩展能力，例如用户可以选择将 LLM 请求的问题加入到 span tag 里

好的，我修改一下

[miniceM]

已按照建议修改 @johnlanni

[johnlanni]

span tag 的配置字段应该有key，value以及value_source，支持用户自己配。value来源可以设计成三类，通过value_source字段指定：

1. property：通过proxywasm.GetProperty获取，value配置成提取的key
2. requeset_header: 从请求头获取，value配置成header名
3. response_header: 从响应头获取，value配置成header名
4. request_body: 从请求body获取，value配置成gjson的 GJSON PATH 语法提取字段（参考transformer插件）

response body可以不用支持，因为这个插件是流式处理的