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 installed patch, 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.
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
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
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
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 | All 3.10.x versions |
apisix_stream_active_connections | Gauge | listen_addr, gateway_group_id, instance_id | Version 3.10.6 and later |
apisix_stream_status | Counter | code, listen_addr, node, gateway_group_id, instance_id | Version 3.10.6 and later |
apisix_stream_bandwidth | Counter | listen_addr, 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.
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 apisix_nginx_metric_errors_total appears twice in a direct scrape in this release line. Prometheus rejects the entire scrape, marks the target as failed, and ingests none of the gateway metrics. Use the DP Manager remote-write path until the duplicate exposition is fixed.
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.