sql_exporter

本仓库包含一个服务，可按灵活的时间间隔运行用户定义的 SQL 查询，并通过 HTTP 导出结果指标供 Prometheus 采集。

状态

已在生产环境中与 PostgreSQL 一起积极使用。我们最终希望支持所有具有稳定 Go 数据库https://github.com/golang/go/wiki/SQLDrivers%E7%9A%84%E6%95%B0%E6%8D%AE%E5%BA%93%E3%80%82%E6%AC%A2%E8%BF%8E%E8%B4%A1%E7%8C%AE%E3%80%82

当前支持：

• Postgres
• ClickHouse
• AWS Athena
• MS-SQL
• MySQL

• ---

• Vertica
• Materialize
• CloudSQL

功能概览

快速开始

创建 config.yml 并运行服务：

go get github.com/justwatchcom/sql_exporter
cp config.yml.dist config.yml
./prom-sql-exporter

使用 Docker 运行：

docker run \
-v `pwd`/config.yml:/config/config.yml \
-e CONFIG=/config/config.yml \
-d \
-p 9237:9237 \
--name sql_exporter \
ghcr.io/justwatchcom/sql_exporter

手动配置 scrape_configs 片段：

scrape_configs:
- job_name: sql_exporter
static_configs:
- targets: ['localhost:9237']

标志

环境变量

使用方法

我们建议在 Kubernetes 中部署和运行 SQL exporter。

Kubernetes

参见 https://github.com/justwatchcom/sql_exporter/tree/master/examples/kubernetes%E3%80%82

Grafana

参见 https://github.com/justwatchcom/sql_exporter/tree/master/examples/grafana%E3%80%82

Prometheus

示例记录规则和告警规则可在 https://github.com/justwatchcom/sql_exporter/tree/master/examples/prometheus 中找到。

配置

为该 exporter 编写查询时，请记住 Prometheus 数据模型会为一个指标分配恰好一个 float 值，并可能通过零个或多个标签进一步标识。这些标签的类型必须为 string 或 text。

如果您的 SQL 方言支持显式类型转换，应始终将标签列转换为 text 类型，将指标列转换为 float 类型。SQL exporter 会尽力支持其他类型或不支持显式转换的驱动，但结果可能不符合预期。

以下是包含所有可用选项的带注释配置示例。更实际的示例请参见 https://github.com/justwatchcom/sql_exporter/blob/master/examples/kubernetes/configmap.yml%E3%80%82

---
# jobs 是作业的映射，可定义任意数量，但请注意数据库的连接使用情况
jobs:
# 每个作业需要唯一名称，用于日志记录和作为默认标签
- name: "example"
# interval 定义此作业两次运行之间的暂停时间
interval: '5m'
# cron_schedule 以标准 CRON 语法指定作业执行时间
# 若指定此参数，interval 将被忽略
cron_schedule: "0 0 * * *"
# connections 是连接 URL 的数组
# 每个查询将在每个连接上执行
connections:
- 'postgres://postgres@localhost/postgres?sslmode=disable'
# startup_sql 是 SQL 语句数组
# 每个语句在连接后执行一次
startup_sql:
- 'SET lock_timeout = 1000'
- 'SET idle_in_transaction_session_timeout = 100'
# iterator 是可选的迭代机制，用于遍历一系列值（例如多个数据库）
iterator:
# sql 是用于检索迭代值列表的 SQL - 查询结果必须为单列
sql: 'SELECT database_name FROM databases'
# placeholder 应出现在原始查询中，且不应用作环境变量
# 例如 {{PLACEHOLDER}} - 它将被查询检索到的值替换
placeholder: PLACEHOLDER
# label 是迭代值分配到的标签名称
label: database
# queries 是指标/查询映射的集合
queries:
# name 会添加前缀 sql_ 并用作指标名称
- name: "running_queries"
# help 是 Prometheus 默认注册表的要求，当前未被 Prometheus 服务器使用。
# 重要：对于名称相同的所有指标，help 必须相同！
help: "运行中的查询数量"
# 可选：用作指标时间戳源的列。
# 不需要时留空
timestamp: "created_at"
# labels 是用作额外标签的列数组。
# 对于名称相同的所有指标，labels 必须相同！
# 所有标签列的类型应为 text、varchar 或 string
labels:
- "datname"
- "usename"
# values 是用作指标值的列数组。所有值的类型应为 float
values:
- "count"
# query 是在此作业的每个连接上直接运行的 SQL 查询
query: |
SELECT now() as created_at, datname::text, usename::text, COUNT(*)::float AS count
FROM pg_stat_activity GROUP BY created_at, datname, usename;
# 如果查询返回零行，则视为失败
allow_zero_rows: false

在 PostgreSQL 上以非超级用户身份运行

某些查询在 PostgreSQL 上需要超级用户权限。如果您不想以超级用户权限运行 exporter，可以使用一些视图/函数来规避此限制。

CREATE USER postgres_exporter PASSWORD 'pw';
ALTER USER postgres_exporter SET SEARCH_PATH TO postgres_exporter,pg_catalog;

CREATE SCHEMA postgres_exporter AUTHORIZATION postgres_exporter;

CREATE FUNCTION postgres_exporter.f_select_pg_stat_activity()
RETURNS setof pg_catalog.pg_stat_activity
LANGUAGE sql
SECURITY DEFINER
AS $
SELECT * from pg_catalog.pg_stat_activity;
$;

CREATE FUNCTION postgres_exporter.f_select_pg_stat_replication()
RETURNS setof pg_catalog.pg_stat_replication
LANGUAGE sql
SECURITY DEFINER
AS $
SELECT * from pg_catalog.pg_stat_replication;
$;

CREATE VIEW postgres_exporter.pg_stat_replication
AS
SELECT * FROM postgres_exporter.f_select_pg_stat_replication();

CREATE VIEW postgres_exporter.pg_stat_activity
AS
SELECT * FROM postgres_exporter.f_select_pg_stat_activity();

GRANT SELECT ON postgres_exporter.pg_stat_replication TO postgres_exporter;
GRANT SELECT ON postgres_exporter.pg_stat_activity TO postgres_exporter;

日志

可通过设置 exporter 环境中的 LOGLEVEL 变量更改日志级别。

LOGLEVEL=info ./sql_exporter

数据库特定配置

某些数据库后端提供特殊功能：

• cloudsql-postgres：可使用特殊字符 * 查询该账户可访问的所有数据库
• cloudsql-mysql：同上
• rds-postgres：此类型 URL 需要有效的 AWS 配置，将使用等效于 rds generate-db-auth-token 的密码。对于此驱动，必须设置 AWS_REGION 环境变量。
• rds-mysql：此类型 URL 需要有效的 AWS 配置，将使用等效于 rds generate-db-auth-token 的密码。对于此驱动，必须设置 AWS_REGION 环境变量。

本 exporter 的开发背景

其他具有类似目标的项目在成熟度或灵活性方面均未满足我们的要求。本 exporter 不依赖任何其他服务，且已在生产环境中运行一段时间。

许可证

MIT License