使用阿里云 SLS 实现可观测（推荐）

This content is not available in your language yet.

简介

HiMarket 集成了阿里云 SLS（日志服务）提供可观测能力，支持基于访问日志的指标聚合、图表展示和日志检索。本手册将指导您完成 SLS 可观测功能的配置。

以下情况适合使用 SLS 方案：

使用阿里云商业化 AI 网关（阿里云 AI 网关或者飞天企业版），开启 SLS 投递即可（开箱即用）
使用开源 Higress，通过配置 ai-statistics 插件和日志采集，投递到阿里云 SLS

如果您不使用阿里云环境，可以选择使用数据库实现可观测方案。

功能概览

可观测大盘：模型调用统计、MCP 工具调用统计、请求成功率、响应时间等
日志查询：支持自定义 SQL 查询访问日志
认证方式：支持 STS（默认）和 AK/SK 两种认证方式
自动降级：SLS 未配置时自动返回空数据，不影响系统正常运行

配置步骤

使用开源 Higress，需要进行如下配置
使用阿里云商业化 AI 网关（阿里云/飞天企业版），则无需进行以下配置，只需要开启日志投递即可。

步骤 1：准备 SLS 资源

在开始配置前，您需要在阿里云 SLS 控制台准备以下资源：

1.1 创建 Project 和 Logstore

登录阿里云 SLS 控制台
创建 Project（例如：apigateway-csb-cop）
在 Project 下创建 Logstore（例如：apig-access-log）

1.2 配置日志采集

将网关访问日志采集到上述 logstore。建议使用 higress 2.1.9 及以上版本，accesslogformat 已优化，适配了 HiMarket 可观测大盘。

日志格式包含以下关键字段：

基础字段：

__time__: 时间戳
response_code: 响应状态码
duration: 请求耗时
method: 请求方法
consumer: 调用者标识
route_name: 路由名称
upstream_cluster: 上游服务

AI 相关字段（JSON 格式的 ai_log 字段）：

model: 模型名称
api: API 名称
input_token: 输入 Token 数
output_token: 输出 Token 数
response_type: 响应类型（stream/normal）
llm_service_duration: LLM 服务耗时
cache_status: 缓存状态（hit/miss/skip）
token_ratelimit_status: 限流状态
mcp_tool_name: MCP 工具名称

1.3 配置索引

HiMarket 提供了自动索引更新接口，启动后会自动配置索引（AK/SK 需要具备创建索引权限）

文本字段：method、consumer、route_name、upstream_cluster 等
数值字段：duration、bytes_received、bytes_sent、response_code 等
JSON 字段：ai_log（开启 JSON 索引，包含上述 AI 相关字段）

1.4 获取认证凭证

准备 AK/SK 认证凭证：

AK/SK（推荐用于开发测试环境）

登录阿里云控制台
进入 AccessKey 管理页面
创建或获取 AccessKey ID 和 AccessKey Secret
确保该 AccessKey 具有 SLS 读取权限

步骤 2：配置 HiMarket

HiMarket 的 SLS 配置全部通过环境变量注入，无需修改配置文件。application.yml 中已预置了环境变量占位符和默认值：

环境变量	说明	默认值
`SLS_ENDPOINT`	SLS 服务端点（必填），格式：`<region>.log.aliyuncs.com`	空（未配置时自动降级返回空数据）
`SLS_AUTH_TYPE`	认证方式	`STS`
`SLS_ACCESS_KEY_ID`	AccessKey ID（`AK_SK` 模式必填）	空
`SLS_ACCESS_KEY_SECRET`	AccessKey Secret（`AK_SK` 模式必填）	空
`SLS_DEFAULT_PROJECT`	SLS Project 名称	`apigateway-csb-cop`
`SLS_DEFAULT_LOGSTORE`	SLS Logstore 名称	`apig-access-log`
`OBSERVABILITY_LOG_SOURCE`	日志数据源类型	`SLS`

SLS_AUTH_TYPE 支持两种值：STS（适用于阿里云 ECS/ACK 等有实例角色的环境）和 AK_SK（适用于开发测试或非阿里云环境）。

根据部署方式选择对应的配置方法：

本地开发 / 裸机部署

