使用 ClickStack 监控 Redis 指标

使用 ClickStack 监控 Redis 指标

简而言之

使用 OTel Redis receiver 在 ClickStack 中监控 Redis 性能指标。包含演示数据集和预置仪表板。

​

与现有 Redis 集成

本节介绍如何配置现有的 Redis 部署：通过为 ClickStack OTel collector 配置 Redis receiver，将指标发送到 ClickStack。

如果你想在配置自己现有的环境之前先测试 Redis 指标集成，可以在下一节中使用我们预先配置的演示数据集。

前置条件

• 正在运行的 ClickStack 实例
• 已有的 Redis 安装 (3.0 或更高版本)
• ClickStack 到 Redis 的网络访问 (默认端口 6379)
• 如果启用了身份验证，则需要 Redis 密码

1. ​

   验证 Redis 连接

   首先，确认你可以连接到 Redis，并且 INFO 命令能够正常执行：

   # 测试连接
   redis-cli ping
   # 预期输出：PONG
   
   # 测试 INFO 命令（由指标收集器使用）
   redis-cli INFO server
   # 应显示 Redis 服务器信息
   

   如果 Redis 启用了身份验证：

   redis-cli -a <your-password> ping
   

   常见的 Redis 端点：

   • 本地安装：localhost:6379
   • Docker：使用容器名称或服务名称 (例如 redis:6379)
   • 远程：<redis-host>:6379
2. ​

   创建自定义 OTel collector 配置

   ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry collector 配置。自定义配置会与 HyperDX 通过 OpAMP 管理的基础配置合并。

   创建一个名为 redis-metrics.yaml 的文件，内容如下：

   redis-metrics.yaml

   receivers:
     redis:
       endpoint: "localhost:6379"
       collection_interval: 10s
       # 如果 Redis 需要身份验证，请取消注释
       # password: ${env:REDIS_PASSWORD}
       
       # 配置要收集的指标
       metrics:
         redis.commands.processed:
           enabled: true
         redis.clients.connected:
           enabled: true
         redis.memory.used:
           enabled: true
         redis.keyspace.hits:
           enabled: true
         redis.keyspace.misses:
           enabled: true
         redis.keys.evicted:
           enabled: true
         redis.keys.expired:
           enabled: true
   
   processors:
     resource:
       attributes:
         - key: service.name
           value: "redis"
           action: upsert
   
   service:
     pipelines:
       metrics/redis:
         receivers: [redis]
         processors:
           - resource
           - memory_limiter
           - batch
         exporters:
           - clickhouse
   

   此配置：

   • 连接到 localhost:6379 上的 Redis (请根据你的部署调整端点)
   • 每 10 秒采集一次指标
   • 采集关键性能指标 (命令、客户端、内存、keyspace 统计信息)
   • 按照 OpenTelemetry 语义约定 设置必需的 service.name 资源属性
   • 通过专用管道将指标路由到 ClickHouse exporter

   采集的关键指标：

   • redis.commands.processed - 每秒处理的命令数
   • redis.clients.connected - 已连接的客户端数量
   • redis.clients.blocked - 因阻塞调用而被阻塞的客户端数量
   • redis.memory.used - Redis 已使用的内存字节数
   • redis.memory.peak - 峰值内存占用
   • redis.keyspace.hits - 成功的键查找次数
   • redis.keyspace.misses - 失败的键查找次数 (用于计算缓存命中率)
   • redis.keys.expired - 已过期的键数量
   • redis.keys.evicted - 因内存压力而被驱逐的键数量
   • redis.connections.received - 接收到的连接总数
   • redis.connections.rejected - 被拒绝的连接数

   • 你只需在自定义配置中定义新的 receivers、processors 和 pipelines
   • memory_limiter 和 batch processors 以及 clickhouse exporter 已在基础 ClickStack 配置中定义，你只需按名称引用它们
   • resource processor 会按照 OpenTelemetry 语义约定设置必需的 service.name 属性
   • 如果在生产环境中启用身份验证，请将密码存储在环境变量中：${env:REDIS_PASSWORD}
   • 请根据需要调整 collection_interval (默认值为 10 秒；较低的值会增加数据量)
   • 如果有多个 Redis 实例，请自定义 service.name 以便区分它们 (例如："redis-cache"、"redis-sessions")
3. ​

   配置 ClickStack 以加载自定义配置

   要在现有的 ClickStack 部署中启用自定义 collector 配置，您需要：

   1. 将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
   2. 设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
   3. 确保 ClickStack 与 Redis 之间的网络连通

   选项 1：Docker Compose

   更新您的 ClickStack 部署配置：

   services:
     clickstack:
       # ... 现有配置 ...
       environment:
         - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
         # 可选：如果 Redis 需要身份验证
         # - REDIS_PASSWORD=your-redis-password
         # ... 其他环境变量 ...
       volumes:
         - ./redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
         # ... 其他卷 ...
       # 如果 Redis 在同一个 compose 文件中：
       depends_on:
         - redis
   
     redis:
       image: redis:7-alpine
       ports:
         - "6379:6379"
       # 可选：启用身份验证
       # command: redis-server --requirepass your-redis-password
   

   选项 2：Docker run (一体化镜像)

   如果使用一体化镜像并通过 docker run 运行：

   docker run --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     clickhouse/clickstack-all-in-one:latest
   

   重要： 如果 Redis 在另一个容器中运行，请使用 Docker 网络：

   # 创建网络
   docker network create monitoring
   
   # 在该网络中运行 Redis
   docker run -d --name redis --network monitoring redis:7-alpine
   
   # 在同一网络中运行 ClickStack（在配置中将端点更新为 "redis:6379"）
   docker run --name clickstack \
     --network monitoring \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     clickhouse/clickstack-all-in-one:latest
   
