# 数据面指标参考

API7 网关通过数据面的 Prometheus 端点导出节点、HTTP 流量、AI 和流式代理指标。可用的序列取决于网关版本、已配置的插件和实际流量：节点指标描述正在运行的网关，而请求指标会在相应功能处理流量后出现。

下列指标名称使用默认的 `apisix_` 前缀。你可以通过 `plugin_attr.prometheus.metric_prefix` 更改前缀，并通过 [`prometheus` 插件配置](https://docs.apiseven.com/hub/prometheus.md)添加或移除部分请求标签。

## 节点指标[​](#节点指标 "节点指标的直接链接")

以下指标描述网关进程及其配置连接。它们不要求路由上运行 `prometheus` 插件。

| 指标                                    | 类型  | 内置标签                                      | 说明                                                                                     |
| --------------------------------------- | ----- | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `apisix_nginx_http_current_connections` | Gauge | `state`、`gateway_group_id`、`instance_id`    | 按状态统计当前 NGINX 连接数。                                                            |
| `apisix_http_requests_total`            | Gauge | `gateway_group_id`、`instance_id`             | 网关启动后处理的请求数。尽管名称以 `_total` 结尾，已发布的实现仍将该指标族导出为 Gauge。 |
| `apisix_etcd_reachable`                 | Gauge | `gateway_group_id`、`instance_id`             | 网关能否连接 DP Manager：`1` 表示可连接，`0` 表示不可连接。                              |
| `apisix_prometheus_disable`             | Gauge | `gateway_group_id`、`instance_id`             | 是否已禁用流量指标采集：`1` 表示已禁用，`0` 表示已启用。                                 |
| `apisix_node_info`                      | Gauge | `hostname`、`gateway_group_id`、`instance_id` | 标识上报指标的网关实例。                                                                 |
| `apisix_etcd_modify_indexes`            | Gauge | `key`、`gateway_group_id`、`instance_id`      | 按资源键记录配置修订版本。                                                               |
| `apisix_shared_dict_capacity_bytes`     | Gauge | `name`、`gateway_group_id`、`instance_id`     | 各 NGINX 共享字典的配置容量。                                                            |
| `apisix_shared_dict_free_space_bytes`   | Gauge | `name`、`gateway_group_id`、`instance_id`     | 各 NGINX 共享字典的可用空间。                                                            |

使用 `instance_id` 对两种采集路径中的数据面实例进行分组。该标签属于导出的序列；Prometheus 只会在抓取目标时添加自己的 `instance` 标签。

## HTTP 流量指标[​](#http-流量指标 "HTTP 流量指标的直接链接")

`prometheus` 插件处理请求时会记录以下指标族。通常使用全局规则为所有 HTTP 流量启用该插件。

| 指标                  | 类型      | 内置标签                                                                                                                                                                                                                                                                            |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apisix_http_status`  | Counter   | `code`、`route`、`route_id`、`matched_uri`、`matched_host`、`service`、`service_id`、`consumer`、`node`、`gateway_group_id`、`instance_id`、`portal_id`、`api_product_id`、`request_type`、`request_llm_model`、`llm_model`、`mcp_request_type`、`mcp_tool_name`、`response_source` |
| `apisix_http_latency` | Histogram | `type`、`route`、`route_id`、`service`、`service_id`、`consumer`、`node`、`gateway_group_id`、`instance_id`、`portal_id`、`api_product_id`、`request_type`、`request_llm_model`、`llm_model`、`mcp_request_type`、`mcp_tool_name`                                                   |
| `apisix_bandwidth`    | Counter   | `type`、`route`、`route_id`、`service`、`service_id`、`consumer`、`node`、`gateway_group_id`、`instance_id`、`portal_id`、`api_product_id`、`request_type`、`request_llm_model`、`llm_model`、`mcp_request_type`、`mcp_tool_name`                                                   |

该表展示最新补丁中的标签结构。在 3.10.0 版本中，`apisix_http_status`、`apisix_http_latency` 和 `apisix_bandwidth` 不包含 `mcp_request_type` 或 `mcp_tool_name`；这些标签从 3.10.1 及更高版本开始提供。

`apisix_http_latency` 以毫秒为单位记录数据，其 `type` 标签可以是 `request`、`upstream` 或 `apisix`。`apisix_bandwidth` 的 `type` 标签可以是 `ingress` 或 `egress`。

如果 ADC 同步删除了 `prometheus` 全局规则，且没有路由级 `prometheus` 配置替代它，节点指标仍可能存在，但受影响路由上的 HTTP 流量指标将停止更新。请在 ADC 管理的声明式配置中包含该全局规则。

## AI 指标[​](#ai-metrics "AI 指标的直接链接")

大多数 AI 指标族会在相关 AI 插件处理请求且 `prometheus` 插件也在该请求上运行时生成，并使用与 HTTP 流量指标相同的资源上下文。如果移除 `prometheus` 全局规则且未在受影响的路由上启用该插件，LLM 延迟、Token、分布和 AI 缓存指标族将停止更新。`apisix_llm_active_connections` 由 `ai-proxy` 直接更新，不依赖该全局规则。

| 指标                                | 类型      | 附加标签或行为                                                                                                                                                                                    |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apisix_llm_latency`                | Histogram | 在 3.10.0 版本中，该指标族没有 `type` 标签，并记录 `llm_time_to_first_token`；对于流式流量，该值为 TTFT。3.10.1 及更高版本将完整响应延迟记录为 `type="total"`，将流式 TTFT 记录为 `type="ttft"`。 |
| `apisix_llm_prompt_tokens`          | Counter   | 统计提供商报告的提示 Token 数。                                                                                                                                                                   |
| `apisix_llm_completion_tokens`      | Counter   | 统计提供商报告的补全 Token 数。                                                                                                                                                                   |
| `apisix_llm_active_connections`     | Gauge     | 跟踪活跃的 AI 请求。使用 `ai-proxy-multi` 回退重试时，失败实例的序列可能会一直高于实际活跃数量，直到配置的过期机制移除该序列或指标存储被重置。                                                    |
| `apisix_llm_prompt_tokens_dist`     | Histogram | 每个请求的提示 Token 数分布。从 3.10.1 及更高版本开始提供。                                                                                                                                       |
| `apisix_llm_completion_tokens_dist` | Histogram | 每个请求的补全 Token 数分布。从 3.10.1 及更高版本开始提供。                                                                                                                                       |
| `apisix_ai_cache_hits_total`        | Counter   | 添加 `layer` 标签以标识提供响应的缓存层。从 3.10.3 及更高版本开始提供。                                                                                                                           |
| `apisix_ai_cache_misses_total`      | Counter   | 统计缓存未命中次数。从 3.10.3 及更高版本开始提供。                                                                                                                                                |
| `apisix_ai_cache_bypasses_total`    | Counter   | 统计绕过缓存的请求数。从 3.10.3 及更高版本开始提供。                                                                                                                                              |
| `apisix_ai_cache_embedding_latency` | Histogram | 以毫秒为单位记录嵌入调用延迟。从 3.10.3 及更高版本开始提供。                                                                                                                                      |

这些指标族的内置资源标签包括 `route`、`route_id`、`service`、`service_id`、`consumer`、`node`、`gateway_group_id`、`instance_id`、`portal_id`、`api_product_id`、`request_type`、`request_llm_model` 和 `llm_model`。Token、活跃连接和缓存指标族还包含 `matched_uri` 和 `matched_host`；`apisix_llm_latency` 不包含这两个标签。

## 流式代理指标[​](#流式代理指标 "流式代理指标的直接链接")

在需要测量会话的每条流式代理路由上启用 `prometheus` 插件。API7 控制面会将流式代理插件列表下发至网关，因此托管部署无需在本地编辑 `stream_plugins`。`apisix_stream_connection_total` 和 `apisix_stream_status` 由插件的流式代理日志阶段记录。`apisix_stream_active_connections` 和 `apisix_stream_bandwidth` 还要求网关运行时包含 stream-metrics 模块。

| 指标                               | 类型    | 内置标签                                                                                  | 可用版本          |
| ---------------------------------- | ------- | ----------------------------------------------------------------------------------------- | ----------------- |
| `apisix_stream_connection_total`   | Counter | `route`、`service`、`service_id`                                                          | 所有 3.10.x 版本  |
| `apisix_stream_active_connections` | Gauge   | `listen_addr`、`service`、`service_id`、`gateway_group_id`、`instance_id`                 | 3.10.6 及更高版本 |
| `apisix_stream_status`             | Counter | `code`、`listen_addr`、`service`、`service_id`、`node`、`gateway_group_id`、`instance_id` | 3.10.6 及更高版本 |
| `apisix_stream_bandwidth`          | Counter | `listen_addr`、`service`、`service_id`、`type`、`side`、`gateway_group_id`、`instance_id` | 3.10.6 及更高版本 |

`apisix_stream_connection_total` 按匹配的流式代理路由区分。其他流式代理指标族按监听地址区分，因为它们可能在路由匹配前或直接由 NGINX stream 子系统更新。

上表展示最新补丁版本的标签结构。四个指标族的 `service` 和 `service_id` 标签从 3.10.9 起提供。匹配的流式代理路由引用服务时，`service_id` 包含服务 ID。默认情况下，`service` 也包含该 ID；设置 `prefer_name: true` 后，`service` 包含服务名称。如果会话未匹配到引用服务的路由，这两个标签均为空。

这些固定标签会按服务拆分流式代理时间序列。对于三个按监听地址区分的指标族，每种监听地址与服务的组合都会产生独立序列。规划 [Prometheus 共享内存区容量](https://docs.apiseven.com/api7-gateway/configure-and-manage/shared-dict-sizing.md#prometheus-metrics)时，请计入这些组合。流式代理指标的 `service` 和 `service_id` 标签无法通过 `prometheus` 插件的 `disabled_labels` 元数据移除。

## 支撑子系统的指标[​](#支撑子系统的指标 "支撑子系统的指标的直接链接")

部分指标在主导出器之外注册，因此不会继承常见的数据面标签：

| 指标                               | 类型    | 内置标签                          | 出现场景                                 |
| ---------------------------------- | ------- | --------------------------------- | ---------------------------------------- |
| `apisix_nginx_metric_errors_total` | Counter | 无                                | 每个指标注册表都会导出内部库错误计数器。 |
| `apisix_batch_process_entries`     | Gauge   | `name`、`route_id`、`server_addr` | 日志记录插件或其他插件使用批处理器。     |

网关会初始化两个使用相同前缀的指标注册表，因此在当前发布版本中直接抓取时，`apisix_nginx_metric_errors_total` 会出现两次。Prometheus 只会丢弃重复样本，其余指标族仍会导入。Prometheus 2.52.0 及更高版本会记录警告；更早版本会静默忽略重复序列。严格的文本格式检查（例如 `promtool check metrics`）会拒绝整个负载。

已配置的 xRPC 协议可以注册其他协议专用指标族。对于特定部署中启用的可选插件和模块，请以实时端点为准。

## 相关页面[​](#相关页面 "相关页面的直接链接")

* [监控指标](https://docs.apiseven.com/api7-gateway/observability/metrics.md)
* [使用现有 Prometheus](https://docs.apiseven.com/api7-gateway/observability/external-prometheus.md)
* [`prometheus` 插件参考](https://docs.apiseven.com/hub/prometheus.md)
