企业官网建设流程全解析

• API网关
• 后端
• LLM 网关
• 微服务
• 人工智能

本文围绕 Kong 仓库中 Prometheus 插件的官方 Grafana 集成文件展开：kong/plugins/prometheus/grafana/目录下的README.md说明了仪表盘的身份与维护约定，而kong-official.json则是一份可直接导入 Grafana 的完整仪表盘定义（对应 Grafana 社区仪表盘库中的 ID 7424）。读完本文，你将掌握如何把该仪表盘导入自己的 Grafana、理解其六大面板区的每个查询背后的 PromQL 逻辑，并弄清这些指标在 Kong 插件源码（exporter.lua、schema.lua）中的真实来源与启用条件。

一、这份集成文件是什么：README 核心事实

kong/plugins/prometheus/grafana/README.md全文虽短，却交代了三件关键事实：

1. kong-official.json是官方仪表盘的“源文件”：它是 Kong 官方发布在 Grafana Labs 仪表盘库（ID 为7424）上的仪表盘的本体定义，仪表盘名称为 “Kong (official)”。
2. 仓库副本与线上副本必须保持同步：README 明确要求“本仓库中的这份拷贝与 Grafana Labs 上的拷贝应当保持同步”。
3. 同步目前靠人工完成：如果在本仓库修改了仪表盘，需要登录 Grafana Labs 重新上传新版本；反之亦然。这是当前（截至本仓库现状）唯一约定的维护方式。

换句话说，想了解 Kong 官方“开箱即用”的监控视图长什么样、有哪些查询、为什么这么写，直接读kong-official.json就是最权威的入口。以下各节全部基于该文件的真实内容展开。

二、仪表盘元信息与导入前准备

2.1 仪表盘核心元信息（来自 kong-official.json）

文件头部__inputs声明了一个名为DS_PROMETHEUS的 datasource 输入，这也是导入向导中“选择数据源”那一屏对应的变量。description字段写明其用途：“Dashboard that graphs metrics exported via Prometheus plugin in Kong”，即专门可视化 Kong Prometheus 插件导出的指标。

2.2 导入步骤

1. 确保 Kong 已启用prometheus插件（见第五节配置开关），并让 Prometheus 成功抓取 Kong 的/metrics端点（Status API 或 Admin API 均可，见第四节）。
2. 在 Grafana 中进入Dashboards → New → Import（或从搜索面板选择 Import dashboard）。
3. 选择“Upload dashboard JSON file”，上传本仓库的 kong-official.json；也可以直接复制文件内容粘贴到 “Import via panel json”。
4. 在导入界面为DS_PROMETHEUS选择已配置好的 Prometheus 数据源。
5. 点击 Import，仪表盘即加载完成，默认时间范围now-15m会立刻展示近 15 分钟数据。

提示：若某个面板长期空白，优先检查对应指标的插件开关是否开启（第五节），因为本仪表盘的大部分请求/延迟/带宽面板依赖插件显式开启status_code_metrics、latency_metrics、bandwidth_metrics等开关（默认均为关闭）。

三、仪表盘面板结构与查询逻辑（核心章节）

kong-official.json共约 3400 行，面板按“行（row）”组织，共六大区块：Request rate（请求速率）、Latencies（延迟）、Bandwidth（带宽）、Caching（缓存/内存）、Upstream（上游健康）、Nginx（连接状态）。每个区块默认折叠（collapsed: true），点击行标题展开。下面逐一拆解其查询与设计意图。

3.1 Request rate（请求速率区块）

关键点：

• 指标kong_http_requests_total的标签集合为service, route, code, source, workspace, consumer（见 exporter.lua）。source取值为service或kong，代表状态码来自上游响应还是 Kong 自身——官方测试中也验证了source="service"与source="kong"两种序列（见 02-access_spec.lua）。
• 该指标是counter，因此必须用rate()/irate()计算速率，面板统一使用rate(...,[1m])即 1 分钟窗口的平均速率。
• instance=~"$instance"中的instance标签并非插件产出，而是 Prometheus 抓取目标时自动附加的地址标签（ip:port），配合模板变量实现多节点筛选。

