Prometheus 监控 APISIX 全栈实战云原生 API 网关的透明化可观测性Apache APISIX 作为云原生 API 网关的佼佼者凭借其动态路由、插件热插拔和高性能支撑着无数微服务集群的流量入口。它的请求吞吐量、上游健康状态、响应延迟分布、etcd 连接可靠性以及插件执行效率直接决定了业务 API 的可用性与用户体验。从 APISIX 2.0 版本开始内置的 prometheus 插件就可将核心指标以 Prometheus 标准格式暴露无需额外部署 Exporter。本文将带你从启用插件、配置抓取到解读关键指标、搭建 Grafana 大屏和落地告警规则彻底透视 APISIX 网关的每一个细节。1. 为什么选择 APISIX 原生 Prometheus 插件零侵入插件内置通过 Admin API 或声明式配置即可全局启用无需重启。指标丰富涵盖 HTTP 请求、连接数、带宽、上游状态、etcd 健康、插件调用统计等。高性能基于内置的prometheus插件采集对数据平面转发性能影响微乎其微。多协议支持同时监控 HTTP 和 gRPC 流量。生态兼容完美对接 Prometheus Operator、Grafana 社区仪表盘。2. 启用 Prometheus 插件2.1 全局启用推荐通过 APISIX Admin API默认http://127.0.0.1:9180/apisix/admin全局启用使所有服务和路由的指标统一收集。curlhttp://127.0.0.1:9180/apisix/admin/global_rules/1-XPUT\-HX-API-KEY: edd1c9f034335f136f87ad84b625c8f1\-d{ plugins: { prometheus: { prefer_name: true } } }参数prefer_name设为true时指标标签中会使用路由和服务的名称而非 ID更易读。2.2 在特定路由上启用如果只需监控特定接口可针对单个路由启用curlhttp://127.0.0.1:9180/apisix/admin/routes/1-XPATCH\-HX-API-KEY: ...\-d{ plugins: { prometheus: {} } }2.3 验证端点APISIX 默认在数据平面端口 9091上暴露/apisix/prometheus/metricsAPISIX 2.7 开始。在配置文件中确认plugin_attr.prometheus的export_addr# conf/config.yamlplugin_attr:prometheus:export_addr:ip:0.0.0.0port:9091重启 APISIX 后访问curlhttp://localhost:9091/apisix/prometheus/metrics你将看到apisix_http_requests_total、apisix_bandwidth、apisix_etcd_modify_index等指标。注意早期版本可能直接在127.0.0.1:9091/metrics或通过数据面端口提供具体以版本为准。本文以 3.x 版本默认路径/apisix/prometheus/metrics为准。3. 配置 Prometheus 抓取3.1 静态配置scrape_configs:-job_name:apisixscrape_interval:15smetrics_path:/apisix/prometheus/metricsstatic_configs:-targets:[apisix-node1:9091,apisix-node2:9091]labels:cluster:prodcomponent:gateway3.2 Kubernetes 环境自动发现如果 APISIX 部署在 K8s 中使用 PodMonitorapiVersion:monitoring.coreos.com/v1kind:PodMonitormetadata:name:apisixspec:selector:matchLabels:app.kubernetes.io/name:apisixpodMetricsEndpoints:-port:prometheuspath:/apisix/prometheus/metricsinterval:15s需确保 APISIX Pod 暴露了名为prometheus的容器端口对应 9091。4. 核心监控指标与 PromQLAPISIX 的 Prometheus 插件暴露的指标以apisix_为前缀标签包括route、service、consumer、node、status等。4.1 HTTP 请求与状态码指标含义apisix_http_requests_totalHTTP 请求总数Counter按route、service、consumer、status分组apisix_http_status各状态码的请求数与上类似视版本可能合并PromQL 示例整体 QPSsum(rate(apisix_http_requests_total[1m]))5xx 错误率sum(rate(apisix_http_requests_total{status~5..}[5m])) / sum(rate(apisix_http_requests_total[5m]))某个路由的 QPSrate(apisix_http_requests_total{routemy-route}[1m])4.2 延迟指标含义apisix_http_latency(Histogram)APISIX 处理延迟从接收到请求到转发给上游的时间apisix_upstream_latency(Histogram)上游服务响应时间PromQLAPISIX 处理延迟 P95histogram_quantile(0.95, rate(apisix_http_latency_bucket[5m]))上游延迟 P99histogram_quantile(0.99, rate(apisix_upstream_latency_bucket[5m]))4.3 带宽指标含义apisix_bandwidth(Counter)入口和出口流量字节数标签type为ingress或egressPromQL入口流量字节/秒rate(apisix_bandwidth{typeingress}[1m])出口流量rate(apisix_bandwidth{typeegress}[1m])4.4 连接数指标含义apisix_nginx_http_current_connections当前 HTTP 连接数包含 reading、writing、waiting类似 Nginx 连接状态。告警apisix_nginx_http_current_connections{statewriting} 100004.5 上游健康与状态指标含义apisix_upstream_status上游健康检查状态1健康0不健康按upstream标签apisix_node_info节点信息主机名、版本等告警上游不健康apisix_upstream_status{upstreambackend-api} 04.6 etcd 连接与同步指标含义apisix_etcd_modify_indexetcd 修改索引反映配置变更频率apisix_etcd_reachableetcd 是否可达1连通0断开PromQLetcd 断连apisix_etcd_reachable 0立即告警配置变更速率rate(apisix_etcd_modify_index[5m])4.7 插件调用统计指标含义apisix_plugin_metrics特定插件如limit-count、prometheus本身的执行计数和延迟可据此分析限流、认证等插件的性能影响。5. Grafana 仪表盘推荐APISIX Official DashboardDashboard ID11719Apache APISIX 社区官方仪表盘完美适配 APISIX 2.x/3.x 的 Prometheus 指标涵盖 QPS、延迟、带宽、上游状态、etcd 健康等。APISIX Ingress Controller若在 Kubernetes 中使用可导入 ID14403。自定义业务视图基于route或service标签创建 QPS 排行、错误率热力、延迟分位数面板。导入后选择数据源通过cluster或instance变量区分不同 APISIX 集群。6. 告警规则实战groups:-name:apisix_alertsrules:-alert:APISIXNodeDownexpr:up{jobapisix} 0for:1mlabels:severity:criticalannotations:summary:APISIX 节点 {{ $labels.instance }} 指标端点不可达-alert:APISIXEtcdDisconnectedexpr:apisix_etcd_reachable 0for:1mlabels:severity:criticalannotations:summary:APISIX 与 etcd 失去连接配置可能无法生效-alert:APISIXHigh5xxRateexpr:sum(rate(apisix_http_requests_total{status~5..}[5m])) by (instance) / sum(rate(apisix_http_requests_total[5m])) by (instance)0.01for:5mlabels:severity:criticalannotations:summary:APISIX 节点 {{ $labels.instance }} 5xx 错误率超过 1%-alert:APISIXUpstreamUnhealthyexpr:apisix_upstream_status 0for:2mlabels:severity:criticalannotations:summary:上游服务 {{ $labels.upstream }} 健康检查失败-alert:APISIXHighUpstreamLatencyexpr:histogram_quantile(0.99,rate(apisix_upstream_latency_bucket[5m]))2for:5mlabels:severity:warningannotations:summary:上游服务 P99 延迟超过 2 秒-alert:APISIXHighConnectionsexpr:apisix_nginx_http_current_connections{statewriting}10000for:5mlabels:severity:warningannotations:summary:APISIX 正在写响应的连接数超过 10000可能过载-alert:APISIXBandwidthSaturationexpr:rate(apisix_bandwidth{typeingress}[5m]) * 8 / 1e90.8for:10mlabels:severity:warningannotations:summary:入口带宽使用率接近物理网卡上限根据实际硬件和流量调整阈值。7. 进阶多节点、安全与自定义指标7.1 监控多个 APISIX 节点每个节点独立暴露指标端点Prometheus 中使用文件服务发现或 Kubernetes Pod 注解自动添加。使用标签instance或node区分。Grafana 中可通过变量切换或聚合。7.2 安全加固指标端口保护9091 端口仅监听内网 IP (export_addr设为127.0.0.1或内网 IP)或使用防火墙限制。认证APISIX 指标端点本身无鉴权建议通过 Nginx/Caddy 反向代理添加 Basic Auth然后 Prometheus 配置basic_auth。Admin API 隔离永远不要将 Admin API (9180) 暴露到公网。7.3 自定义业务指标APISIX 支持通过serverless插件或自定义 Lua 插件向prometheus模块注册新指标。例如统计特定 API 的调用次数localprometheusrequire(apisix.plugins.prometheus)prometheus.define_metric(custom_api_calls,counter,API calls,{api_name})-- 在逻辑中prometheus.inc(custom_api_calls,{login})这些自定义指标会同样暴露在/apisix/prometheus/metrics端点。7.4 结合日志与追踪当告警触发时可联动 APISIX 的访问日志写入 Kafka/Loki和 SkyWalking/Zipkin 追踪快速定位错误原因。Prometheus 负责发现问题日志和追踪负责诊断问题。8. 总结通过 APISIX 内置的 Prometheus 插件云原生 API 网关的每一个请求、每一字节带宽、每一次上游健康检查和 etcd 同步状态都转化为可查询、可告警的时序数据。结合 Grafana 仪表盘和 Alertmanager 的及时通知你可以在网关 5xx 错误率攀升、上游服务宕机或 etcd 断连时第一时间响应。将 APISIX 的可观测性无缝纳入全栈监控体系意味着从网关到后端微服务整个流量生命周期的透明化已经完成。部署它让 APISIX 不仅是高性能的流量入口更是完全可观测的云原生网关基石。