a6-plugin-prometheus

name: a6-plugin-prometheus description: >- Skill for configuring the Apache APISIX prometheus plugin via the a6 CLI. Covers enabling Prometheus metrics export on routes and globally, exposed metrics (HTTP status, latency, bandwidth, upstream health, LLM tokens), custom labels, histogram buckets, and Grafana dashboard integration. version: "1.0.0" author: Apache APISIX Contributors license: Apache-2.0 metadata: category: plugin apisix_version: ">=3.0.0" plugin_name: prometheus a6_commands: - a6 route create - a6 route update - a6 config sync

a6-plugin-prometheus

Overview

The prometheus plugin exposes APISIX metrics in Prometheus text format. It tracks HTTP status codes, request latency, bandwidth, upstream health, etcd status, and (since v3.15) LLM token usage. Prometheus scrapes the metrics endpoint; Grafana visualizes them.

When to Use

• Monitor request rates, error rates, and latency per route/service/consumer
• Track upstream health check status
• Observe LLM token consumption and time-to-first-token
• Build dashboards and alerts with Prometheus + Grafana

Plugin Configuration Reference (Route/Service/Global Rule)

The plugin has minimal per-route config. Most configuration is global via plugin_attr in APISIX config.yaml.

Metrics Exported

Core Metrics

LLM/AI Metrics (v3.15+)

Latency Types

• request: Total time from first byte read to last byte sent
• upstream: Time waiting for upstream response
• apisix: request - upstream (APISIX processing overhead)

Step-by-Step: Enable Prometheus Metrics

1. Enable on a route

a6 route create -f - <<'EOF'
{
  "id": "my-api",
  "uri": "/api/*",
  "plugins": {
    "prometheus": {
      "prefer_name": true
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

2. Enable globally (all routes)

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/global_rules" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "id": "prometheus-global",
    "plugins": {
      "prometheus": {}
    }
  }'

3. Access metrics

Default endpoint: http://127.0.0.1:9091/apisix/prometheus/metrics

4. Configure Prometheus scrape

# prometheus.yml
scrape_configs:
  - job_name: apisix
    scrape_interval: 15s
    static_configs:
      - targets: ['127.0.0.1:9091']

5. Import Grafana dashboard

Import dashboard ID 11719 from grafana.com for a pre-built APISIX monitoring dashboard.

Common Patterns

Custom metric prefix and export port

Configure in APISIX config.yaml (not via Admin API):

plugin_attr:
  prometheus:
    export_uri: /apisix/prometheus/metrics
    metric_prefix: apisix_
    enable_export_server: true
    export_addr:
      ip: 0.0.0.0
      port: 9091

Extra labels on metrics

plugin_attr:
  prometheus:
    metrics:
      http_status:
        extra_labels:
          - upstream_addr: $upstream_addr
      http_latency:
        extra_labels:
          - upstream_addr: $upstream_addr
      bandwidth:
        extra_labels:
          - upstream_addr: $upstream_addr

Custom histogram buckets

plugin_attr:
  prometheus:
    default_buckets:
      - 10
      - 50
      - 100
      - 200
      - 500
      - 1000
      - 5000
      - 30000

Config Sync Example

version: "1"
global_rules:
  - id: prometheus-global
    plugins:
      prometheus:
        prefer_name: true
routes:
  - id: my-api
    uri: /api/*
    upstream_id: my-upstream

Troubleshooting