Prometheus | Apache APISIX 与 API7 网关插件文档

静态配置

默认情况下，默认配置中已预先配置 prometheus。

需要更新的文件取决于网关的部署方式：

Host or Docker
Kubernetes (Helm)

对于主机或 Docker 部署，请配置以下设置：

config.yaml
plugin_attr:
  prometheus:                               # prometheus 插件属性
    export_uri: /apisix/prometheus/metrics  # 设置 Prometheus 指标端点的 URI。
    metric_prefix: apisix_                  # 设置 APISIX 生成的 Prometheus 指标前缀。
    enable_export_server: true              # 启用 Prometheus 导出服务器。
    export_addr:                            # 设置 Prometheus 导出服务器的地址。
      ip: 127.0.0.1                         # 设置 IP 地址。
      port: 9091                            # 设置端口。
    refresh_interval: 15                    # 仅在 APISIX 中可用。
                                            # 设置刷新缓存指标数据的时间间隔（秒）。
    fetch_metric_timeout: 5                 # 仅在 API7 企业版中可用。
                                            # 获取指标的超时时间（秒）。超时后，API 仅返回基本指标，
                                            # 包括 nginx_http_current_connections、http_requests_total、
                                            # etcd_reachable、prometheus_disable、node_info、etcd_modify_indexes、
                                            # shared_dict_capacity_bytes 和 shared_dict_free_space_bytes。
    allow_degradation: false                # 仅在 API7 企业版中可用。
                                            # 如果为 true，则允许在共享内存不足时降级。
    degradation_pause_steps: [ 60 ]         # 仅在 API7 企业版中可用。
                                            # 插件处于降级状态并回收其占用的共享内存时，
                                            # 跳过插件执行的时间（秒）。
    # metrics:                              # 为指标创建额外标签。
    #  http_status:                         # 这些指标将以 `apisix_` 为前缀。
    #    extra_labels:                      # 设置 http_status 指标的额外标签。
    #      - upstream_addr: $upstream_addr
    #      - status: $upstream_status
    #    expire: 0                          # 指标的过期时间（秒）。
                                            # 0 表示指标不会过期。
    #  http_latency:
    #    extra_labels:                      # 设置 http_latency 指标的额外标签。
    #      - upstream_addr: $upstream_addr
    #    expire: 0                          # 指标的过期时间（秒）。
                                            # 0 表示指标不会过期。
    #  bandwidth:
    #    extra_labels:                      # 设置 bandwidth 指标的额外标签。
    #      - upstream_addr: $upstream_addr
    #    expire: 0                          # 指标的过期时间（秒）。
                                            # 0 表示指标不会过期。
    # default_buckets:                      # 设置 `http_latency` 指标直方图的默认桶。
    #   - 10
    #   - 50
    #   - 100
    #   - 200
    #   - 500
    #   - 1000
    #   - 2000
    #   - 5000
    #   - 10000
    #   - 30000
    #   - 60000
    #   - 500
    # llm_latency_buckets:          # 自 API7 企业版 3.9.7 起可用。
    #                               # 自 3.9.14 起，这些桶同时适用于 `type=total` 和 `type=ttft`，单位为毫秒。
    #   - 100
    #   - 500
    #   - 1000
    #   - 5000
    # llm_prompt_tokens_buckets:    # 自 API7 企业版 3.9.14 起可用。
    #                               # 设置 `apisix_llm_prompt_tokens_dist` 直方图的桶，单位为 Token。
    #   - 100
    #   - 1000
    #   - 10000
    # llm_completion_tokens_buckets: # 自 API7 企业版 3.9.14 起可用。
    #                                # 设置 `apisix_llm_completion_tokens_dist` 直方图的桶，单位为 Token。
    #   - 100
    #   - 1000
    #   - 10000

然后重新加载网关，使更改生效。

对于 Helm 部署，请更新用于渲染 plugin_attr.prometheus 的 Chart values，并保持 values 文件中的其他配置不变。

对于 APISIX Helm Chart，请设置以下 values：

values.yaml
apisix:
  pluginAttrs:
    prometheus:
      export_uri: /apisix/prometheus/metrics
      metric_prefix: apisix_
      enable_export_server: true
      export_addr:
        ip: 127.0.0.1
        port: 9091
      refresh_interval: 15
      # 在此添加其余 prometheus plugin_attr 字段。

对于 API7 网关 Helm Chart，请设置以下 values：

