跳到主要内容

Prometheus

prometheus 插件提供了将 APISIX 与 Prometheus 集成的能力。

启用插件后，APISIX 将开始收集相关指标，例如 API 请求和延迟，并以基于文本的展示格式将它们导出到 Prometheus。然后，你可以在 Prometheus 中创建监控规则和告警，以监控 API 网关和 API 的健康状况。

指标​

Prometheus 中有不同类型的指标。要了解它们的区别，请参阅 指标类型。

默认情况下，prometheus 插件会导出以下指标。有关示例，请参阅 获取 APISIX 指标。请注意，如果没有数据，某些指标（如 apisix_batch_process_entries）可能不会立即显示。

名称类型描述
apisix_bandwidthcounter流经 APISIX 的总流量（以字节为单位）。
apisix_etcd_modify_indexesgaugeAPISIX 键对 etcd 的更改次数。
apisix_batch_process_entriesgauge批量发送数据时批次中的剩余条目数，例如使用 http logger 和其他日志插件时。
apisix_etcd_reachablegaugeAPISIX 是否可以连接到 etcd。值 1 表示可达，0 表示不可达。
apisix_http_statuscounter返回给客户端的 HTTP 状态码。这是经过插件处理和代理后客户端实际收到的状态，可能与上游状态不同。
apisix_http_requests_totalgauge来自客户端的 HTTP 请求数。
apisix_nginx_http_current_connectionsgauge当前与客户端的连接数。
apisix_nginx_metric_errors_totalcounternginx-lua-prometheus 错误总数。
apisix_http_latencyhistogramHTTP 请求延迟（以毫秒为单位）。
apisix_node_infogauge有关 APISIX 节点的信息，例如主机名和 APISIX 版本。
apisix_shared_dict_capacity_bytesgaugeNGINX 共享字典 的总容量。
apisix_shared_dict_free_space_bytesgaugeNGINX 共享字典 中的剩余空间。
apisix_upstream_statusgauge上游节点的健康检查状态，如果在上游配置了健康检查则可用。值 1 表示健康，0 表示不健康。
apisix_stream_connection_totalcounter每个流路由处理的连接总数。
apisix_stream_active_connectionsgauge每个流监听地址上活动的 TCP 连接与 UDP 会话数。需要 APISIX-Runtime。在 API7 企业版 3.9.x 系列中自 3.9.19 起支持，在 3.10.x 系列中自 3.10.6 起支持，并且在 APISIX 中自 3.18.0 起支持。
apisix_stream_statuscounter按终止状态、监听地址和上游节点统计的已结束流会话数。在 API7 企业版 3.9.x 系列中自 3.9.19 起支持，在 3.10.x 系列中自 3.10.6 起支持，并且在 APISIX 中自 3.18.0 起支持。
apisix_stream_bandwidthcounter流子系统按监听地址、方向和连接侧代理的字节数。需要 APISIX-Runtime。在 API7 企业版 3.9.x 系列中自 3.9.19 起支持，在 3.10.x 系列中自 3.10.6 起支持，并且在 APISIX 中自 3.18.0 起支持。
apisix_llm_prompt_tokenscounter提示词 Token 数量。仅对 AI 请求类型导出。自 API7 企业版 3.9.7 和 APISIX 3.17.0 起支持。
apisix_llm_completion_tokenscounter补全 Token 数量。仅对 AI 请求类型导出。自 API7 企业版 3.9.7 和 APISIX 3.17.0 起支持。
apisix_llm_latencyhistogramLLM 请求延迟，单位为毫秒。仅对 AI 请求类型导出。自 API7 企业版 3.9.7 和 APISIX 3.17.0 起支持。type 标签用于区分完整响应延迟（total）与流式请求的首 Token 时间（ttft），自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起引入。未指定 type 的查询会同时匹配两类观测值；如需保留此前的总延迟语义，请筛选 type="total"。每个流式请求会记录一个 total 样本和一个 ttft 样本。
apisix_llm_active_connectionsgauge正在处理的 LLM 上游请求数。仅对 AI 请求类型导出。自 API7 企业版 3.9.7 和 APISIX 3.17.0 起支持。
apisix_llm_prompt_tokens_disthistogram单个请求的提示词 Token 数量分布。仅对 AI 请求类型导出。自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起支持。
apisix_llm_completion_tokens_disthistogram单个请求的补全 Token 数量分布。仅对 AI 请求类型导出。自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起支持。
apisix_ai_cache_hits_totalcounter由 AI Cache 返回的请求数，按精确缓存层或语义缓存层区分。自 API7 企业版 3.9.16、3.10.3 和 APISIX 3.18.0 起支持。
apisix_ai_cache_misses_totalcounter未返回缓存响应的 AI Cache 查找次数。自 API7 企业版 3.9.16、3.10.3 和 APISIX 3.18.0 起支持。
apisix_ai_cache_bypasses_totalcounter绕过 AI Cache 查找的请求数。自 API7 企业版 3.9.16、3.10.3 和 APISIX 3.18.0 起支持。
apisix_ai_cache_embedding_latencyhistogram语义缓存层调用嵌入模型服务提供方的延迟，单位为毫秒。自 API7 企业版 3.9.16、3.10.3 和 APISIX 3.18.0 起支持。
备注

