Prometheus

prometheus 插件提供了将 APISIX 与 Prometheus 集成的能力。

启用插件后，APISIX 将开始收集相关指标，例如 API 请求和延迟，并以 基于文本的展示格式 将它们导出到 Prometheus。然后，你可以在 Prometheus 中创建事件监控和警报，以监控 API 网关和 API 的健康状况。

指标​

Prometheus 中有不同类型的指标。要了解它们的区别，请参阅 指标类型。

默认情况下，prometheus 插件会导出以下指标。有关示例，请参阅 获取 APISIX 指标。请注意，如果没有数据，某些指标（如 apisix_batch_process_entries）可能不会立即显示。

标签​

标签 是指标的属性，用于区分指标。

例如，apisix_http_status 指标可以用 route 信息进行标记，以识别 HTTP 状态源自哪个路由。

以下是非详尽的 APISIX 指标及其描述的标签列表。

apisix_http_status 的标签​

以下标签用于区分 apisix_http_status 指标。

apisix_bandwidth 的标签​

以下标签用于区分 apisix_bandwidth 指标。

apisix_http_latency 的标签​

以下标签用于区分 apisix_http_latency 指标。

延迟类型​

apisix_http_latency 可以用以下三种类型之一进行标记：

• request 表示从客户端读取第一个字节到向客户端发送最后一个字节后的日志写入之间经过的时间。

• upstream 表示等待上游服务响应所经过的时间。

• apisix 表示 request 延迟与 upstream 延迟之间的差值。

换句话说，APISIX 延迟不仅仅归因于 Lua 处理。它应该理解如下：

APISIX 延迟
  = 下游请求时间 - 上游响应时间
  = 下游流量延迟 + NGINX 延迟

apisix_upstream_status 的标签​

以下标签用于区分 apisix_upstream_status 指标。

apisix_llm_latency 的标签​

以下标签用于区分 apisix_llm_latency 指标。

其他 LLM 指标的标签​

以下标签用于区分 apisix_llm_prompt_tokens、apisix_llm_completion_tokens 和 apisix_llm_active_connections 指标。

示例​

下面的示例展示了如何在不同场景下使用 prometheus 插件。

获取 APISIX 指标​

以下示例展示了如何从 APISIX 获取指标。

默认的 Prometheus 指标端点和其他 Prometheus 相关配置可以在 静态配置 中找到。如果你想自定义这些配置，请参阅 配置文件。

如果你在容器化环境中部署 APISIX，并希望从外部访问 Prometheus 指标端点，请按如下方式更新配置文件并 重新加载 APISIX：

plugin_attr:
  prometheus:
    export_addr:
      ip: 0.0.0.0 

向 APISIX Prometheus 指标端点发送请求：

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

你应该看到类似于以下的输出：

# HELP apisix_bandwidth Total bandwidth in bytes consumed per service in Apisix
# TYPE apisix_bandwidth counter
apisix_bandwidth{type="egress",route="",service="",consumer="",node=""} 8417
apisix_bandwidth{type="egress",route="1",service="",consumer="",node="127.0.0.1"} 1420
apisix_bandwidth{type="egress",route="2",service="",consumer="",node="127.0.0.1"} 1420
apisix_bandwidth{type="ingress",route="",service="",consumer="",node=""} 189
apisix_bandwidth{type="ingress",route="1",service="",consumer="",node="127.0.0.1"} 332
apisix_bandwidth{type="ingress",route="2",service="",consumer="",node="127.0.0.1"} 332
# HELP apisix_etcd_modify_indexes Etcd modify index for APISIX keys
# TYPE apisix_etcd_modify_indexes gauge
apisix_etcd_modify_indexes{key="consumers"} 0
apisix_etcd_modify_indexes{key="global_rules"} 0
...

在公共 API 端点上暴露 APISIX 指标​

以下示例展示了如何禁用默认在端口 9091 上暴露端点的 Prometheus 导出服务器，并在 APISIX 用于监听其他客户端请求的端口 9080 上的新公共 API 端点上暴露 APISIX Prometheus 指标。

在配置文件中禁用 Prometheus 导出服务器，并 重新加载 APISIX 以使更改生效：

plugin_attr:
  prometheus:
    enable_export_server: false

接下来，创建一个带有 public-api 插件的路由，并为 APISIX 指标暴露一个公共 API 端点：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-metrics",
    "uri": "/apisix/prometheus/metrics",
    "plugins": {
      "public-api": {}
    }
  }'

向新的指标端点发送请求以进行验证：

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

你应该看到类似于以下的输出：