export SLS_ENDPOINT="cn-hangzhou.log.aliyuncs.com"
export SLS_AUTH_TYPE="AK_SK"
export SLS_ACCESS_KEY_ID="your-access-key-id"
export SLS_ACCESS_KEY_SECRET="your-access-key-secret"
# 以下两项如果与默认值一致可省略
export SLS_DEFAULT_PROJECT="apigateway-csb-cop"
export SLS_DEFAULT_LOGSTORE="apig-access-log"

Docker Compose 部署

在 docker-compose.yml 的 environment 中添加：

services:
  himarket-server:
    environment:
      - SLS_ENDPOINT=cn-hangzhou.log.aliyuncs.com
      - SLS_AUTH_TYPE=AK_SK
      - SLS_ACCESS_KEY_ID=your-access-key-id
      - SLS_ACCESS_KEY_SECRET=your-access-key-secret

Kubernetes / Helm 部署

通过 Secret 或 ConfigMap 注入上述环境变量。推荐将 AK/SK 存入 Secret：

apiVersion: v1
kind: Secret
metadata:
  name: himarket-sls-secret
type: Opaque
stringData:
  SLS_ACCESS_KEY_ID: "your-access-key-id"
  SLS_ACCESS_KEY_SECRET: "your-access-key-secret"
---
# 在 Deployment 中引用
env:
  - name: SLS_ENDPOINT
    value: "cn-hangzhou.log.aliyuncs.com"
  - name: SLS_AUTH_TYPE
    value: "AK_SK"
  - name: SLS_ACCESS_KEY_ID
    valueFrom:
      secretKeyRef:
        name: himarket-sls-secret
        key: SLS_ACCESS_KEY_ID
  - name: SLS_ACCESS_KEY_SECRET
    valueFrom:
      secretKeyRef:
        name: himarket-sls-secret
        key: SLS_ACCESS_KEY_SECRET

步骤 3：启动并验证

启动 HiMarket 后查看日志，确认 SLS 配置加载成功：

# 开发环境
mvn clean install -pl himarket-bootstrap -am
cd himarket-bootstrap && mvn spring-boot:run

# 生产环境
java -jar himarket-bootstrap/target/himarket-bootstrap.jar

启动成功时日志输出：

INFO  c.a.h.config.ObservabilityConfig - Observability log source: SLS
INFO  c.a.h.config.ObservabilityConfig - SLS endpoint: cn-hangzhou.log.aliyuncs.com, project: apigateway-csb-cop, logstore: apig-access-log, authType: AK_SK

如果 SLS_ENDPOINT 未配置，会输出以下警告（不影响系统运行，可观测接口会返回空数据）：

WARN  c.a.h.config.ObservabilityConfig - SLS endpoint is not configured! Queries will return empty results.

Higress 插件配置

Model 大盘

ai-statistics 插件配置示例：

  - config:
      attributes:
      - apply_to_log: true
        default_value: unknown
        key: consumer
        value: x-mse-consumer
        value_source: request_header
      - apply_to_log: true
        key: fallback_from
        value: x-higress-fallback-from
        value_source: request_header
      - apply_to_log: true
        apply_to_span: true
        as_separate_log_field: true
        key: question
        trace_span_key: gen_ai.input.messages
        value: messages.@reverse.0.content
        value_source: request_body
      - apply_to_log: true
        apply_to_span: true
        as_separate_log_field: true
        key: answer
        rule: append
        trace_span_key: gen_ai.input.messages
        value: choices.0.delta.content
        value_source: response_streaming_body
      - apply_to_log: true
        apply_to_span: true
        as_separate_log_field: true
        key: answer
        trace_span_key: gen_ai.input.messages
        value: choices.0.message.content
        value_source: response_body
    configDisable: false
    ingress:
    - ai-route-higress-qwen-max.internal

MCP 大盘