仅当请求由 AI 插件（例如 AI Proxy）处理时，才会导出 LLM 指标（apisix_llm_prompt_tokens、apisix_llm_completion_tokens、apisix_llm_latency、apisix_llm_prompt_tokens_dist 和 apisix_llm_completion_tokens_dist）。未启用 AI 插件的路由不会生成这些指标。apisix_llm_active_connections 由 AI 插件直接管理，也仅存在于启用了 AI 的路由中。

当一次 LLM 上游尝试开始时，该 gauge 增加；请求进入日志阶段后，该 gauge 减少。对于单次尝试，它表示正在处理的 LLM 上游请求。使用 ai-proxy-multi 回退重试时，每次重试都会增加一个新的实例级时序，而请求只会使用最终实例的标签减少一次。因此，失败实例的时序可能会一直高于真实活动请求数，直到指标过期或存储被重置。

要减少 LLM 指标中的高基数标签，请使用插件元数据中的 disabled_labels，有选择地禁用 consumer 或 node 等标签。

提示词和补全 Token 直方图使用可配置的桶。有关默认值和配置方式，请参阅静态插件属性。

标签​

标签 是指标的属性，用于区分指标。

例如，apisix_http_status 指标可以用 route 信息进行标记，以识别 HTTP 状态源自哪个路由。

以下是非详尽的 APISIX 指标及其描述的标签列表。

apisix_http_status 的标签​

以下标签用于区分 apisix_http_status 指标。

名称描述
code上游节点返回的 HTTP 响应代码。
route当 prefer_name 为 false（默认值）时，为 HTTP 状态源自的路由 ID；当 prefer_name 为 true 时，为路由名称。如果请求不匹配任何路由，则默认为空字符串。
route_id仅在 Enterprise 中可用。无论 prefer_name 设置如何，HTTP 状态源自的路由 ID。
matched_uri匹配请求的路由 URI。如果请求不匹配任何路由，则默认为空字符串。
matched_host匹配请求的路由主机。如果请求不匹配任何路由，或者路由上未配置主机，则默认为空字符串。
service当 prefer_name 为 false（默认值）时，为 HTTP 状态源自的服务 ID；当 prefer_name 为 true 时，为服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。
service_id仅在 Enterprise 中可用。无论 prefer_name 设置如何，HTTP 状态源自的服务 ID。
consumer与请求关联的消费者名称。如果请求没有关联消费者，则默认为空字符串。
node上游节点的 IP 地址。
gateway_group_idHTTP 状态源自的网关组 ID。仅 API7 企业版可用。
instance_idHTTP 状态源自的网关实例 ID。仅 API7 企业版可用。
api_product_idHTTP 状态源自的产品 ID。仅 API7 企业版可用。
request_type与 HTTP 状态关联的请求类型：traditional_http、websocket、ai_chat 或 ai_stream。以 101 Switching Protocols 应答的请求为 websocket，在 API7 企业版 3.9.x 系列中自 3.9.21 起引入，在 3.10.x 系列中自 3.10.7 起引入。
request_llm_model客户端请求中指定的 LLM 模型。
llm_model处理请求的 LLM 模型。
response_sourceHTTP 响应的来源：apisix（由 APISIX 生成，如插件拒绝或路由未找到）、nginx（NGINX 代理错误，如连接被拒绝或上游超时）或 upstream（来自上游服务的真实响应）。该标签自 API7 企业版 3.9.10 和 APISIX 3.17.0 起提供。
mcp_request_typeMCP 请求类型，例如 tools/list 或 tools/call。非 MCP 请求为空。自 API7 企业版 3.9.14 起支持。
mcp_tool_nametools/call 请求中的 MCP 工具名称，其他请求为空。自 API7 企业版 3.9.14 起支持。

