Prometheus ValKey 和 Redis 指标导出器

用于ValKey指标（与Redis兼容）的Prometheus导出器。
支持ValKey和Redis 2.x、3.x、4.x、5.x、6.x和7.x版本

乌克兰仍在遭受俄罗斯侵略，请考虑通过捐款支持乌克兰。

构建和运行导出器

本地构建和运行

git clone https://github.com/oliver006/redis_exporter.git
cd redis_exporter
go build .
./redis_exporter --version

预构建二进制文件

预构建的二进制文件请查看发布页面。

基本Prometheus配置

在prometheus.yml配置文件的scrape_configs中添加以下块：

scrape_configs:
  - job_name: redis_exporter
    static_configs:
    - targets: ['<<REDIS-EXPORTER-HOSTNAME>>:9121']

并相应调整主机名。

Kubernetes SD配置

为了在下拉列表中显示人类可读的实例名称而不是IP地址，建议使用实例重新标记。

例如，如果通过pod角色抓取指标，可以添加：

          - source_labels: [__meta_kubernetes_pod_name]
            action: replace
            target_label: instance
            regex: (.*redis.*)

作为相应抓取配置的重新标记配置。根据正则表达式值，只有名称中包含"redis"的pod才会被重新标记。

根据如何检索抓取目标，可以采用类似的方法处理其他角色类型。

抓取多个Redis主机的Prometheus配置

Prometheus文档中有一篇非常有用的文章，介绍了多目标导出器的工作原理。

使用命令行标志--redis.addr=运行导出器，这样每次抓取/metrics端点时就不会尝试访问本地实例。使用以下配置，Prometheus将使用/scrape端点而不是/metric端点。例如，第一个目标将通过以下Web请求查询： http://exporterhost:9121/scrape?target=first-redis-host:6379

scrape_configs:
  ## 导出器将抓取的多个Redis目标的配置
  - job_name: 'redis_exporter_targets'
    static_configs:
      - targets:
        - redis://first-redis-host:6379
        - redis://second-redis-host:6379
        - redis://second-redis-host:6380
        - redis://second-redis-host:6381
    metrics_path: /scrape
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: <<REDIS-EXPORTER-HOSTNAME>>:9121

  ## 抓取导出器本身的配置
  - job_name: 'redis_exporter'
    static_configs:
      - targets:
        - <<REDIS-EXPORTER-HOSTNAME>>:9121

Redis实例列在targets下，Redis导出器主机名通过最后一个relabel_config规则配置。
如果Redis实例需要身份验证，可以通过导出器的--redis.password命令行选项设置密码（这意味着目前只能在尝试以这种方式抓取的实例中使用一个密码。如果这是个问题，请使用多个导出器）。
您还可以使用json文件通过file_sd_configs提供多个目标，如下所示：

scrape_configs:
  - job_name: 'redis_exporter_targets'
    file_sd_configs:
      - files:
        - targets-redis-instances.json
    metrics_path: /scrape
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: <<REDIS-EXPORTER-HOSTNAME>>:9121

  ## 抓取导出器本身的配置
  - job_name: 'redis_exporter'
    static_configs:
      - targets:
        - <<REDIS-EXPORTER-HOSTNAME>>:9121

targets-redis-instances.json应该类似这样：

[
  {
    "targets": [ "redis://redis-host-01:6379", "redis://redis-host-02:6379"],
    "labels": { }
  }
]

Prometheus使用文件监视，对json文件的所有更改都会立即应用。

命令行标志

命令行设置的优先级高于环境变量提供的任何配置。

与 Redis 进行身份验证

如果您的 Redis 实例需要身份验证,那么有几种方法可以提供用户名(Redis 6.x 中引入了 ACL)和密码。

您可以将用户名和密码作为地址的一部分提供,有关 redis:// 方案的官方文档请参见这里。 您可以设置 -redis.password-file=sample-pwd-file.json 来指定密码文件,每当导出器连接到 Redis 实例时都会使用它,无论您是使用 /scrape 端点为多个实例还是使用正常的 /metrics 端点仅抓取一个实例。 它仅在 redis.password == "" 时生效。请参阅 contrib/sample-pwd-file.json 获取一个可用示例,并确保在密码文件条目中始终包含 redis://。

包含密码的 URI 示例为:redis://<<用户名(可选)>>:<<密码>>@<<主机名>>:<<端口>>

或者,您可以使用 --redis.user 和 --redis.password 直接向 redis_exporter 提供用户名和/或密码。

