json_exporter

镜像概述和主要用途

json_exporter 是由 Prometheus 社区开发的一款指标导出工具（exporter），用于通过 JSONPath 表达式从远程 JSON 数据源抓取数据，并将其转换为 Prometheus 可识别的指标格式。该工具支持灵活的模块配置，可针对不同结构的 JSON 数据定义独立的提取规则，是连接 JSON 数据源与 Prometheus 监控体系的关键组件。

核心功能和特性

• JSONPath 支持：采用 Kubernetes 风格的 JSONPath 语法，可精确定位 JSON 结构中的数据字段
• 多模块配置：支持定义多个抓取模块，每个模块可针对不同 JSON 数据源配置独立的提取规则
• HTTP 请求灵活性：支持 HTTP GET 和 POST 方法，POST 请求体可配置为静态内容或模板化内容（使用 Go Template 及 Sprig 库函数）
• 自定义时间戳：允许将 JSON 中的字段作为指标的 Unix 时间戳（int64 类型）
• TLS 安全支持：可通过配置启用 HTTPS，保障指标传输安全（详见 exporter-toolkit/web TLS 配置）
• Prometheus 集成：输出符合 Prometheus 规范的指标，可直接被 Prometheus 抓取和监控

使用场景和适用范围

• API 监控：从返回 JSON 格式数据的 REST API 服务中提取业务指标（如用户数、订单量等）
• 文件监控：从本地或远程 JSON 格式的日志文件、配置文件中提取系统或应用状态指标
• 多源适配：需同时监控多种不同结构 JSON 数据源的场景（通过多模块配置实现差异化处理）
• 自定义指标：将非标准 JSON 数据源集成到 Prometheus 监控体系的场景

详细使用方法和配置说明

基本使用步骤

1. 构建并启动 exporter（本地编译方式）：

   $ make build
   $ ./json_exporter --config.file examples/config.yml &
   

2. 启动测试 HTTP 服务器（用于提供 JSON 测试数据）：

   $ python3 -m http.server 8000 &
   Serving HTTP on :: port 8000 (http://[::]:8000/) ...
   

模块测试示例

默认模块测试

通过 probe 端点指定 default 模块和目标 JSON 数据源：

$ curl "http://localhost:7979/probe?module=default&target=http://localhost:8000/examples/data.json"

返回指标示例：

# HELP example_global_value Example of a top-level global value scrape in the json
# TYPE example_global_value untyped
example_global_value{environment="beta",location="planet-mars"} 1234
# HELP example_timestamped_value_count Example of a timestamped value scrape in the json
# TYPE example_timestamped_value_count untyped
example_timestamped_value_count{environment="beta"} 2
# HELP example_value_active Example of sub-level value scrapes from a json
# TYPE example_value_active untyped
example_value_active{environment="beta",id="id-A"} 1
example_value_active{environment="beta",id="id-C"} 1
...

自定义模块测试

针对不同 JSON 结构使用 animals 模块：

$ curl "http://localhost:7979/probe?module=animals&target=http://localhost:8000/examples/animal-data.json"

返回指标示例：

# HELP animal_population Example of top-level lists in a separate module
# TYPE animal_population untyped
animal_population{name="deer",predator="false"} 456
animal_population{name="lion",predator="true"} 123
animal_population{name="pigeon",predator="false"} 789

通过 Prometheus 测试

1. 启动 Prometheus 容器，挂载包含 json_exporter 抓取配置的 prometheus.yml：

   $ docker run --rm -it -p 9090:9090 -v $PWD/examples/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus
   

2. 访问 Prometheus UI：

   • 指标查询：http://localhost:9090/graph?g0.range_input=1h&g0.expr=example_value_active&g0.tab=1
   • 目标状态：http://localhost:9090/targets

使用自定义时间戳

可将 JSON 中的字段指定为指标的 Unix 时间戳（int64 类型），但需注意：

• Prometheus 原生的 数据过期机制 将被禁用
• 可能导致指标数据在 Prometheus 中保留时间超出预期

通过 HTTPS 暴露指标

可通过配置启用 HTTPS，具体 TLS 参数配置详见 exporter-toolkit/web 文档。

发送 HTTP POST 请求体内容

当配置 modules.<module_name>.body 参数时，exporter 将以 POST 方法发送请求，请求体内容由 body.content 定义，支持以下特性：

静态内容示例

body:
  content: |
    My static information: {"time_diff": "1m25s", "anotherVar": "some value"}

模板化内容示例（启用 Go Template）

需设置 body.templatize: true，可使用 Go Template 及 Sprig 库 函数：

body:
  content: |
    {"time_diff": "{{ duration `95` }}","anotherVar": "{{ randInt 12 30 }}"}
  templatize: true

结合查询参数的模板示例

Prometheus 发送给 exporter 的查询参数可作为模板变量使用：

body:
  content: |
    {"time_diff": "{{ duration `95` }}","anotherVar": "{{ .myVal | first }}"}
  templatize: true

请求示例：

$ curl "[***]"

实际发送的 POST 请求体：

{"time_diff": "1m35s","anotherVar": "something"}

Docker 部署方案

Docker run 命令示例

$ docker run -v $PWD/examples/config.yml:/config.yml quay.io/prometheuscommunity/json-exporter --config.file=/config.yml

• -v $PWD/examples/config.yml:/config.yml：挂载本地配置文件到容器内
• --config.file=/config.yml：指定 exporter 使用的配置文件路径

配置参数说明

核心启动参数

• --config.file：（必选）指定 JSON exporter 的配置文件路径，配置文件需包含模块定义、JSONPath 规则等

模块配置参数（config.yml 中）

• body.content：POST 请求体内容，支持静态文本或模板字符串
• body.templatize：布尔值，是否启用模板化处理（默认 false），启用后 body.content 将作为 Go Template 解析