response_source 是 apisix_http_status 的必需标签，每个既有状态标签组合最多可能新增三个时序。发布前请更新匹配完整标签集的 PromQL join、记录规则、告警和 Dashboard，并评估新增基数。

apisix_bandwidth 的标签​

以下标签用于区分 apisix_bandwidth 指标。

名称描述
type流量类型，egress（出口）或 ingress（入口）。
route当 prefer_name 为 false（默认值）时，为带宽对应的路由 ID；当 prefer_name 为 true 时，为路由名称。如果请求不匹配任何路由，则默认为空字符串。
route_id仅在 Enterprise 中可用。无论 prefer_name 设置如何，带宽对应的路由 ID。
service当 prefer_name 为 false（默认值）时，为带宽对应的服务 ID；当 prefer_name 为 true 时，为服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。
service_id仅在 Enterprise 中可用。无论 prefer_name 设置如何，带宽对应的服务 ID。
consumer与请求关联的消费者名称。如果请求没有关联消费者，则默认为空字符串。
node上游节点的 IP 地址。
gateway_group_id仅在 Enterprise 中可用。带宽对应的网关组 ID。
instance_id仅在 Enterprise 中可用。带宽对应的网关实例 ID。
api_product_id仅在 Enterprise 中可用。带宽对应的产品 ID。
request_type带宽对应的请求类型：traditional_http、websocket、ai_chat 或 ai_stream。以 101 Switching Protocols 应答的请求为 websocket，在 API7 企业版 3.9.x 系列中自 3.9.21 起引入，在 3.10.x 系列中自 3.10.7 起引入。
request_llm_model仅在企业版（自 3.9.7 起）可用。客户端请求中指定的 LLM 模型。
llm_model仅在 Enterprise 中可用。带宽对应的 LLM 模型。
mcp_request_type仅在企业版（自 3.9.14 版本起）可用。MCP 请求类型，例如 tools/list 或 tools/call。非 MCP 请求为空。
mcp_tool_name仅在企业版（自 3.9.14 版本起）可用。tools/call 请求中的 MCP 工具名称，其他请求为空。

apisix_http_latency 的标签​

以下标签用于区分 apisix_http_latency 指标。

名称描述
type延迟类型。有关详细信息，请参阅 延迟类型。
route当 prefer_name 为 false（默认值）时，为延迟对应的路由 ID；当 prefer_name 为 true 时，为路由名称。如果请求不匹配任何路由，则默认为空字符串。
route_id仅在 Enterprise 中可用。无论 prefer_name 设置如何，延迟对应的路由 ID。
service当 prefer_name 为 false（默认值）时，为延迟对应的服务 ID；当 prefer_name 为 true 时，为服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。
service_id仅在 Enterprise 中可用。无论 prefer_name 设置如何，延迟对应的服务 ID。
consumer与延迟关联的消费者名称。如果请求没有关联消费者，则默认为空字符串。
node与延迟关联的上游节点的 IP 地址。
gateway_group_id仅在 Enterprise 中可用。延迟对应的网关组 ID。
instance_id仅在 Enterprise 中可用。延迟对应的网关实例 ID。
api_product_id仅在 Enterprise 中可用。延迟对应的产品 ID。
request_type延迟对应的请求类型：traditional_http、websocket、ai_chat 或 ai_stream。以 101 Switching Protocols 应答的请求为 websocket，在 API7 企业版 3.9.x 系列中自 3.9.21 起引入，在 3.10.x 系列中自 3.10.7 起引入。
request_llm_model仅在企业版（自 3.9.7 起）可用。客户端请求中指定的 LLM 模型。
llm_model仅在 Enterprise 中可用。延迟对应的 LLM 模型。
mcp_request_type仅在企业版（自 3.9.14 版本起）可用。MCP 请求类型，例如 tools/list 或 tools/call。非 MCP 请求为空。
mcp_tool_name仅在企业版（自 3.9.14 版本起）可用。tools/call 请求中的 MCP 工具名称，其他请求为空。