如果您想为 redis_exporter 使用专用的 Redis 用户(而不是默认用户),则需要为该用户启用一系列命令。 您可以使用以下 Redis 命令设置用户,只需将 <<<用户名>>> 和 <<<密码>>> 替换为您想要的值。

ACL SETUSER <<<用户名>>> -@all +@connection +memory -readonly +strlen +config|get +xinfo +pfcount -quit +zcard +type +xlen -readwrite -command +client -wait +scard +llen +hlen +get +eval +slowlog +cluster|info -hello -echo +info +latency +scan -reset -auth -asking ><<<密码>>>

要监控 Sentinel 节点,您可以使用以下带有正确 ACL 的命令:

ACL SETUSER <<<用户名>>> -@all +@connection -command +client -hello +info -auth +sentinel|masters +sentinel|replicas +sentinel|slaves +sentinel|sentinels +sentinel|ckquorum ><<<密码>>>

通过 Docker 运行

最新版本会自动发布到 Docker 注册表。

您可以像这样运行它:

docker run -d --name redis_exporter -p 9121:9121 oliver006/redis_exporter

Docker 镜像也发布到 quay.io docker 仓库,如果遇到 Docker hub 的速率限制问题,您可以从那里拉取它们。

docker run -d --name redis_exporter -p 9121:9121 quay.io/oliver006/redis_exporter

latest docker 镜像仅包含导出器二进制文件。 如果出于调试目的需要在具有 shell 的镜像中运行导出器,则可以运行 alpine 镜像:

docker run -d --name redis_exporter -p 9121:9121 oliver006/redis_exporter:alpine

如果您尝试访问主机节点上运行的 Redis 实例,则需要添加 --network host,以便 redis_exporter 容器可以访问它:

docker run -d --name redis_exporter --network host oliver006/redis_exporter

在 Kubernetes 上运行

这里是一个 Kubernetes 部署配置示例,说明如何将 redis_exporter 作为 Redis 实例的边车部署。

Tile38

Tile38 现在原生支持 Prometheus 导出服务器指标和对象、字符串等的基本统计信息。 您还可以使用 redis_exporter 导出 Tile38 指标,特别是通过使用 Lua 脚本或 -check-keys 标志导出更高级的指标。 要启用 Tile38 支持,请使用 --is-tile38=true 运行导出器。

导出的内容

INFO 命令中的大多数项目都被导出,详情请参阅 Redis 文档。 此外,对于每个数据库,都有关于总键数、过期键数和数据库中键的平均 TTL 的指标。 您还可以使用 -check-keys(或相关)标志导出键的值。导出器还将导出键的大小(或根据数据类型导出长度)。 这可用于导出(有序)集合、哈希、列表、流等中的元素数量。 如果键是字符串格式并与 --check-keys(或相关)匹配,则其字符串值将作为标签导出到 key_value_as_string 指标中。

如果您需要自定义指标收集,可以使用 -script 标志提供以逗号分隔的 Redis Lua 脚本 路径列表。如果您只传递一个脚本,可以省略逗号。contrib 文件夹中可以找到一个示例。

redis_memory_max_bytes 指标

redis_memory_max_bytes 指标将显示 Redis 可以使用的最大字节数。 如果您正在抓取的 Redis 实例未设置内存限制,则该值为零(这是 Redis 的默认设置)。 您可以通过检查 redis_config_maxmemory 指标是否为零来确认是否是这种情况,或者通过 redis-cli 连接到 Redis 实例并运行 CONFIG GET MAXMEMORY 命令来确认。

效果展示

Grafana 截图示例:

Grafana 仪表板可在 grafana.com 和/或 github.com 上获得。

同时查看多个 Redis

如果运行 Redis Sentinel,可能需要同时查看各个集群成员的指标。为此,仪表板的下拉菜单是多值类型的,允许选择多个 Redis。请注意,这里有一个注意事项;顶部的单一统计面板,即 正常运行时间、总内存使用量 和 客户端,在查看多个 Redis 时不起作用。

使用 mixin

redis-mixin 中提供了一组示例规则、警报和仪表板。

从 0.x 升级到 1.x

PR #256 引入了重大更改,这些更改作为版本 v1.0.0 发布。 如果你只抓取一个Redis实例并使用命令行标志--redis.address和--redis.password，那么你很可能不受影响。 否则，请查看PR #256和这个README以获取更多信息。

按键组聚合内存使用

