Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

使用 ClickStack 监控 Redis 指标

View as MarkdownEdit this pageReport an issueSet up docs MCP

与现有 Redis 集成

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

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

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

验证 Redis 连接

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

# Test connection
redis-cli ping
# Expected output: PONG

# Test INFO command (used by metrics collector)
redis-cli INFO server
# Should display Redis server information

如果 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.yamlyaml
receivers:
  redis:
    endpoint: "localhost:6379"
    collection_interval: 10s
    # Uncomment if Redis requires authentication
    # password: ${env:REDIS_PASSWORD}
    
    # Configure which metrics to collect
    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 - 被拒绝的连接数

配置 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:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # Optional: If Redis requires authentication
      # - REDIS_PASSWORD=your-redis-password
      # ... other environment variables ...
    volumes:
      - ./redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      # ... other volumes ...
    # If Redis is in the same compose file:
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    # Optional: Enable authentication
    # 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 网络：

# Create a network
docker network create monitoring

# Run Redis on the network
docker run -d --name redis --network monitoring redis:7-alpine

# Run ClickStack on the same network (update endpoint to "redis:6379" in config)
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 并确认指标是否已开始流入：

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

演示数据集

对于想在配置生产系统之前先测试 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 中验证指标

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

继续前往 Dashboards and visualization 部分，导入仪表盘并一次查看全部 Redis 指标。

仪表盘与可视化

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

下载仪表盘配置

下载仪表盘配置文件。

导入预构建的仪表盘

  1. 打开 HyperDX 并导航到仪表盘部分
  2. 点击右上角省略号菜单中的 Import Dashboard
导入仪表盘按钮
  1. 上传 redis-metrics-dashboard.json 文件，然后点击 Finish Import
完成导入对话框

查看仪表盘

仪表盘创建完成后，所有可视化都将预先配置好：

Redis 指标 仪表盘

故障排查

自定义配置未正确加载

请确认环境变量 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 数据。

Navigation