延迟类型​

apisix_http_latency 可以用以下三种类型之一进行标记：

  • request 表示从客户端读取第一个字节到向客户端发送最后一个字节后的日志写入之间经过的时间。

  • upstream 表示等待上游服务响应所经过的时间。

  • apisix 表示 request 延迟与 upstream 延迟之间的差值。

对于 WebSocket 会话，request 和 upstream 延迟衡量的是升级后的连接保持打开的时长，而不是一次请求-响应往返。在 API7 企业版 3.9.x 系列中自 3.9.21 起、在 3.10.x 系列中自 3.10.7 起，这类请求带有 request_type="websocket"，因此可以用 request_type!="websocket" 把它们排除在延迟查询之外。

换句话说，APISIX 延迟不仅仅归因于 Lua 处理。它应该理解如下：

APISIX latency
  = downstream request time - upstream response time
  = downstream traffic latency + NGINX latency

apisix_upstream_status 的标签​

以下标签用于区分 apisix_upstream_status 指标。

名称描述
name配置了健康检查的上游对应的资源 ID，例如 /apisix/routes/1 和 /apisix/upstreams/1。
ip上游节点的 IP 地址。
port节点的端口号。

流指标的标签​

apisix_stream_active_connections 以流监听地址作为标签：

名称描述
listen_addrAPISIX 接受该 TCP 连接或 UDP 会话的地址，例如 0.0.0.0:9100。

apisix_stream_status 在每个流会话结束时记录一次：

名称描述
code会话的结束方式。200 表示正常关闭。400 表示客户端侧的问题，例如客户端重置连接或发送了无效数据。403 表示被访问规则拒绝。500 表示内部错误。502 表示上游或传输层问题，例如连接失败、重置或空闲超时。503 表示被连接数限制拒绝。
listen_addrAPISIX 接受该会话的地址。
node选中的上游地址，形式为 IP:端口。会话在 APISIX 选出上游之前结束时为空。

对于上游连接建立之后发生的部分失败，NGINX 报告的 Stream $status 仍为 200。该指标改用会话终止原因来区分正常关闭与之后的超时或重置。worker 关闭以及未记录到可识别原因时同样使用 200。

apisix_stream_bandwidth 在会话保持打开期间持续更新：

名称描述
listen_addrAPISIX 接受该会话的地址。
type流量方向：ingress 或 egress。
side连接侧：downstream 或 upstream。

apisix_llm_latency 的标签​

以下标签用于区分 apisix_llm_latency 指标。

名称描述
typeLLM 延迟类型：total 表示完整响应延迟，ttft 表示流式请求的首 Token 时间。自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起引入。此前将每个 apisix_llm_latency 样本都视为总延迟的 Dashboard、告警和记录规则必须添加 type="total"。
route当 prefer_name 为 false（默认值）时，为 HTTP 状态源自的路由 ID；当 prefer_name 为 true 时，为路由名称。如果请求不匹配任何路由，则默认为空字符串。
route_id无论 prefer_name 设置如何，HTTP 状态源自的路由 ID。
service当 prefer_name 为 false（默认值）时，为 HTTP 状态源自的服务 ID；当 prefer_name 为 true 时，为服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。
service_id无论 prefer_name 设置如何，HTTP 状态源自的服务 ID。
consumer与请求关联的消费者名称。如果请求没有关联消费者，则默认为空字符串。
nodeai-proxy 或 ai-proxy-multi 选中的 LLM 实例名称，而不是上游 IP 地址。
gateway_group_idHTTP 状态源自的网关组 ID。
instance_idHTTP 状态源自的网关实例 ID。
api_product_idHTTP 状态源自的产品 ID。
request_typeHTTP 状态源自的请求类型。
request_llm_model客户端请求中发送的模型名称。自 API7 企业版 3.9.7 和 APISIX 3.17.0 起引入。
llm_model网关实际使用的目标模型。如果 AI 实例配置了模型，则使用该值；否则使用客户端请求的模型。