values.yaml
pluginAttrs:
  prometheus:
    export_uri: /apisix/prometheus/metrics
    metric_prefix: apisix_
    enable_export_server: true
    export_addr:
      ip: 127.0.0.1
      port: 9091
    fetch_metric_timeout: 5
    allow_degradation: false
    degradation_pause_steps: [ 60 ]
    # 在此添加其余 prometheus plugin_attr 字段。

然后使用当前网关版本对应的 Chart 应用 values 文件：

helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml

你可以使用内置变量创建 extra_labels。有关更多信息，请参阅为指标添加额外标签。

参数

请参阅插件通用配置，了解所有插件通用的配置选项。

prefer_name
boolean
默认值：false
如果为 true，则在 Prometheus 指标中导出路由/服务名称而不是其 ID。

插件元数据

以下插件元数据仅在 API7 企业版中可用。

插件元数据通过 Admin API 或声明式配置进行设置，与在 config.yaml 中渲染 plugin_attr 的 Helm values 相互独立。

disabled_labels
object
应禁用的标签，以减少指标数量并防止资源瓶颈。
决定指标本身含义的标签不允许禁用，因为合并这些标签会把本应区分的测量值并入同一条序列。这些标签包括 status 的 code，latency、bandwidth 和 llm_latency 的 type，以及 ai_cache_hits_total 的 layer。在 API7 企业版 3.9.x 系列中自 3.9.17 起、在 3.10.x 系列中自 3.10.4 起，配置这些标签会被拒绝。
- status
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model、llm_model、mcp_request_type 和 mcp_tool_name 的任意组合
  要为 apisix_http_status 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起，还支持禁用 request_type、request_llm_model 和 llm_model 标签。
  自 API7 企业版 3.9.14 版本起，还支持禁用 mcp_request_type 和 mcp_tool_name 标签。
- latency
  array[string]
  有效值：
  route、route_id、service、service_id、consumer、node、request_type、request_llm_model、llm_model、mcp_request_type 和 mcp_tool_name 的任意组合
  要为 apisix_http_latency 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起，还支持禁用 request_type、request_llm_model 和 llm_model 标签。
  自 API7 企业版 3.9.14 版本起，还支持禁用 mcp_request_type 和 mcp_tool_name 标签。
- bandwidth
  array[string]
  有效值：
  route、route_id、service、service_id、consumer、node、request_type、request_llm_model、llm_model、mcp_request_type 和 mcp_tool_name 的任意组合
  要为 apisix_bandwidth 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起，还支持禁用 request_type、request_llm_model 和 llm_model 标签。
  自 API7 企业版 3.9.14 版本起，还支持禁用 mcp_request_type 和 mcp_tool_name 标签。
- llm_latency
  array[string]
  有效值：
  route、route_id、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_llm_latency 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起可用。
  自 API7 企业版 3.9.14 版本起，还支持禁用 type 标签。
- llm_prompt_tokens
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_llm_prompt_tokens 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起可用。
- llm_completion_tokens
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_llm_completion_tokens 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起可用。
- llm_active_connections
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_llm_active_connections 指标禁用的标签。
  自 API7 企业版 3.9.7 版本起可用。
- llm_prompt_tokens_dist
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_llm_prompt_tokens_dist 指标禁用的标签。
  自 API7 企业版 3.9.14 版本起可用。
- llm_completion_tokens_dist
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_llm_completion_tokens_dist 指标禁用的标签。
  自 API7 企业版 3.9.14 版本起可用。
- ai_cache_hits_total
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_ai_cache_hits_total 指标禁用的标签。
  layer 是结构性标签，不允许禁用：合并该标签会把精确匹配命中和语义命中并入同一条序列。
  此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用，在 3.10.x 系列中自 3.10.3 起可用。
- ai_cache_misses_total
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_ai_cache_misses_total 指标禁用的标签。
  此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用，在 3.10.x 系列中自 3.10.3 起可用。
- ai_cache_bypasses_total
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_ai_cache_bypasses_total 指标禁用的标签。
  此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用，在 3.10.x 系列中自 3.10.3 起可用。
- ai_cache_embedding_latency
  array[string]
  有效值：
  route、route_id、matched_uri、matched_host、service、service_id、consumer、node、request_type、request_llm_model 和 llm_model 的任意组合
  要为 apisix_ai_cache_embedding_latency 指标禁用的标签。
  此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用，在 3.10.x 系列中自 3.10.3 起可用。

静态配置​

参数​

插件元数据​

静态配置

参数

插件元数据