ai-statistics 插件配置示例

  - config:
      attributes:
      - apply_to_log: true
        key: jsonrpc_version
        value: x-envoy-jsonrpc-version
        value_source: request_header
        trace_span_key: network.protocol.version
        apply_to_span: true
      - apply_to_log: true
        key: jsonrpc_id
        value: x-envoy-jsonrpc-id
        value_source: request_header
        trace_span_key: rpc.jsonrpc.request_id
        apply_to_span: true
      - apply_to_log: true
        key: jsonrpc_method
        value: x-envoy-jsonrpc-method
        value_source: request_header
        trace_span_key: mcp.method.name
        apply_to_span: true
      - apply_to_log: true
        key: jsonrpc_params
        value: x-envoy-jsonrpc-params
        value_source: request_header
        trace_span_key: mcp.arguments
        apply_to_span: true
      - apply_to_log: true
        key: jsonrpc_result
        value: x-envoy-jsonrpc-result
        value_source: response_header
      - apply_to_log: true
        apply_to_span: true
        attribute_key: tool.name
        key: mcp_tool_name
        value: x-envoy-mcp-tool-name
        value_source: request_header
        trace_span_key: mcp.tool.name
        apply_to_span: true
      - apply_to_log: true
        apply_to_span: true
        attribute_key: tool.parameters
        key: mcp_tool_arguments
        value: x-envoy-mcp-tool-arguments
        value_source: request_header
      - apply_to_log: true
        key: mcp_tool_response
        value: x-envoy-mcp-tool-response
        value_source: response_header
      - apply_to_log: true
        key: mcp_tool_error
        value: x-envoy-mcp-tool-error
        value_source: response_header
    configDisable: false
    ingress:
    - mcp-server-travel.internal

pre-request 插件配置示例

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  annotations:
  name: pre-request.internal
  namespace: himarket-system
spec:
  imagePullPolicy: Always
  matchRules:
  - config:
      stage: request
    configDisable: false
    ingress:
    - mcp-server-travel.internal
  phase: AUTHN
  priority: 1000
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/jsonrpc-converter:1.0.0

pre-response 插件配置示例：

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  annotations:
  name: pre-response.internal
  namespace: himarket-system
spec:
  imagePullPolicy: Always
  matchRules:
  - config:
      stage: response
    configDisable: false
    ingress:
    - mcp-server-travel.internal
  phase: UNSPECIFIED_PHASE
  priority: 1000
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/jsonrpc-converter:1.0.0

插件优先级调整：

pre-request(json-converter):
  phase: AUTHN
  priority: 1000

key-auth:
  phase: AUTHN
  priority: 310

ai-statistics:
  phase: AUTHN
  priority: 100

pre-response(json-converter):
  phase: UNSPECIFIED_PHASE
  priority: 1000

mcp-server:
  phase: UNSPECIFIED_PHASE
  priority: 999

ai-security-guard:
  phase: UNSPECIFIED_PHASE
  priority: 850

预设场景说明

HiMarket 内置了丰富的预设查询场景，涵盖模型大盘、MCP 大盘等：

卡片类（CARD）

场景标识	说明	适用大盘
`pv`	总请求次数	模型、MCP
`uv`	独立调用者数量	模型、MCP
`fallback_count`	Fallback 请求数	模型
`bytes_received`	网关入流量（MB）	MCP
`bytes_sent`	网关出流量（MB）	MCP
`input_token_total`	输入 Token 总数	模型
`output_token_total`	输出 Token 总数	模型
`token_total`	Token 总数	模型

线图类（LINE）

场景标识	说明	适用大盘
`qps_stream`	流式 QPS	模型
`qps_normal`	非流式 QPS	模型
`qps_total`	总体 QPS	模型
`success_rate`	请求成功率	模型、MCP
`token_per_sec_input`	输入 Token/s	模型
`token_per_sec_output`	输出 Token/s	模型
`token_per_sec_total`	总 Token/s	模型
`rt_avg_total`	平均响应时间（整体）	模型
`rt_avg_stream`	平均响应时间（流式）	模型
`rt_avg_normal`	平均响应时间（非流式）	模型
`rt_first_token`	首包响应时间	模型
`cache_hit/miss/skip`	缓存命中/未命中/跳过	模型
`ratelimited_per_sec`	限流请求数/s	模型
`qps_by_status`	按状态码分组的 QPS	MCP
`qps_total_simple`	总 QPS	MCP
`rt_avg`	平均响应时间	MCP
`rt_p99/p95/p90/p50`	P99/P95/P90/P50 响应时间	MCP

表格类（TABLE）

场景标识	说明	适用大盘
`model_token_table`	模型 Token 使用统计	模型
`consumer_token_table`	消费者 Token 使用统计	模型
`service_token_table`	服务 Token 使用统计	模型
`error_requests_table`	错误请求统计	模型
`ratelimited_consumer_table`	限流消费者统计	模型
`risk_label_table`	风险类型统计	模型
`risk_consumer_table`	风险消费者统计	模型
`method_distribution`	Method 分布	MCP
`gateway_status_distribution`	网关状态码分布	MCP
`backend_status_distribution`	后端状态码分布	MCP
`request_distribution`	请求分布	MCP