其他 LLM 指标的标签​

以下标签用于区分 apisix_llm_prompt_tokens、apisix_llm_completion_tokens、apisix_llm_active_connections、apisix_llm_prompt_tokens_dist 和 apisix_llm_completion_tokens_dist 指标。

名称描述
route当 prefer_name 为 false（默认值）时，为 HTTP 状态源自的路由 ID；当 prefer_name 为 true 时，为路由名称。如果请求不匹配任何路由，则默认为空字符串。
route_id无论 prefer_name 设置如何，HTTP 状态源自的路由 ID。
matched_uri匹配请求的路由 URI。如果请求不匹配任何路由，则默认为空字符串。
matched_host匹配请求的路由主机。如果请求不匹配任何路由，或者路由上未配置主机，则默认为空字符串。
service当 prefer_name 为 false（默认值）时，为 HTTP 状态源自的服务 ID；当 prefer_name 为 true 时，为服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。
service_id无论 prefer_name 设置如何，HTTP 状态源自的服务 ID。
consumer与请求关联的消费者名称。如果请求没有关联消费者，则默认为空字符串。
nodeai-proxy 或 ai-proxy-multi 选中的 LLM 实例名称，而不是上游 IP 地址。
gateway_group_idHTTP 状态源自的网关组 ID。
instance_idHTTP 状态源自的网关实例 ID。
api_product_idHTTP 状态源自的产品 ID。
request_typeHTTP 状态源自的请求类型。
request_llm_model客户端请求中发送的模型名称。自 API7 企业版 3.9.7 和 APISIX 3.17.0 起引入。
llm_model网关实际使用的目标模型。如果 AI 实例配置了模型，则使用该值；否则使用客户端请求的模型。

提示词与补全 Token 计数器和分布直方图在不同产品中使用不同的标签集。APISIX 导出 route_id、service_id、consumer、node、request_type、request_llm_model 和 llm_model。API7 企业版还导出 route、matched_uri、matched_host 和 service，以及网关实例和 API 产品标签。

request_llm_model 和 llm_model 的值来自客户端和服务提供方数据，最长为 128 字节。自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起引入。如果不需要按模型拆分时序，请禁用这些标签。

AI Cache 指标的标签​

四个 AI Cache 指标共享以下标签。只有 apisix_ai_cache_hits_total 包含 layer。

名称描述
layer返回缓存命中的缓存层：exact 或 semantic。该结构性标签不能禁用。
route路由名称；如果路由没有名称，则为空字符串。
route_id路由 ID。
service服务名称；如果路由未引用服务，则为空字符串。
service_id服务 ID；如果路由未引用服务，则为空字符串。
consumerConsumer 名称；如果请求未关联 Consumer，则为空字符串。
nodeai-proxy 或 ai-proxy-multi 选中的 LLM 实例名称，而不是上游 IP 地址。
request_type请求类型，例如 ai_chat 或 ai_stream。
request_llm_model客户端请求中发送的模型名称。
llm_model网关实际使用的目标模型。如果 AI 实例配置了模型，则使用该值；否则使用客户端请求的模型。缓存命中时不会访问 LLM，因此该值为空。

API7 企业版还为这些指标导出 matched_uri、matched_host，以及网关实例和 API 产品标签。

示例​

下面的示例展示了如何在不同场景下使用 prometheus 插件。

获取 APISIX 指标​

以下示例展示了如何从 APISIX 获取指标。

默认的 Prometheus 指标端点和其他 Prometheus 相关配置可以在静态配置中找到。如果你想自定义这些配置，请参阅配置文件。

如果你在容器化环境中部署网关，并希望从外部访问 Prometheus 指标端点，请在网关静态配置中更新 Prometheus 导出地址：

在网关配置文件中新增或更新以下配置：

config.yaml
plugin_attr:
  prometheus:
    export_addr:
      ip: 0.0.0.0

重新加载网关以使更改生效。

向 APISIX Prometheus 指标端点发送请求：

curl "http://127.0.0.1:9091/apisix/prometheus/metrics"

你应该看到类似于以下的输出：

