measurementlab/prometheus-bigquery-exporter

prometheus-bigquery-exporter

一个用于将BigQuery查询结果转换为Prometheus指标的导出器。

局限性：无历史值

Prometheus通过导出器收集系统的当前状态，并将收集到的值与收集时间的时间戳关联。

注意：此导出器无法将历史值与过去的时间戳关联！

因此，prometheus-bigquery-exporter执行的查询结果应代表查询执行时固定时间点的有意义值，例如“1小时前5分钟窗口内的测试总数”。

查询格式

prometheus-bigquery-exporter接受任意BigQuery查询，但查询结果必须遵循可预测的结构，以便导出器成功解析并转换为Prometheus指标。

指标名称与值

指标名称由查询文件名和查询值列派生。导出器通过匹配列名模式value([.+])识别值列，括号内的字符将附加到从查询文件名获取的指标前缀后。例如：

• 文件名：bq_ndt_test.sql
• 指标前缀：bq_ndt_test
• 列名：value_count
• 最终指标：bq_ndt_test_count

必须包含值列（至少一个）：

• value([.+]) - 每个查询必须定义"value"结果列，值必须为整数或浮点数。若需返回多个值，每个值列需以"value"为前缀并使用唯一后缀。

标签列（可选）：

• 若结果包含多行，查询必须定义标签以区分各值。所有非"value"列名将成为结果指标的标签。例如，包含"machine"和"value"两列的结果将创建带有"machine"标签的指标，标签值取自对应行数据。

标签必须为字符串：

• 标签数量无限制，但应遵循Prometheus最佳实践，限制标签值的基数。

重复指标视为错误：

• 若查询返回多行且未通过标签集区分，则视为错误。

示例查询

以下查询创建标签并按标签分组：

sql
-- 示例数据，替代实际值表
WITH example_data AS (
    SELECT "a" AS label, 5 AS widgets
    UNION ALL
    SELECT "b" AS label, 2 AS widgets
    UNION ALL
    SELECT "b" AS label, 3 AS widgets
)

SELECT
    label, SUM(widgets) AS value
FROM
    example_data
GROUP BY
    label

• 将示例查询保存为文件 bq_example.sql
• 启动导出器：

sh
prometheus-bigquery-exporter -gauge-query bq_example.sql

• 访问 http://localhost:9348/metrics，将看到类似以下指标：

txt
bq_example{label="a"} 5
bq_example{label="b"} 5
...

示例配置

典型部署在Kubernetes环境（如GKE）中：

sh
# 进入示例目录
cd example
# 部署示例查询为配置映射及Kubernetes部署
./deploy.sh

测试

若需本地运行BigQuery导出器（如测试新查询），可按以下步骤构建并运行：

1. 构建Docker镜像：

sh
docker build -t bqx-local -f Dockerfile .

2. 使用Google账号认证（两步均需执行：第一步用于gcloud命令，使用用户凭据；第二步用于导出器，使用应用默认凭据）：

sh
gcloud auth login
gcloud auth application-default login

3. 运行镜像，转发端口并挂载gcloud凭据：

sh
docker run -p 9348:9348 --rm \
  -v $HOME/.config/gcloud:/root/.config/gcloud \
  -v $PWD:/queries -it bqx-local \
    -project=$GCLOUD_PROJECT \
    -gauge-query=/queries/example/config/bq_example.sql