a6-plugin-prometheus

概览

prometheus 插件以 Prometheus 文本格式暴露 APISIX 指标，包括 HTTP 状态码、请求延迟、带宽、上游健康、etcd 状态、流会话、LLM Token 使用量和 AI 缓存命中。Prometheus 抓取该指标端点，Grafana 用于可视化。字段表请参阅 prometheus。

适用场景

监控每个路由、服务或消费者的请求速率、错误率和延迟。
跟踪上游健康检查状态。
观察系统整体性能和资源使用情况。
使用 Prometheus + Grafana 构建仪表板和告警。

插件配置参考（路由/服务/全局规则）

字段	类型	是否必填	默认值	说明
`prefer_name`	boolean	否	`false`	在指标标签中使用路由/服务名称而不是 ID

该插件的路由级配置很少，大多数选项在 APISIX config.yaml 中管理。

导出的指标

核心指标

指标	类型	描述
`apisix_http_status`	计数器	按路由、服务和消费者统计的 HTTP 状态码
`apisix_http_latency`	直方图	请求延迟（毫秒），类型包括 request、upstream 和 apisix
`apisix_bandwidth`	计数器	带宽（字节），类型包括 ingress 和 egress
`apisix_http_requests_total`	仪表	收到的 HTTP 请求总数
`apisix_nginx_http_current_connections`	仪表	按状态分列的当前连接
`apisix_upstream_status`	仪表	上游健康状态（1 表示健康，0 表示不健康）
`apisix_etcd_reachable`	仪表	etcd 可达性（1 表示可达，0 表示不可达）
`apisix_etcd_modify_indexes`	仪表	etcd 修改次数
`apisix_node_info`	仪表	APISIX 节点主机名和版本
`apisix_shared_dict_capacity_bytes`	仪表	共享内存容量
`apisix_shared_dict_free_space_bytes`	仪表	共享内存空闲空间
`apisix_stream_connection_total`	计数器	TCP/UDP 流连接总数
`apisix_stream_active_connections`	仪表	活跃的流连接（APISIX-Runtime，3.18.0+）
`apisix_stream_status`	计数器	按状态统计的已完成流会话（3.18.0+）
`apisix_stream_bandwidth`	计数器	按方向统计的流字节数（APISIX-Runtime，3.18.0+）

LLM/AI 指标（v3.15+）

指标	类型	描述
`apisix_llm_latency`	直方图	LLM 请求延迟。自 APISIX 3.18.0 起，`type` 标签为 `total`（完整响应）或 `ttft`（流式响应的首 Token 时间）。不带 `type` 的查询会同时匹配二者；使用 `type="total"` 保持此前总延迟语义。每个流式请求会记录一个 `total` 和一个 `ttft` 样本
`apisix_llm_prompt_tokens`	计数器	消耗的提示词 Token 数量
`apisix_llm_completion_tokens`	计数器	消耗的补全 Token 数量
`apisix_llm_active_connections`	仪表	活跃的 LLM 连接数
`apisix_llm_prompt_tokens_dist`	直方图	提示词 Token 分布（3.18.0+）
`apisix_llm_completion_tokens_dist`	直方图	补全 Token 分布（3.18.0+）

AI 缓存指标（3.18.0+）

指标	类型	描述
`apisix_ai_cache_hits_total`	计数器	按精确或语义 `layer` 统计的缓存命中数
`apisix_ai_cache_misses_total`	计数器	缓存未命中数
`apisix_ai_cache_bypasses_total`	计数器	跳过的查找数
`apisix_ai_cache_embedding_latency`	直方图	语义缓存嵌入延迟

若要删除高基数标签，请在 prometheus 插件元数据中设置 disabled_labels。不要禁用结构化标签，例如 HTTP 状态的 code、延迟/带宽/LLM 延迟的 type，或缓存命中的 layer。

延迟类型

request：从读取第一个字节到发送最后一个字节的总耗时
upstream：等待上游响应的耗时
apisix：request - upstream，即 APISIX 自身的处理开销

分步指南：启用 Prometheus 指标

1. 在路由上启用

a6 route create -f - <<'EOF'
{
  "id": "my-api",
  "uri": "/api/*",
  "plugins": {
    "prometheus": {
      "prefer_name": true
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

2. 全局启用(所有路由)

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/global_rules" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "id": "prometheus-global",
    "plugins": {
      "prometheus": {}
    }
  }'

3. 访问指标

默认端点：http://<gateway-host>:9091/apisix/prometheus/metrics

4. 配置 Prometheus 抓取

# prometheus.yml
scrape_configs:
  - job_name: apisix
    scrape_interval: 15s
    static_configs:
      - targets: ['127.0.0.1:9091']

5. 导入 Grafana Dashboard

下载与 APISIX 版本相匹配的 Dashboard JSON，例如：

https://raw.githubusercontent.com/apache/apisix/3.18.0/docs/assets/other/json/apisix-grafana-dashboard.json

Grafana.com 的 Dashboard 11719 面向 APISIX 2.10.x 和旧版面板，不适用于当前指标。

常见模式

自定义参数前缀和导出端口

在APISIX config.yaml中配置（不通过Admin API ）：

plugin_attr:
  prometheus:
    export_uri: /apisix/prometheus/metrics
    metric_prefix: apisix_
    enable_export_server: true
    export_addr:
      ip: 0.0.0.0
      port: 9091

为指标添加额外标签

plugin_attr:
  prometheus:
    metrics:
      http_status:
        extra_labels:
          - upstream_addr: $upstream_addr
      http_latency:
        extra_labels:
          - upstream_addr: $upstream_addr
      bandwidth:
        extra_labels:
          - upstream_addr: $upstream_addr

自定义直方图桶

plugin_attr:
  prometheus:
    default_buckets:
      - 10
      - 50
      - 100
      - 200
      - 500
      - 1000
      - 5000
      - 30000

配置同步示例

version: "1"
global_rules:
  - id: prometheus-global
    plugins:
      prometheus:
        prefer_name: true
routes:
  - id: my-api
    uri: /api/*
    upstream_id: my-upstream

故障排查

现象	原因	解决方法
端点没有指标	插件未启用	将 `prometheus: {}` 添加到路由或 global_rules
指标端口无法访问	`enable_export_server: false`	设置为 `true`，或使用 `public-api` 插件
缺少路由标签	`prefer_name: false` 且路由没有名称	设置 `prefer_name: true` 并为路由命名
没有 LLM 指标	APISIX 版本低于 3.15，或未配置 `ai-proxy`	升级 APISIX，并确保路由上启用了 `ai-proxy`
基数过高	额外标签过多	减少 `extra_labels`，在插件元数据中使用 `disabled_labels`，避免使用高基数变量
LLM 延迟看起来翻倍或 p99 错误	3.18.0 后选择器遗漏 `type`	筛选 `apisix_llm_latency{type="total"}`

本文根据 api7/a6 仓库中的 a6-plugin-prometheus/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。

概览​

适用场景​

插件配置参考（路由/服务/全局规则）​

导出的指标​

核心指标​

LLM/AI 指标（v3.15+）​

AI 缓存指标（3.18.0+）​

延迟类型​

分步指南：启用 Prometheus 指标​

1. 在路由上启用​

2. 全局启用(所有路由)​

3. 访问指标​

4. 配置 Prometheus 抓取​

5. 导入 Grafana Dashboard​

常见模式​

自定义参数前缀和导出端口​

为指标添加额外标签​

自定义直方图桶​

配置同步示例​

故障排查​

概览