# HELP apisix_bandwidth Total bandwidth in bytes consumed per service in Apisix
# TYPE apisix_bandwidth counter
apisix_bandwidth{type="egress",route="",service="",consumer="",node=""} 8417
apisix_bandwidth{type="egress",route="1",service="",consumer="",node="127.0.0.1"} 1420
apisix_bandwidth{type="egress",route="2",service="",consumer="",node="127.0.0.1"} 1420
apisix_bandwidth{type="ingress",route="",service="",consumer="",node=""} 189
apisix_bandwidth{type="ingress",route="1",service="",consumer="",node="127.0.0.1"} 332
apisix_bandwidth{type="ingress",route="2",service="",consumer="",node="127.0.0.1"} 332
# HELP apisix_etcd_modify_indexes Etcd modify index for APISIX keys
# TYPE apisix_etcd_modify_indexes gauge
apisix_etcd_modify_indexes{key="consumers"} 0
apisix_etcd_modify_indexes{key="global_rules"} 0
...

通过禁用标签降低指标基数​

插件元数据可将选定标签的值折叠为空字符串，在保留指标标签模式的同时减少时序数量。APISIX 和 API7 企业版为 HTTP 状态和延迟指标使用不同的元数据键。

API7 企业版会导出额外维度，因此两种产品接受的标签也有所不同：

指标元数据键APISIX 中可禁用的标签API7 企业版的差异
http_statusroute、matched_uri、matched_host、service、consumer、node、request_type、request_llm_model、llm_model、response_source使用键 status。额外支持 route_id、service_id、mcp_request_type 和 mcp_tool_name，但不允许禁用 response_source。
http_latencyroute、service、consumer、node、request_type、request_llm_model、llm_model使用键 latency。额外支持 route_id、service_id、mcp_request_type 和 mcp_tool_name。
bandwidthroute、service、consumer、node、request_type、request_llm_model、llm_model额外支持 route_id、service_id、mcp_request_type 和 mcp_tool_name。
llm_latencyroute_id、service_id、consumer、node、request_type、request_llm_model、llm_model还支持 route 和 service。
llm_prompt_tokens、llm_completion_tokens、llm_prompt_tokens_dist、llm_completion_tokens_distroute_id、service_id、consumer、node、request_type、request_llm_model、llm_model还支持 route、matched_uri、matched_host 和 service。
llm_active_connectionsroute、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model、llm_model标签相同。
ai_cache_hits_total、ai_cache_misses_total、ai_cache_bypasses_total、ai_cache_embedding_latencyroute、route_id、service、service_id、consumer、node、request_type、request_llm_model、llm_model还支持 matched_uri 和 matched_host。

本表不包含结构性标签，因为这些标签不能禁用。

在 API7 企业版中，stream_status 元数据键可以禁用 apisix_stream_status 的 node 标签。code 和 listen_addr 是结构性标签。自 API7 企业版 3.9.19 和 3.10.6 起引入。

在 APISIX 中，使用以下配置禁用 HTTP 状态和延迟指标的 node 标签：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/prometheus" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "disabled_labels": {
      "http_status": ["node"],
      "http_latency": ["node"]
    }
  }'

对于 API7 企业版，请改用 status 和 latency：

{
  "disabled_labels": {
    "status": ["node"],
    "latency": ["node"]
  }
}

通过启用了该插件的路由发送请求，然后获取指标端点。受影响的时序应保留 node 标签，但其值为空：

apisix_http_status{code="200",route="1",matched_uri="/get",matched_host="",service="",consumer="",node="",request_type="traditional_http",request_llm_model="",llm_model="",response_source="upstream"} 1

模式会拒绝用于区分不同测量值的结构性标签，包括 HTTP 状态的 code，HTTP 延迟、带宽和 LLM 延迟的 type，以及 AI Cache 命中的 layer。APISIX 与 API7 企业版的可选标签集并不相同；请根据所配置的网关查阅插件元数据参考。

在公共 API 端点上暴露 APISIX 指标​

以下示例展示了如何禁用默认在端口 9091 上暴露端点的 Prometheus 导出服务器，并在 APISIX 用于监听其他客户端请求的端口 9080 上的新公共 API 端点上暴露 APISIX Prometheus 指标。

警告

如果收集大量指标，插件可能会占用大量 CPU 资源进行指标计算，并对常规请求的处理产生负面影响。