3.2 Latencies（延迟区块）

延迟区块同时绘制三组直方图，每组都给出p90 / p95 / p99三个分位数曲线：

实现佐证：在 exporter.lua 中定义了三种直方图桶：

• KONG_LATENCY_BUCKETS = {1, 2, 5, 7, 10, 15, 20, 30, 50, 75, 100, 200, 500, 750, 1000, 3000, 6000}（毫秒）——用于kong_latency_ms；
• UPSTREAM_LATENCY_BUCKETS = {25, 50, 80, 100, 250, 400, 700, 1000, 2000, 5000, 10000, 30000, 60000}——用于upstream_latency_ms与request_latency_ms。

写入逻辑位于 exporter.lua：serialized.latencies.request记入total_latency，serialized.latencies.proxy记入upstream_latency，serialized.latencies.kong记入kong_latency，三者均为observe()直方图观测。面板正是利用这些_bucket序列 +histogram_quantile还原分位数，属于标准的 Prometheus 直方图分位数计算范式。

3.3 Bandwidth（带宽区块）

实现佐证：exporter.lua 中bandwidth_bytes的标签为service, route, direction, workspace, consumer（HTTP 子系统含 consumer，stream 子系统不含）。写入时（exporter.lua）取serialized.ingress_size与serialized.egress_size，分别以direction="ingress"/"egress"递增计数。由于是字节累计量，面板使用irate(...[1m])计算瞬时每秒速率。

3.4 Caching（缓存/内存区块）

实现佐证：这两个指标在 exporter.lua 定义，标签含node_id, shared_dict, kong_subsystem（或node_id, pid, kong_subsystem），并在每次抓取时通过kong.node.get_memory_stats()刷新（exporter.lua）。它们是gauge类型，无需 rate。面板用百分比形式展示 shared dict 容量水位，可直接作为 Nginx/LuaJIT 内存压力告警依据。

3.5 Upstream（上游健康区块）

实现佐证：kong_upstream_target_health的 state 取值共四种——healthchecks_off、healthy、unhealthy、dns_error，定义在 exporter.lua。抓取时（exporter.lua）通过balancer.get_upstream_health()拉取每个 upstream 的 target 健康信息，先reset()旧值再写入，避免暴露过期状态；并且只有upstream_health_metrics开关开启且在传统模式（非 control_plane）下才导出。长循环中还调用kong.tools.yield.yield()主动让出执行权，避免抓取拖慢代理请求。heatmap 面板的 y 轴即{{upstream}}:{{target}}，可直观看到某 target 何时变红。

3.6 Nginx（连接状态区块）

实现佐证：kong_nginx_connections_total定义于 exporter.lua，标签为node_id, subsystem, state；每次抓取时通过kong.nginx.get_statistics()将connections_accepted/handled/total/active/reading/writing/waiting写入（exporter.lua）。该区块属于基础指标，无需任何插件开关即默认导出。

四、模板变量：多实例、多服务、多路由的动态筛选

templating.list定义了 5 个变量，全部基于 Prometheuslabel_values()动态获取，可多选（multi: true）且支持 “All”（includeAll: true，allValue: ".*"）：

面板查询中统一以service=~"$service"、route=~"$route"、instance=~"$instance"、upstream=~"$upstream"形式引用。由于allValue为.*，选择 “All” 时正则退化为匹配一切，实现全局视角；多选时则叠加多个取值。这是该仪表盘能同时服务“单节点排查”与“集群总览”的关键机制。

五、让面板数据“动起来”的插件配置开关

仪表盘中的大部分面板依赖 Kongprometheus插件在config中显式开启的开关。完整字段定义见 schema.lua，全部默认关闭：

注意：status_code_metrics是 RPS 面板的数据开关——handler.lua 中只有在该开关为真时才填充serialized.status_code，而 exporter.lua 只有看到serialized.status_code才会递增kong_http_requests_total。同理，延迟、带宽面板分别受latency_metrics、bandwidth_metrics控制。若只启用插件而未开任何开关，则只有 Caching、Nginx 等基础指标可看。

