# Data Plane Metrics Reference

API7 Gateway exports node, HTTP traffic, AI, and stream metrics from the data-plane Prometheus endpoint. The available series depend on the gateway version, configured plugins, and traffic: node metrics describe the running gateway, while request metrics appear after the corresponding feature processes traffic.

Metric names below use the default `apisix_` prefix. You can change the prefix with `plugin_attr.prometheus.metric_prefix` and add or remove selected request labels through the [`prometheus` plugin configuration](https://docs.api7.ai/hub/prometheus.md).

## Node Metrics[​](#node-metrics "Direct link to Node Metrics")

These metrics describe the gateway process and its configuration connection. They do not require the `prometheus` plugin to run on a route.

| Metric                                  | Type  | Built-in labels                               | Description                                                                                                                          |
| --------------------------------------- | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `apisix_nginx_http_current_connections` | Gauge | `state`, `gateway_group_id`, `instance_id`    | Current NGINX connection count by state.                                                                                             |
| `apisix_http_requests_total`            | Gauge | `gateway_group_id`, `instance_id`             | Requests handled since the gateway started. Despite the `_total` suffix, the released implementation exports this family as a gauge. |
| `apisix_etcd_reachable`                 | Gauge | `gateway_group_id`, `instance_id`             | Whether the gateway can reach DP Manager: `1` for reachable and `0` for unreachable.                                                 |
| `apisix_prometheus_disable`             | Gauge | `gateway_group_id`, `instance_id`             | Whether traffic-metric collection is disabled: `1` for disabled and `0` for enabled.                                                 |
| `apisix_node_info`                      | Gauge | `hostname`, `gateway_group_id`, `instance_id` | Identifies the reporting gateway instance.                                                                                           |
| `apisix_etcd_modify_indexes`            | Gauge | `key`, `gateway_group_id`, `instance_id`      | Configuration revision by resource key.                                                                                              |
| `apisix_shared_dict_capacity_bytes`     | Gauge | `name`, `gateway_group_id`, `instance_id`     | Configured capacity of each NGINX shared dictionary.                                                                                 |
| `apisix_shared_dict_free_space_bytes`   | Gauge | `name`, `gateway_group_id`, `instance_id`     | Free space in each NGINX shared dictionary.                                                                                          |

Use `instance_id` to group data-plane instances across both collection paths. It is part of the exported series, while Prometheus adds its own `instance` label only when scraping a target.

## HTTP Traffic Metrics[​](#http-traffic-metrics "Direct link to HTTP Traffic Metrics")

The `prometheus` plugin records these families when it runs on a request. A global rule is the usual way to enable it for all HTTP traffic.

| Metric                | Type      | Built-in labels                                                                                                                                                                                                                                                                     |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`                                                   |

The table shows the label shape in the latest patch. In version 3.10.0, `apisix_http_status`, `apisix_http_latency`, and `apisix_bandwidth` do not include `mcp_request_type` or `mcp_tool_name`; these labels are available in version 3.10.1 and later.

`apisix_http_latency` records milliseconds. Its `type` label is `request`, `upstream`, or `apisix`. The `type` label on `apisix_bandwidth` is `ingress` or `egress`.

If an ADC synchronization deletes the `prometheus` global rule and no route-level `prometheus` configuration replaces it, node metrics can remain present while HTTP traffic metrics stop updating on the affected routes. Include the global rule in the declarative configuration that ADC manages.

## AI Metrics[​](#ai-metrics "Direct link to AI Metrics")

Most AI metric families are populated when the relevant AI plugin handles a request and the `prometheus` plugin also runs on that request. They use the same resource context as HTTP traffic metrics. Removing the `prometheus` global rule without enabling the plugin on the affected routes stops the LLM latency, token, distribution, and AI-cache families. `apisix_llm_active_connections` is updated directly by `ai-proxy` and does not depend on that global rule.

| Metric                              | Type      | Additional label or behavior                                                                                                                                                                                                                      |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apisix_llm_latency`                | Histogram | In version 3.10.0, this family has no `type` label and records `llm_time_to_first_token`; for streaming traffic, that value is TTFT. Version 3.10.1 and later record full response latency as `type="total"` and streaming TTFT as `type="ttft"`. |
| `apisix_llm_prompt_tokens`          | Counter   | Counts prompt tokens reported by the provider.                                                                                                                                                                                                    |
| `apisix_llm_completion_tokens`      | Counter   | Counts completion tokens reported by the provider.                                                                                                                                                                                                |
| `apisix_llm_active_connections`     | Gauge     | Tracks active AI requests. With `ai-proxy-multi` fallback retries, a failed-instance series can remain above the true active count until a configured expiry removes it or the metric storage is reset.                                           |
| `apisix_llm_prompt_tokens_dist`     | Histogram | Distribution of prompt tokens per request. Available in version 3.10.1 and later.                                                                                                                                                                 |
| `apisix_llm_completion_tokens_dist` | Histogram | Distribution of completion tokens per request. Available in version 3.10.1 and later.                                                                                                                                                             |
| `apisix_ai_cache_hits_total`        | Counter   | Adds `layer` to identify the cache layer that served the response. Available in version 3.10.3 and later.                                                                                                                                         |
| `apisix_ai_cache_misses_total`      | Counter   | Counts cache misses. Available in version 3.10.3 and later.                                                                                                                                                                                       |
| `apisix_ai_cache_bypasses_total`    | Counter   | Counts requests that bypassed the cache. Available in version 3.10.3 and later.                                                                                                                                                                   |
| `apisix_ai_cache_embedding_latency` | Histogram | Embedding-call latency in milliseconds. Available in version 3.10.3 and later.                                                                                                                                                                    |

The built-in resource labels for these families include `route`, `route_id`, `service`, `service_id`, `consumer`, `node`, `gateway_group_id`, `instance_id`, `portal_id`, `api_product_id`, `request_type`, `request_llm_model`, and `llm_model`. Token, active-connection, and cache families also include `matched_uri` and `matched_host`; `apisix_llm_latency` does not.

## Stream Metrics[​](#stream-metrics "Direct link to Stream Metrics")

Enable the `prometheus` plugin on each stream route whose sessions you want to measure. API7 Control Plane delivers the stream plugin list to the gateway, so a managed deployment does not need to edit `stream_plugins` locally. `apisix_stream_connection_total` and `apisix_stream_status` are recorded by the plugin's stream log phase. `apisix_stream_active_connections` and `apisix_stream_bandwidth` additionally require the stream-metrics module in the gateway runtime.

| Metric                             | Type    | Built-in labels                                                                           | Availability             |
| ---------------------------------- | ------- | ----------------------------------------------------------------------------------------- | ------------------------ |
| `apisix_stream_connection_total`   | Counter | `route`, `service`, `service_id`                                                          | All 3.10.x versions      |
| `apisix_stream_active_connections` | Gauge   | `listen_addr`, `service`, `service_id`, `gateway_group_id`, `instance_id`                 | Version 3.10.6 and later |
| `apisix_stream_status`             | Counter | `code`, `listen_addr`, `service`, `service_id`, `node`, `gateway_group_id`, `instance_id` | Version 3.10.6 and later |
| `apisix_stream_bandwidth`          | Counter | `listen_addr`, `service`, `service_id`, `type`, `side`, `gateway_group_id`, `instance_id` | Version 3.10.6 and later |

`apisix_stream_connection_total` is keyed by the matched stream route. The other stream families are keyed by listening address because they can be updated before a route is matched or directly by the NGINX stream subsystem.

The table shows the label shape in the latest patch. The `service` and `service_id` labels are available on all four families in version 3.10.9 and later. When a matched stream route references a service, `service_id` contains its ID. By default, `service` contains the same ID; with `prefer_name: true`, it contains the service name. Both labels are empty when a session does not reach a route with a service.

These fixed labels split stream series by service. For the three listener-keyed families, each listener and service combination creates separate series. Include those combinations when [sizing the Prometheus shared-memory zone](https://docs.api7.ai/api7-gateway/configure-and-manage/shared-dict-sizing.md#prometheus-metrics). The stream `service` and `service_id` labels cannot be removed with the `prometheus` plugin's `disabled_labels` metadata.

## Metrics from Supporting Subsystems[​](#metrics-from-supporting-subsystems "Direct link to Metrics from Supporting Subsystems")

Some metrics are registered outside the main exporter and therefore do not inherit the common data-plane labels:

| Metric                             | Type    | Built-in labels                   | Appears when                                                      |
| ---------------------------------- | ------- | --------------------------------- | ----------------------------------------------------------------- |
| `apisix_nginx_metric_errors_total` | Counter | None                              | Each metrics registry exports the internal library error counter. |
| `apisix_batch_process_entries`     | Gauge   | `name`, `route_id`, `server_addr` | A logger or another plugin uses the batch processor.              |

The gateway initializes two same-prefix metrics registries, so currently released versions expose `apisix_nginx_metric_errors_total` twice in a direct scrape. Prometheus drops the repeated sample and ingests all metric families. Prometheus 2.52.0 and later logs a warning; earlier versions ignore the repeated series silently. Strict text-format checks, such as `promtool check metrics`, reject the whole payload.

Configured xRPC protocols can register additional protocol-specific families. Treat the live endpoint as authoritative for optional plugins and modules enabled in a particular deployment.

## Related Pages[​](#related-pages "Direct link to Related Pages")

* [Monitor Metrics](https://docs.api7.ai/api7-gateway/observability/metrics.md)
* [Use an Existing Prometheus](https://docs.api7.ai/api7-gateway/observability/external-prometheus.md)
* [`prometheus` plugin reference](https://docs.api7.ai/hub/prometheus.md)