筛选选项类（TABLE）

场景标识	说明
`filter_service_options`	实例列表
`filter_api_options`	API 列表
`filter_model_options`	模型列表
`filter_route_options`	路由列表
`filter_consumer_options`	消费者列表
`filter_upstream_options`	上游服务列表
`filter_mcp_tool_options`	MCP 工具名称列表
`filter_mcp_server_options`	MCP Server 列表

故障排查

问题 1：接口返回空数据

原因分析：

SLS 未配置（endpoint 为空）
Project 或 Logstore 不存在
时间范围内无日志数据
认证信息错误

解决方法：

检查配置文件或环境变量是否正确设置
查看应用日志，确认 SLS 配置加载状态
登录 SLS 控制台确认 Project 和 Logstore 存在
使用 SLS 控制台查询验证数据是否存在
验证 AccessKey 权限是否包含 SLS 读取权限

问题 2：查询超时

原因分析：

时间范围过大
日志量过大
索引未配置或配置不当

解决方法：

缩小查询时间范围
在 SLS 控制台为 Logstore 配置索引
使用预设场景而非复杂自定义查询
增加 interval 参数减少数据点数量

问题 3：查询结果与预期不符

原因分析：

日志字段映射不匹配
索引配置不正确
SQL 语法错误

解决方法：

确认日志字段名称与预设 SQL 一致
检查 JSON 字段（如 ai_log）是否开启 JSON 索引
查看应用日志获取实际执行的 SQL
在 SLS 控制台手动执行 SQL 验证

问题 4：认证失败

错误日志：

ERROR c.a.h.s.g.f.SlsClientFactory - Failed to create SLS client
LogException: AccessKeyId is required

解决方法：

确认环境变量已正确设置
确认 auth-type 为 AK_SK
确认 AccessKey ID 和 Secret 无误
确认 AccessKey 未被禁用或过期

最佳实践

1. 安全性

不要将 AccessKey 直接写入配置文件
使用环境变量或 Kubernetes Secret 管理敏感信息
定期轮换 AccessKey
遵循最小权限原则，仅授予 SLS 读取权限

2. 性能优化

合理设置查询时间范围，避免一次查询超过 7 天
配置索引提升查询性能
使用预设场景而非复杂自定义查询
增大 interval 减少时序图数据点

3. 成本控制

按需配置 Logstore 存储周期
合理设置日志采集规则，避免采集无用日志
使用 SLS 的数据生命周期管理功能

4. 监控告警

在 SLS 控制台配置查询异常告警
监控 HiMarket 应用日志中的 SLS 相关错误
定期检查 SLS 使用量和费用

附录

A. SLS 区域 Endpoint 列表

区域	Endpoint
华东1（杭州）	cn-hangzhou.log.aliyuncs.com
华东2（上海）	cn-shanghai.log.aliyuncs.com
华北1（青岛）	cn-qingdao.log.aliyuncs.com
华北2（北京）	cn-beijing.log.aliyuncs.com
华北3（张家口）	cn-zhangjiakou.log.aliyuncs.com
华南1（深圳）	cn-shenzhen.log.aliyuncs.com
西南1（成都）	cn-chengdu.log.aliyuncs.com

更多区域请参考：https://help.aliyun.com/document_detail/29008.html

使用阿里云 SLS 实现可观测（推荐）

简介

功能概览

配置步骤

步骤 1：准备 SLS 资源

1.1 创建 Project 和 Logstore

1.2 配置日志采集

1.3 配置索引

1.4 获取认证凭证

步骤 2：配置 HiMarket

本地开发 / 裸机部署

Docker Compose 部署

Kubernetes / Helm 部署

步骤 3：启动并验证

Higress 插件配置

Model 大盘

MCP 大盘

预设场景说明

卡片类（CARD）

线图类（LINE）

表格类（TABLE）

筛选选项类（TABLE）

故障排查

问题 1：接口返回空数据

问题 2：查询超时

问题 3：查询结果与预期不符

问题 4：认证失败

最佳实践

1. 安全性

2. 性能优化

3. 成本控制

4. 监控告警

附录

A. SLS 区域 Endpoint 列表

相关链接