要使官方仪表盘完整出数，一份最小化的插件配置可以是：

# declarative 配置示例（或通过 Admin API / Kong Manager 配置） plugins: - name: prometheus config: per_consumer: true status_code_metrics: true latency_metrics: true bandwidth_metrics: true upstream_health_metrics: true ai_metrics: false wasm_metrics: false

另外，schema.lua 内置了custom_validator：若 Nginx 模板中不存在prometheus_metrics共享字典，插件配置会被校验拒绝（报错ngx shared dict 'prometheus_metrics' not found）。Kong 默认模板会注入该 shared dict，因此常规部署无需处理；相关行为在 02-access_spec.lua 有专门的单元测试覆盖。

细粒度开关的正确性同样有测试背书：02-access_spec.lua 中的granular_metrics_set将status_code_metrics → http_requests_total、latency_metrics → kong_latency_ms、bandwidth_metrics → bandwidth_bytes、upstream_health_metrics → upstream_target_health一一对应，逐一验证“开关关闭时对应指标不出现、开启时出现”，这正是理解面板与开关依赖关系的最佳实证。

六、数据链路：从请求到仪表盘的完整闭环

理解面板后，值得顺带掌握其背后的采集链路（全部可在本仓库源码中追溯）：

1. 写入（log 阶段）：每个代理请求结束时，handler.lua 在log钩子中调用kong.log.serialize()，按开关组装serialized数据，交给 exporter.lua 的log()递增/观测对应指标。
2. 存储（性能设计）：prometheus.lua 使用单个prometheus_metrics共享字典跨 worker 存储指标；同时每个 worker 进程内维护独立计数器，定期刷入共享字典，避免每次计数都锁共享内存。其结果是计数器呈“最终一致”——最多延迟一个同步间隔（默认 1 秒）才可见。直方图桶的le标签在内部按字典序排列存储，输出前还原为规范浮点格式与+Inf。
3. 抓取（/metrics 端点）：HTTP 子系统通过 Status API 或 Admin API 的/metrics路由暴露（status_api.lua 与 api.lua 均注册GET /metrics），调用exporter.collect()（exporter.lua），在抓取瞬间刷新连接数、内存、上游健康、数据面状态等 gauge 型指标，并输出全部序列；若配置了 stream 监听，还会通过 stream API 合并 stream 子系统指标。
4. Prometheus 抓取后：由 Grafana 的${DS_PROMETHEUS}数据源读取，经第三节的 PromQL 渲染成面板。

七、版本同步与贡献约定

回到 README.md 的核心维护约定：

• 本仓库的kong-official.json与 Grafana Labs 仪表盘库上的 7424 号仪表盘是同一份仪表盘的两个副本；
• 目前同步是纯人工流程：修改本仓库副本后，需要登录 Grafana Labs 上传新版本；反之，在线上修改后也要回写到本仓库；
• 因此，贡献者若改动该 JSON，应同时更新两个位置，保持两者内容一致，避免“仓库新、线上旧”或反之的漂移。

这也解释了为何该文件保留了gnetId: 7424、iteration（迭代时间戳）等元字段——它们正是线上仪表盘版本管理的遗留标识。

结语

Kong 官方 Grafana 仪表盘并非简单的“看图工具”，而是一份围绕kong_前缀指标族精心设计的查询模板：它以rate/irate处理计数器、以histogram_quantile还原直方图分位数、以label_values实现动态过滤、以数值映射呈现健康状态，几乎覆盖了 Prometheus 查询的最佳实践。搭配 schema.lua 中的细粒度开关、exporter.lua 中的指标定义与 02-access_spec.lua 的测试验证，你可以放心地将其作为生产环境 Kong 可观测性的起点，并在此基础上扩展 AI 指标、Wasm 指标等官方仪表盘尚未消费的新维度。

• API网关
• 后端
• LLM 网关
• 微服务
• 人工智能