为了解决这个问题，APISIX 使用 特权代理（privileged agent） 并将指标计算卸载到单独的进程。如果你使用配置文件中配置的指标端点（如 上文 所示），此优化将自动应用。如果你使用 public-api 插件暴露指标端点，你将无法从该优化中受益。

要通过 public-api 暴露指标，请先禁用默认的 Prometheus 导出服务器：

在网关配置文件中新增或更新以下配置：

config.yaml
plugin_attr:
  prometheus:
    enable_export_server: false

重新加载网关以使更改生效。

接下来，创建一个带有 public-api 插件的路由，并为 APISIX 指标暴露一个公共 API 端点：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-metrics",
    "uri": "/prometheus_metrics",
    "plugins": {
      "public-api": {
        "uri": "/apisix/prometheus/metrics"
      }
    }
  }'

向新的指标端点发送请求以进行验证：

curl "http://127.0.0.1:9080/prometheus_metrics"

你应该看到类似于以下的输出：

# HELP apisix_http_requests_total The total number of client requests since APISIX started
# TYPE apisix_http_requests_total gauge
apisix_http_requests_total 1
# HELP apisix_nginx_http_current_connections Number of HTTP connections
# TYPE apisix_nginx_http_current_connections gauge
apisix_nginx_http_current_connections{state="accepted"} 1
apisix_nginx_http_current_connections{state="active"} 1
apisix_nginx_http_current_connections{state="handled"} 1
apisix_nginx_http_current_connections{state="reading"} 0
apisix_nginx_http_current_connections{state="waiting"} 0
apisix_nginx_http_current_connections{state="writing"} 1
...

将 APISIX 与 Prometheus 和 Grafana 集成​

要了解如何使用 Prometheus 收集 APISIX 指标并在 Grafana 中将其可视化，请参阅 操作指南。

监控上游健康状态​

以下示例展示了如何监控上游节点的健康状态。

创建一个带有 prometheus 插件的路由并配置上游主动健康检查：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-route",
    "uri": "/get",
    "plugins": {
      "prometheus": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1,
        "127.0.0.1:20001": 1
      },
      "checks": {
        "active": {
          "timeout": 5,
          "http_path": "/status",
          "healthy": {
            "interval": 2,
            "successes": 1
          },
          "unhealthy": {
            "interval": 1,
            "http_failures": 2
          }
        },
        "passive": {
          "healthy": {
            "http_statuses": [200, 201],
            "successes": 3
          },
          "unhealthy": {
            "http_statuses": [500],
            "http_failures": 3,
            "tcp_failures": 3
          }
        }
      }
    }
  }'

向 APISIX Prometheus 指标端点发送请求：

curl "http://127.0.0.1:9091/apisix/prometheus/metrics"

你应该看到类似于以下的输出：

# HELP apisix_upstream_status upstream status from health check
# TYPE apisix_upstream_status gauge
apisix_upstream_status{name="/upstreams/<id>",ip="<healthy-node-ip>",port="80"} 1
apisix_upstream_status{name="/upstreams/<id>",ip="<unhealthy-node-ip>",port="80"} 0

在该示例输出中，一个上游节点处于健康状态，另一个上游节点处于不健康状态。

要了解有关如何配置主动和被动健康检查的更多信息，请参阅 健康检查。

为指标添加额外标签​

以下示例展示了如何向指标添加额外标签并在标签值中使用 内置变量。

目前，只有以下指标支持额外标签：

  • apisix_http_status
  • apisix_http_latency
  • apisix_bandwidth
  • 上文列出的所有 apisix_llm_* 指标
  • 全部四个 apisix_ai_cache_* 指标

APISIX 和 API7 网关以相同方式应用额外标签。

请在 Prometheus 静态配置中添加额外标签：

在网关配置文件中新增或更新以下配置：

config.yaml
plugin_attr:
  prometheus:                                # prometheus 插件
    metrics:                                 # 使用内置变量创建额外标签。
      http_status:
        extra_labels:                        # 设置 http_status 指标的额外标签。
          - upstream_addr: $upstream_addr    # 添加 upstream_addr 标签，其值为 NGINX 变量 $upstream_addr。
          - route_name: $route_name          # 添加 route_name 标签，其值为 APISIX 变量 $route_name。