# HELP apisix_http_requests_total The total number of client requests since APISIX started
# TYPE apisix_http_requests_total gauge
apisix_http_requests_total 1
# HELP apisix_nginx_http_current_connections Number of HTTP connections
# TYPE apisix_nginx_http_current_connections gauge
apisix_nginx_http_current_connections{state="accepted"} 1
apisix_nginx_http_current_connections{state="active"} 1
apisix_nginx_http_current_connections{state="handled"} 1
apisix_nginx_http_current_connections{state="reading"} 0
apisix_nginx_http_current_connections{state="waiting"} 0
apisix_nginx_http_current_connections{state="writing"} 1
...

将 APISIX 与 Prometheus 和 Grafana 集成​

要了解如何使用 Prometheus 收集 APISIX 指标并在 Grafana 中将其可视化，请参阅 操作指南。

监控上游健康状态​

以下示例展示了如何监控上游节点的健康状态。

创建一个带有 prometheus 插件的路由并配置上游主动健康检查：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-route",
    "uri": "/get",
    "plugins": {
      "prometheus": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1,
        "127.0.0.1:20001": 1
      },
      "checks": {
        "active": {
          "timeout": 5,
          "http_path": "/status",
          "healthy": {
            "interval": 2,
            "successes": 1
          },
          "unhealthy": {
            "interval": 1,
            "http_failures": 2
          }
        },
        "passive": {
          "healthy": {
            "http_statuses": [200, 201],
            "successes": 3
          },
          "unhealthy": {
            "http_statuses": [500],
            "http_failures": 3,
            "tcp_failures": 3
          }
        }
      }
    }
  }'

向 APISIX Prometheus 指标端点发送请求：

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

你应该看到类似于以下的输出：

# HELP apisix_upstream_status upstream status from health check
# TYPE apisix_upstream_status gauge
apisix_upstream_status{name="/apisix/routes/1",ip="54.237.103.220",port="80"} 1
apisix_upstream_status{name="/apisix/routes/1",ip="127.0.0.1",port="20001"} 0

这表明上游节点 httpbin.org:80 是健康的，而上游节点 127.0.0.1:20001 是不健康的。

要了解有关如何配置主动和被动健康检查的更多信息，请参阅 健康检查。

为指标添加额外标签​

以下示例展示了如何向指标添加额外标签并在标签值中使用 内置变量。

目前，只有以下指标支持额外标签：

• apisix_http_status
• apisix_http_latency
• apisix_bandwidth

在 配置文件 中包含以下配置以为指标添加标签，并 重新加载 APISIX 以使更改生效：

plugin_attr:
  prometheus:                                # Plugin: prometheus
    metrics:                                 # Create extra labels from built-in variables.
      http_status:
        extra_labels:                        # Set the extra labels for http_status metrics.
          - upstream_addr: $upstream_addr    # Add an extra upstream_addr label with value being the NGINX variable $upstream_addr.
          - route_name: $route_name          # Add an extra route_name label with value being the APISIX variable $route_name.

请注意，如果你在标签值中定义了一个变量，但它不对应任何现有的 内置变量，则标签值将默认为空字符串。

创建一个带有 prometheus 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-route",
    "uri": "/get",
    "name": "extra-label",
    "plugins": {
      "prometheus": {}
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求到该路由以进行验证：

curl -i "http://127.0.0.1:9080/get"

你应该看到 HTTP/1.1 200 OK 响应。

向 APISIX Prometheus 指标端点发送请求：

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

你应该看到类似于以下的输出：

# HELP apisix_http_status HTTP status codes per service in APISIX
# TYPE apisix_http_status counter
apisix_http_status{code="200",route="1",matched_uri="/get",matched_host="",service="",consumer="",node="54.237.103.220",upstream_addr="54.237.103.220:80",route_name="extra-label"} 1

使用 Prometheus 监控 TCP/UDP 流量​

以下示例展示了如何在 APISIX 中收集 TCP/UDP 流量指标。

在 配置文件 中包含以下配置以启用流代理并为流代理启用 prometheus 插件。重新加载 APISIX 以使更改生效：

apisix:
  proxy_mode: http&stream   # Enable both L4 & L7 proxies
  stream_proxy:             # Configure L4 proxy
    tcp:
      - 9100                # Set TCP proxy listening port
    udp:
      - 9200                # Set UDP proxy listening port

stream_plugins:
  - prometheus              # Enable prometheus for stream proxy

创建一个带有 prometheus 插件的 流路由：

curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "prometheus-route",
    "plugins": {
      "prometheus":{}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求到该流路由以进行验证：

curl -i "http://127.0.0.1:9100"

你应该看到 HTTP/1.1 200 OK 响应。

向 APISIX Prometheus 指标端点发送请求：

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

你应该看到类似于以下的输出：

# HELP apisix_stream_connection_total Total number of connections handled per stream route in APISIX
# TYPE apisix_stream_connection_total counter
apisix_stream_connection_total{route="1"} 1