跳到主要内容

a6-plugin-prometheus

概览​

prometheus 插件以 Prometheus 文本格式暴露 Apache APISIX指标，包括 HTTP 状态码、请求延迟、带宽、上游健康状态和系统状态。Apache APISIX提供内置指标端点，可由 Prometheus 抓取，并使用 Grafana 进行可视化。

适用场景​

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

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

字段类型是否必填默认值说明
prefer_nameboolean否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 流连接总数

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

指标类型描述
apisix_llm_latency直方图LLM 请求延迟
apisix_llm_prompt_tokens计数器消耗的提示词 Token 数量
apisix_llm_completion_tokens计数器消耗的补全 Token 数量
apisix_llm_active_connections仪表活跃的 LLM 连接数

延迟类型​

  • 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仪表板​

从 grafana.com 导入仪表板 ID 11719，用于预建的 APISIX 监控仪表板。

常见模式​

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

在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，避免指标数量爆炸

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