📚 课程目录第4章 Kong内置监控工具

4. Kong内置监控工具：Admin API状态端点、健康检查接口、Prometheus插件基础配置

Kong网关提供了多层级的可观测性能力，从最基础的存活探测到细粒度的指标采集。本章聚焦于三个核心工具：Admin API状态端点用于快速获取节点运行时信息，健康检查接口用于上游与节点级存活判定，Prometheus插件则提供生产级指标暴露能力。掌握这三者的配置与解读，是延迟诊断的第一步。

4.1 Admin API状态端点：节点运行时快照

Kong的Admin API默认监听 localhost:8001，其中 /status 端点返回当前节点的内存、请求计数、连接池等关键指标。该端点不依赖任何插件，开箱即用。

端点路径	方法	返回内容摘要
`/status`	GET	内存使用、活跃连接数、请求总数、数据库可达性
`/status/cluster`	GET	集群节点列表、每个节点的状态与同步延迟

  关键字段解读：

  memory.lua_shared_dicts.kong_db_cache.allocated_amount — 数据库缓存分配量，持续增长可能预示缓存未命中。

  server.requests_count — 自节点启动以来的总请求数，用于计算平均延迟。

  database.reachable — 布尔值，指示数据库连接是否正常。

# 快速获取节点状态
curl -s http://localhost:8001/status | jq '.server, .memory, .database'

4.2 健康检查接口：上游与节点存活探测

Kong的健康检查分为两个层面：上游（Upstream）健康检查和节点健康检查。前者用于判定后端服务实例是否可用，后者用于监控Kong节点自身。

4.2.1 上游主动健康检查

在Upstream对象中配置 healthchecks.active，Kong会定期向目标发送HTTP/HTTPS/TCP探测请求。配置示例：

# 创建带主动健康检查的Upstream
curl -s -X POST http://localhost:8001/upstreams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example-upstream",
    "healthchecks": {
      "active": {
        "type": "http",
        "http_path": "/health",
        "healthy": {
          "interval": 5,
          "successes": 2
        },
        "unhealthy": {
          "interval": 5,
          "http_failures": 3
        }
      }
    }
  }'

最佳实践：健康检查路径应返回2xx或3xx状态码，响应体尽量小（如 {"status":"ok"}），避免增加上游负载。健康检查间隔建议设为5~10秒，超时设为1秒。

4.2.2 节点健康检查端点

Kong节点自身暴露 /health 端点（需启用 health-check 插件或通过Nginx直接暴露）。返回格式：

# 节点健康检查响应示例
{
  "status": "healthy",
  "nodes": [
    {
      "node_id": "d3b7a1c2-...",
      "status": "healthy",
      "last_sync": "2025-03-15T10:30:00Z"
    }
  ]
}

该端点常用于负载均衡器（如AWS NLB、HAProxy）的存活探测，建议配置为 interval: 10s、timeout: 2s、unhealthy_threshold: 3。

4.3 Prometheus插件基础配置

Prometheus插件是Kong生产监控的核心，它将请求延迟、状态码分布、上游延迟等指标以Prometheus格式暴露。配置分为两步：启用插件和配置指标。

4.3.1 全局启用Prometheus插件

# 在Kong上全局启用Prometheus插件
curl -s -X POST http://localhost:8001/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prometheus",
    "config": {
      "per_consumer": false,
      "status_code_metrics": true,
      "latency_metrics": true,
      "bandwidth_metrics": true,
      "upstream_health_metrics": true
    }
  }'

配置项	默认值	说明
`per_consumer`	false	是否按消费者拆分指标，开启后基数会膨胀
`status_code_metrics`	true	记录每个状态码的请求计数
`latency_metrics`	true	记录Kong延迟、上游延迟、总延迟（毫秒）
`bandwidth_metrics`	true	记录请求与响应体大小（字节）
`upstream_health_metrics`	true	暴露上游健康检查状态（0/1）

4.3.2 指标暴露端点

启用插件后，Kong会在 :8001/metrics 和 :8000/metrics 暴露指标。推荐使用 :8001/metrics（Admin API端口），避免公网暴露。

# 获取Prometheus格式指标
curl -s http://localhost:8001/metrics | head -20

# 输出示例：
# HELP kong_http_requests_total Total number of HTTP requests
# TYPE kong_http_requests_total counter
kong_http_requests_total{service="svc1",route="route1",code="200"} 1024
# HELP kong_latency_ms Latency in milliseconds
# TYPE kong_latency_ms histogram
kong_latency_ms_bucket{type="kong",le="5"} 512
kong_latency_ms_bucket{type="kong",le="10"} 768

注意：指标基数爆炸是常见陷阱。如果每个Service/Route/Consumer都产生独立的标签组合，Prometheus采集压力会急剧上升。建议在非必要场景关闭 per_consumer，并限制Service和Route数量在合理范围内（通常不超过500个）。

4.4 监控工具关系架构

下图展示了三个工具在Kong节点中的协作关系：Admin API提供状态快照，健康检查接口保障上游与节点存活，Prometheus插件输出结构化指标供外部采集。

4.5 配置清单与验证步骤

以下清单帮助你在新部署的Kong节点上快速完成监控工具配置：

验证Admin API状态端点：curl -s http://localhost:8001/status | jq '.database.reachable' 应返回 true。
配置上游健康检查：为每个Upstream设置 healthchecks.active，确认健康检查路径可达。
暴露节点健康检查：在负载均衡器后端配置 /health 探测，确认返回 200。
启用Prometheus插件：全局启用并确认 :8001/metrics 返回指标数据。
验证指标完整性：发送测试请求后，检查 kong_latency_ms 和 kong_http_requests_total 是否出现。

快速验证脚本：

#!/bin/bash
# 检查所有监控端点是否正常
echo "=== Admin API Status ==="
curl -sf http://localhost:8001/status | jq '.database.reachable'
echo "=== Health Check ==="
curl -sf http://localhost:8001/health | jq '.status'
echo "=== Prometheus Metrics ==="
curl -sf http://localhost:8001/metrics | grep -c "kong_http_requests_total"

完成上述配置后，Kong节点便具备了基础的监控能力。下一阶段将基于Prometheus指标构建延迟诊断仪表板，并深入分析瓶颈根因。