使用 ClickStack 监控 Redis 指标 - ClickHouse Documentation

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

与现有 Redis 集成

本节介绍如何配置现有的 Redis 部署：通过为 ClickStack OTel collector 配置 Redis receiver，将指标发送到 ClickStack。如果你想在配置自己现有的环境之前先测试 Redis 指标集成，可以在下一节中使用我们预先配置的演示数据集。

前置条件

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

验证 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

创建自定义 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")

配置 ClickStack 以加载自定义配置

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

将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
确保 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

在 HyperDX 中验证指标

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

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

演示数据集

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

下载样本指标数据集

下载预生成的指标文件 (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 驱逐，缓存性能下降
每日流量模式 - 工作时段达到高峰、夜间回落、随机出现小尖峰

启动 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 完全启动。

将指标加载到 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"

在 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 指标所需的关键可视化内容。

仪表盘配置

导入预构建仪表盘

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

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

查看仪表盘

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

对于演示数据集，请将时间范围设置为 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 数据。

​与现有 Redis 集成

前置条件

​验证 Redis 连接

​创建自定义 OTel collector 配置

​配置 ClickStack 以加载自定义配置

选项 1：Docker Compose

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

​在 HyperDX 中验证指标

​演示数据集

​下载样本指标数据集

​启动 ClickStack

​将指标加载到 ClickStack 中

​在 HyperDX 中验证指标

​仪表盘与可视化

​仪表盘配置

​导入预构建仪表盘

​查看仪表盘

​故障排查

​自定义配置未正确加载

​HyperDX 中没有显示任何指标

​身份验证错误

​网络连接问题

​后续步骤

​生产环境部署

与现有 Redis 集成

验证 Redis 连接

创建自定义 OTel collector 配置

配置 ClickStack 以加载自定义配置

在 HyperDX 中验证指标

演示数据集

下载样本指标数据集

启动 ClickStack

将指标加载到 ClickStack 中

在 HyperDX 中验证指标

仪表盘与可视化

仪表盘配置

导入预构建仪表盘

查看仪表盘

故障排查

自定义配置未正确加载

HyperDX 中没有显示任何指标

身份验证错误

网络连接问题

后续步骤

生产环境部署