重新加载网关以使更改生效。

请注意，如果你在标签值中定义了一个变量，但它不对应任何现有的 内置变量，则标签值将默认为空字符串。

创建一个带有 prometheus 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-route",
    "uri": "/get",
    "name": "extra-label",
    "plugins": {
      "prometheus": {}
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求到该路由以进行验证：

curl -i "http://127.0.0.1:9080/get"

你应该看到 HTTP/1.1 200 OK 响应。

向 APISIX Prometheus 指标端点发送请求：

curl "http://127.0.0.1:9091/apisix/prometheus/metrics"

你应该看到类似于以下的输出：

# HELP apisix_http_status HTTP status codes per service in APISIX
# TYPE apisix_http_status counter
apisix_http_status{code="200",route="1",matched_uri="/get",matched_host="",service="",consumer="",node="54.237.103.220",request_type="traditional_http",request_llm_model="",llm_model="",response_source="upstream",upstream_addr="54.237.103.220:80",route_name="extra-label"} 1

使用 Prometheus 监控 TCP/UDP 流量​

以下示例展示了如何在 APISIX 中收集 TCP/UDP 流量指标。

如需收集 TCP/UDP 指标，请启用 stream proxy，并将 prometheus 添加到现有 stream 插件列表中。请保留部署使用的其他 stream 插件；以下主机/Docker 示例展示了本教程所需的最小列表。

在网关配置文件中新增或更新以下配置：

config.yaml
apisix:
  proxy_mode: http&stream   # 同时启用 L4 和 L7 代理
  stream_proxy:             # 配置 L4 代理
    tcp:
      - 9100                # 设置 TCP 代理监听端口
    udp:
      - 9200                # 设置 UDP 代理监听端口

stream_plugins:
  - prometheus              # 为 stream proxy 启用 prometheus

重新加载网关以使更改生效。

创建一个启用了 prometheus 插件的流路由：

curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-route",
    "plugins": {
      "prometheus":{}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求到该流路由以进行验证：

curl -i "http://127.0.0.1:9100"

你应该看到 HTTP/1.1 200 OK 响应。

向 APISIX Prometheus 指标端点发送请求：

curl "http://127.0.0.1:9091/apisix/prometheus/metrics"

你应该看到类似于以下的输出：

# HELP apisix_stream_connection_total Total number of connections handled per stream route in APISIX
# TYPE apisix_stream_connection_total counter
apisix_stream_connection_total{route="prometheus-route"} 1

APISIX 还会导出终止状态。如果 APISIX-Runtime 提供 stream-metrics 模块，抓取结果还会包含活动连接和带宽：

# HELP apisix_stream_active_connections Number of stream sessions currently being proxied per listening address
# TYPE apisix_stream_active_connections gauge
apisix_stream_active_connections{listen_addr="0.0.0.0:9100"} 0
# HELP apisix_stream_status Stream sessions per termination status in APISIX
# TYPE apisix_stream_status counter
apisix_stream_status{code="200",listen_addr="0.0.0.0:9100",node="54.237.103.220:80"} 1
# HELP apisix_stream_bandwidth Total bandwidth in bytes proxied by the stream subsystem in APISIX
# TYPE apisix_stream_bandwidth counter
apisix_stream_bandwidth{listen_addr="0.0.0.0:9100",type="ingress",side="downstream"} 78
apisix_stream_bandwidth{listen_addr="0.0.0.0:9100",type="egress",side="downstream"} 219
apisix_stream_bandwidth{listen_addr="0.0.0.0:9100",type="egress",side="upstream"} 78
apisix_stream_bandwidth{listen_addr="0.0.0.0:9100",type="ingress",side="upstream"} 219

具体上游地址和字节数取决于请求。上例中的活动连接 gauge 为 0，因为请求在抓取前已完成；请在连接保持打开时进行抓取，以观察正值。

活动连接和带宽指标使用默认大小为 1m 的共享内存区域。当网关暴露大量 stream 监听地址时，请增大该区域：

config.yaml
nginx_config:
  stream:
    metrics_zone_size: 2m

更改区域大小后，请重新加载 APISIX。在没有 stream-metrics 模块的运行时中，APISIX 会继续导出连接总数和状态指标，但不会发布活动连接或带宽指标。