4. ​

   在 HyperDX 中验证指标

   配置完成后，登录 HyperDX 并确认指标是否已开始流入：

   1. 打开指标浏览器
   2. 搜索以 redis. 开头的指标 (例如：redis.commands.processed、redis.memory.used)
   3. 你应会看到指标数据点按你配置的采集间隔持续出现

​

演示数据集

对于想在配置生产系统之前先测试 Redis 指标 集成的用户，我们提供了一个预生成的数据集，其中包含逼真的 Redis 指标 变化模式。

1. ​

   下载样本指标数据集

   下载预生成的指标文件 (24 小时的 Redis 指标 数据，包含逼真的变化模式) ：

   # 下载 gauge 指标（内存、碎片率）
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv
   
   # 下载 sum 指标（命令、连接、keyspace 统计）
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-sum.csv
   

   该数据集包含以下逼真模式：

   • 缓存预热事件 (06:00) - 命中率从 30% 升至 80%
   • 流量突增 (14:30-14:45) - 流量激增 5 倍，并伴随连接压力
   • 内存压力 (20:00) - 出现 key 驱逐，缓存性能下降
   • 每日流量模式 - 工作时段达到高峰、夜间回落、随机出现小尖峰
2. ​

   启动 ClickStack

   启动一个 ClickStack 实例：

   docker run -d --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

   等待大约 30 秒，让 ClickStack 完全启动。

3. ​

   将指标加载到 ClickStack 中

   将指标直接加载到 ClickHouse：

   # 加载 gauge 指标（内存、碎片）
   cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
     clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"
   
   # 加载 sum 指标（命令、连接、keyspace）
   cat redis-metrics-sum.csv | docker exec -i clickstack-demo \
     clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
   
4. ​

   在 HyperDX 中验证指标

   加载完成后，查看指标的最快方式是使用预置仪表盘。

   继续前往仪表盘和可视化部分，导入仪表盘并一次查看全部 Redis 指标。

   演示数据集的时间范围为 2025-10-20 00:00:00 到 2025-10-21 05:00:00。请确保 HyperDX 中的时间范围与该时间窗口一致。

   请留意以下有代表性的模式：

   • 06:00 - 缓存预热 (命中率从较低水平开始上升)
   • 14:30-14:45 - 流量突增 (客户端连接数高，出现部分拒绝)
   • 20:00 - 内存压力 (开始出现 key 驱逐)

​

仪表盘与可视化

为帮助你开始使用 ClickStack 监控 Redis，我们提供了 Redis 指标 所需的关键可视化内容。

1. ​

   仪表盘配置

2. ​

   导入预构建仪表盘

   1. 打开 HyperDX 并进入 仪表盘 部分
   2. 点击右上角省略号菜单中的 Import Dashboard

   3. 上传 redis-metrics-dashboard.json 文件，然后点击 Finish Import
3. ​

   查看仪表盘

   导入后，仪表盘会创建完成，且所有可视化都已预先配置好：

   对于演示数据集，请将时间范围设置为 2025-10-20 05:00:00 - 2025-10-21 05:00:00 (UTC) (请根据你的本地时区调整) 。导入的仪表盘默认不会指定时间范围。

​

故障排查

​

自定义配置未正确加载

请确认环境变量 CUSTOM_OTELCOL_CONFIG_FILE 设置正确：

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

检查自定义配置文件是否已挂载到 /etc/otelcol-contrib/custom.config.yaml：

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml

查看自定义 config 内容，确认其可正常读取：

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

​

HyperDX 中没有显示任何指标

确认采集器可以访问 Redis：

# 从 ClickStack 容器中执行
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# 预期输出：PONG

检查 Redis INFO 命令是否能正常运行：

docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# 应显示 Redis 统计信息

确认生效的配置中包含你的 Redis receiver：

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "redis:"

检查 collector 日志中是否有错误：

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# 查找连接错误或身份验证失败

​

身份验证错误

如果您在日志中看到身份验证错误：

# 验证 Redis 是否需要身份验证
redis-cli CONFIG GET requirepass

# 测试身份验证
redis-cli -a <password> ping

# 确保在 ClickStack 环境中已设置密码
docker exec <clickstack-container> printenv REDIS_PASSWORD

更新配置，使用该密码：

receivers:
  redis:
    endpoint: "redis:6379"
    password: ${env:REDIS_PASSWORD}

​

网络连接问题

如果 ClickStack 无法连接到 Redis：

# 检查两个容器是否在同一网络中
docker network inspect <network-name>

# 测试连通性
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379

确保在 Docker Compose 文件或 docker run 命令中，将两个容器置于同一网络中。

​

后续步骤

• 为关键指标设置告警 (如内存使用量阈值、连接数限制、缓存命中率下降)
• 针对特定用例创建更多仪表盘 (如复制延迟、持久化性能)
• 通过复制 receiver 配置并使用不同的端点和服务名称，监控多个 Redis 实例

​

生产环境部署

本指南在 ClickStack 内置的 OpenTelemetry Collector 基础上进行了扩展，便于快速完成设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅发送 OpenTelemetry 数据。