ClickStack で Redis メトリクスを監視する

要点OTel Redis receiver を使用して、ClickStack で Redis のパフォーマンスメトリクスを監視します。デモデータセットと、あらかじめ用意されたダッシュボードが含まれています。

既存の Redis とのインテグレーション

このセクションでは、ClickStack OTel collector で Redis receiver を設定し、既存の Redis 環境から ClickStack にメトリクスを送信できるようにする手順を説明します。既存の環境をご自身で設定する前に Redis メトリクスのインテグレーションを試したい場合は、次のセクションで用意されている事前設定済みのデモデータセットを使ってテストできます。

前提条件

稼働中の ClickStack インスタンス
既存の Redis インストール (バージョン 3.0 以降)
ClickStack から Redis へのネットワークアクセス (デフォルトポート: 6379)
authentication が有効な場合は Redis のパスワード

Redis 接続を確認する

まず、Redis に接続でき、INFO コマンドを実行できることを確認します。

# 接続テスト
redis-cli ping
# 期待される出力: PONG

# INFOコマンドのテスト（メトリクスcollectorが使用）
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 のベース設定を拡張できます。カスタム設定は、OpAMP 経由で HyperDX が管理するベース設定にマージされます。以下の内容で、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 に接続します (環境に合わせて endpoint を調整してください)
10 Seconds ごとにメトリクスを収集します
主要なパフォーマンスメトリクス (コマンド、クライアント、メモリ、keyspace 統計) を収集します
OpenTelemetry semantic conventions に従って、必須の service.name リソース属性を設定します
専用の pipeline を介してメトリクスを ClickHouse エクスポーターにルーティングします

収集される主要なメトリクス:

redis.commands.processed - 1 秒あたりに処理されたコマンド数
redis.clients.connected - 接続中のクライアント数
redis.clients.blocked - ブロッキング呼び出しで待機しているクライアント数
redis.memory.used - Redis が使用しているメモリ量 (バイト)
redis.memory.peak - ピークメモリ使用量
redis.keyspace.hits - 成功したキーのルックアップ数
redis.keyspace.misses - 失敗したキーのルックアップ数 (cache ヒット率の計算用)
redis.keys.expired - 期限切れになったキー数
redis.keys.evicted - メモリ不足により追い出されたキー数
redis.connections.received - 受信した接続の総数
redis.connections.rejected - 拒否された接続数

カスタム構成では、新しい receivers、processors、pipelines のみを定義します
memory_limiter と batch の processors、および clickhouse エクスポーターは、ベースの ClickStack 構成ですでに定義されています。ここでは名前で参照するだけです
resource processor は、OpenTelemetry semantic conventions に従って必須の service.name 属性を設定します
authentication を使用する本番環境では、パスワードを環境変数 ${env:REDIS_PASSWORD} に保存してください
collection_interval は必要に応じて調整してください (既定値は 10s。値を小さくするとデータ量が増えます)
複数の 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を実行する（設定内のendpointを"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 にログインして、メトリクスが取り込まれていることを確認します。

Metricsエクスプローラーに移動します
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) - キーのエビクションと cache パフォーマンスの低下
日次トラフィックパターン - 営業時間中のピーク、夕方の低下、ランダムな小規模スパイク

ClickStack を起動する

ClickStack インスタンスを起動します:

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

ClickStack が完全に起動するまで約 30 秒待ちます。

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 - メモリ逼迫 (キーのエビクションが始まる)

ダッシュボードと可視化

ClickStack で Redis の監視を始めるにあたって、Redis メトリクス向けの主要な可視化を用意しています。

してダッシュボード設定を取得する

あらかじめ用意されたダッシュボードをインポートする

HyperDX を開き、Dashboards セクションに移動します
右上の三点メニューから 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

カスタム設定の内容を表示し、正しく読み取れることを確認します:

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

HyperDX にメトリクスが表示されない

collector から 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 コマンドで、両方のコンテナーが同じネットワークに接続されるようにしてください。

次のステップ

重要なメトリクス (メモリ使用量のしきい値、接続数の上限、cache ヒット率の低下) に対するアラートを設定します
特定のユースケース向けに、追加のダッシュボードを作成します (レプリケーションラグ、永続化パフォーマンス)
異なるエンドポイントとサービス名を使用して 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 にメトリクスが表示されない

認証エラー

ネットワーク接続の問題

次のステップ

本番環境への移行