当一个Redis实例用于多个目的时，能够看到Redis内存如何在不同使用场景中消耗是很有用的。当一个没有驱逐策略的Redis实例内存不足时，这一点尤为重要，因为我们想确定是某些应用程序行为不当（例如没有删除不再使用的键）还是Redis实例需要扩容以应对增加的资源需求。幸运的是，大多数使用Redis的应用程序会为与其特定目的相关的键采用某种命名约定，如（层次化）命名空间前缀，这可以被redis_exporter的check-keys、check-single-keys和count-keys参数利用来显示特定场景的内存使用指标。按键组聚合内存使用更进一步，利用Redis LUA脚本支持的灵活性，通过用户定义的LUA正则表达式列表将Redis实例上的所有键分类到组中，从而可以将内存使用指标聚合到易于识别的组中。

要启用按键组聚合内存使用，只需通过redis_exporter参数check-key-groups指定一个非空的、逗号分隔的LUA正则表达式列表。在每次按键组聚合内存指标时，redis_exporter将为每个Redis数据库设置一个SCAN游标，通过LUA脚本分批处理所有键。然后，同一个LUA脚本会逐个处理每个键批次，如下所示：

1. 调用MEMORY USAGE命令收集每个键的内存使用情况
2. 按指定顺序将指定的LUA正则表达式应用于每个键，给定键所属的组名将从第一个匹配该键的正则表达式的捕获组连接而成。例如，将正则表达式^(.*)_[^_]+$应用于键key_exp_Nick将产生组名key_exp。如果没有指定的正则表达式匹配某个键，该键将被分配到unclassified组

一旦键被分类，相应组的内存使用和键计数器将在本地LUA表中递增。当一个批次中的所有键都被处理后，这个聚合的指标表将与下一个SCAN游标位置一起返回给redis_exporter，redis_exporter可以将所有批次的数据聚合成一个分组内存使用指标表，供Prometheus指标抓取器使用。

除了使LUA正则表达式的全部灵活性可用于将键分类到组中外，LUA脚本还有减少网络流量的好处，因为它在Redis服务器上执行所有MEMORY USAGE命令，并以比键级数据更紧凑的格式将聚合数据返回给redis_exporter。使用SCAN游标处理由服务器端LUA脚本处理的键批次也有助于防止Redis单一处理线程中出现无限延迟气泡，并且可以通过check-keys-batch-size参数根据特定环境调整批次大小。

扫描Redis实例的整个键空间可能听起来有点奢侈，但只需一次扫描就可以将所有键分类到组中，在一个中等规模的系统上，有约78万个键和一个相当复杂的17个正则表达式列表，完成一次按键组的内存使用聚合平均需要约5秒。当然，特定系统的实际性能会因总键数、用于分类的正则表达式的数量和复杂度以及配置的批次大小而有很大差异。

为了保护Prometheus不被配置错误的组分类正则表达式（例如应用正则表达式^(.*)$，其中每个键都将被分类到自己的不同组）导致的大量时间序列所淹没，可以通过max-distinct-key-groups参数配置每个Redis数据库的不同键组数量限制。如果超过max-distinct-key-groups限制，只有内存使用最高的键组将在限制内单独跟踪，剩余的键组将在一个单一的overflow键组下报告。

以下是启用按键组聚合内存使用时将暴露的额外指标列表：

收集Redis列表及其大小的脚本

如果使用Redis版本<4.0，通过默认的redis_exporter无法获取我们需要基于长度或内存收集的大多数有用指标。 借助LUA脚本，我们可以收集这些指标。 其中一个脚本contrib/collect_lists_length_growing.lua将帮助收集Redis列表的长度。 有了这个计数，我们可以采取以下行动，如在Grafana或任何类似工具中使用这些Prometheus指标创建警报或仪表板。

开发

测试需要各种真实的Redis实例，不仅为了验证导出器的正确性，还为了与旧版本的Redis以及类似Redis的系统（如KeyDB或Tile38）的兼容性。 contrib/docker-compose-for-tests.yml文件包含了所需的所有服务定义。 你可以先通过运行make docker-env-up启动Redis测试实例，然后每次想运行测试时，可以运行make docker-test。这将把当前目录（包含.go源文件）挂载到docker容器中并启动测试。 测试完成后，你可以通过运行make docker-env-down来关闭堆栈。 或者你可以通过运行make docker-all一次性启动堆栈、运行测试，然后关闭堆栈。

注意使用持久化测试环境时，测试初始化可能导致意外结果。当make docker-env-up执行一次，而make docker-test不断运行或在执行过程中停止时，数据库中的键数量会发生变化，这可能导致测试意外失败。作为临时解决方案，请定期使用make docker-env-down进行清理。

社区努力

如果你有更多建议、问题或关于添加内容的想法，请开启一个issue或PR。