Skip to main content
API7.ai Logo
Version: 3.9.x

Monitor Metrics

API7 Gateway provides two ways to monitor traffic:

  • A built-in Monitoring page in the Dashboard for at-a-glance status checks with no extra infrastructure.
  • A Prometheus-format endpoint on the data plane for inspecting raw gateway metrics.

Prerequisites​

Approach 1: Built-in Monitoring Page​

The Dashboard's Monitoring section displays the most critical real-time metrics:

MetricDescription
QPSQueries per second, indicating the current load.
LatencyRequest processing time (average, p90, p99).
Error RateThe percentage of requests returning 4xx or 5xx status codes.
ThroughputInbound and outbound data volume.

To access this page, sign in to the Dashboard and navigate to Monitoring.

Approach 2: Prometheus Scrape Endpoint​

Enable the prometheus plugin as a global rule to expose raw metrics at http://<data-plane>:9091/apisix/prometheus/metrics. The current release line has a direct-scrape limitation described below; use DP Manager remote write when sending the metrics to Prometheus.

Step 1: Enable the Prometheus Plugin Globally​

curl -k "https://localhost:7443/apisix/admin/global_rules/prometheus?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "prometheus": {}
    }
  }'

Step 2: Verify the Endpoint​

Send a request through any route to generate metrics, then scrape the Prometheus endpoint on the data plane:

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

You should see Prometheus-formatted metrics including counters, gauges, and histograms emitted by the gateway.

Direct Prometheus scrape limitation

This release emits apisix_nginx_metric_errors_total twice because the gateway uses two same-prefix metric registries. Prometheus rejects the entire scrape, marks the target as failed, and ingests none of the gateway metrics. No publicly released fixed version is currently available. Use the DP Manager remote-write path for Prometheus ingestion. Direct scraping requires a later release that fixes the duplicate exposition or a build that API7 Support confirms contains the fix. The endpoint remains useful for manual inspection or a collector that is verified to tolerate the duplicate family.

The metrics listener binds to 127.0.0.1 by default. Publishing port 9091 does not make that loopback-only listener reachable from outside a container or pod.

For a gateway configured with config.yaml, set the listener to an address that your monitoring network can reach:

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

Restart the gateway, then publish or expose the port.

For a gateway deployed with the API7 Gateway Helm chart and Prometheus Operator, first verify that the gateway includes a fix for the duplicate exposition. After verification, enable the chart's ServiceMonitor integration. This binds the listener to 0.0.0.0, exposes port 9091 through the gateway Service, and creates a ServiceMonitor:

values.yaml
serviceMonitor:
  enabled: true

This option requires the ServiceMonitor custom resource definition. On the current release line, it creates the failing Prometheus scrape described above. For manual inspection or another verified-compatible collector, configure pluginAttrs.prometheus.export_addr. You must also expose port 9091 with a Kubernetes Service or request the pod IPs directly. Changing pluginAttrs alone does not add a Service port.

If you do not want to expose the listener, use the DP Manager remote-write path.

caution

The metrics endpoint is unauthenticated. Restrict it to the monitoring network instead of exposing it with proxy traffic.

Step 3: Choose a Collection Path​

For Prometheus, use the DP Manager remote-write path. It does not require exposing port 9091 outside the data plane.

If you use another collector that is verified to accept the duplicate family, configure it to request /apisix/prometheus/metrics from <data-plane-host>:9091.

Key Metrics​

When building dashboards or alerts, focus on these metrics emitted by the prometheus plugin:

  • apisix_http_status — counter of responses by status code (label code).
  • apisix_http_latency — histogram of request latency (label type distinguishes request, upstream, and apisix).
  • apisix_bandwidth — counter of bytes sent and received (label type).
  • apisix_nginx_http_current_connections — gauge of active connections (label state).

For the data-plane metric families and their built-in labels, see Data Plane Metrics Reference. For plugin configuration and label tuning, see prometheus.

Additional Resources​