prom2json 镜像文档

镜像概述和主要用途

prom2json 是一个用于抓取 Prometheus 客户端指标并转换为 JSON 格式的工具。由于 Prometheus 客户端已不再维护原生 JSON 暴露格式，该工具通过抓取客户端的协议缓冲区或文本格式指标，将其转换为结构化 JSON 并输出到标准输出，解决了非 Prometheus 服务器程序（尤其是小型临时程序）处理指标的需求，同时方便人工检查指标数据。

核心功能和特性

• 多格式输入支持：可处理 Prometheus 客户端暴露的协议缓冲区格式或文本格式指标
• 灵活的输入方式：支持通过 HTTP 端点、管道（如 curl 输出）或本地文件输入指标数据
• 安全配置：支持 TLS 客户端认证（通过证书和密钥）及不安全的 TLS 验证（不建议生产环境使用）
• 结构化 JSON 输出：生成包含指标名称、帮助信息、类型及详细指标数据的 JSON，兼容原生直方图格式
• 跨工具集成：输出的 JSON 可直接与 jq 等工具结合，便于指标分析和查询

使用场景和适用范围

• 人工检查指标：快速查看 Prometheus 客户端暴露的指标详情
• 小型临时程序：为无法处理协议缓冲区格式的简单程序提供 JSON 格式指标数据
• 指标数据分析：与 jq 等 JSON 处理工具结合，进行指标过滤、统计和查询
• 自动化脚本：在 shell 脚本中集成，处理和分析 Prometheus 指标数据

使用方法和配置说明

Docker 镜像获取

bash
docker pull prom/prom2json

基本使用示例

1. 抓取 HTTP 端点指标

直接从 Prometheus 客户端的 HTTP 指标端点抓取并转换：

bash
docker run --rm -ti prom/prom2json [***]

2. 通过管道输入指标

结合 curl 获取指标并通过管道输入给 prom2json：

bash
curl [***] | docker run --rm -i prom/prom2json

3. 处理本地文件指标

若需处理本地文件中的指标（需挂载文件到容器）：

bash
docker run --rm -ti -v /tmp/metrics.prom:/tmp/metrics.prom prom/prom2json /tmp/metrics.prom

安全配置示例

TLS 客户端认证

指定证书和密钥进行 TLS 客户端认证：

bash
docker run --rm -ti -v /path/to/cert:/cert -v /path/to/key:/key prom/prom2json --cert=/cert --key=/key [***]

不安全的 TLS 验证（不建议生产环境）

禁用 TLS 证书验证（仅用于测试）：

bash
docker run --rm -ti prom/prom2json --accept-invalid-cert [***]

JSON 输出格式说明

prom2json 输出的 JSON 为指标对象数组，每个对象包含以下字段：

• name：指标名称
• help：指标帮助信息
• type：指标类型（如 COUNTER、SUMMARY、HISTOGRAM 等）
• metrics：指标数据数组，包含具体标签和值

格式特点

• 数值编码：所有数值以字符串形式存储，以支持 NaN、+Inf 等 Prometheus 特殊值
• 直方图处理：包含至少一个区间的直方图将以原生直方图格式输出，结构参考 Prometheus 查询 API

示例输出

json
[
  {
    "name": "http_request_duration_microseconds",
    "help": "The HTTP request latencies in microseconds.",
    "type": "SUMMARY",
    "metrics": [
      {
        "labels": {
          "method": "get",
          "handler": "prometheus",
          "code": "200"
        },
        "quantiles": {
          "0.99": "67542.292",
          "0.9": "23902.678",
          "0.5": "6865.718"
        },
        "count": "743",
        "sum": "6936936.447000001"
      }
    ]
  },
  {
    "name": "roshi_select_call_count",
    "help": "How many select calls have been made.",
    "type": "COUNTER",
    "metrics": [
      {
        "value": "***"
      }
    ]
  }
]

与 jq 结合使用示例

查询 http_requests_total 指标家族的指标数量：

bash
docker run --rm -ti prom/prom2json [***] | jq '.[]|select(.name=="http_requests_total")|.metrics|length'