ClickStack으로 Redis 메트릭 모니터링

요약OTel Redis 수신기를 사용해 ClickStack에서 Redis 성능 메트릭을 모니터링합니다. 데모 데이터셋과 사전 구축된 대시보드도 제공합니다.

기존 Redis와의 통합

이 섹션에서는 ClickStack OTel collector를 Redis 수신기로 구성해, 기존 Redis 환경에서 ClickStack으로 메트릭을 전송하도록 설정하는 방법을 설명합니다. 기존 환경을 직접 구성하기 전에 Redis Metrics 통합을 테스트하려면, 다음 섹션에서 미리 구성된 데모 데이터셋로 먼저 테스트할 수 있습니다.

사전 요구 사항

실행 중인 ClickStack 인스턴스
기존 Redis 설치본(버전 3.0 이상)
ClickStack에서 Redis로의 네트워크 접근(기본 포트 6379)
인증이 enabled된 경우 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에 연결합니다(환경에 맞게 엔드포인트를 조정하세요)
10초마다 메트릭을 수집합니다
주요 성능 메트릭(명령, 클라이언트, 메모리, keyspace 통계)을 수집합니다
OpenTelemetry semantic conventions에 따라 필수 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 semantic conventions에 따라 필수 service.name 속성을 설정합니다
authentication을 사용하는 운영 환경에서는 비밀번호를 환경 변수에 저장하십시오: ${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에 로그인한 다음 메트릭이 정상적으로 수집되는지 확인합니다:

Metrics 탐색기로 이동합니다
redis.로 시작하는 메트릭을 검색합니다(예: redis.commands.processed, redis.memory.used)
구성한 수집 인터벌에 따라 메트릭 데이터 포인트가 표시되어야 합니다

데모 데이터셋

프로덕션 시스템을 구성하기 전에 Redis Metrics 통합을 테스트하려는 사용자를 위해, 실제와 유사한 Redis Metrics 패턴이 포함된 미리 생성된 데이터셋을 제공합니다.

샘플 메트릭 데이터셋 다운로드

미리 생성된 메트릭 파일을 다운로드합니다(실제와 유사한 패턴이 포함된 24시간 분량의 Redis Metrics):

# 게이지 메트릭 다운로드(메모리, 단편화 비율)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

# Download sum metrics (commands, connections, keyspace stats)
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) - 키 eviction이 발생하고 캐시 성능이 저하됨
일일 트래픽 패턴 - 업무 시간대 피크, 저녁 시간대 감소, 불규칙한 미세 스파이크

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에 직접 로드합니다:

# 게이지 메트릭 로드(메모리, 단편화)
cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Load sum metrics (commands, connections, 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 Metrics를 한 번에 확인하십시오.

데모 데이터셋의 시간 범위는 2025-10-20 00:00:00부터 2025-10-21 05:00:00까지입니다. HyperDX의 시간 범위도 이 기간에 맞추십시오.다음 패턴을 확인해 보십시오:

06:00 - 캐시 워밍(낮은 적중률이 상승)
14:30-14:45 - 트래픽 급증(클라이언트 연결 수 증가, 일부 요청 거부)
20:00 - 메모리 압박(키 eviction 시작)

대시보드 및 시각화

ClickStack으로 Redis를 모니터링하기 시작할 수 있도록 Redis Metrics용 핵심 시각화를 제공합니다.

대시보드 구성을

사전 구축된 대시보드 가져오기

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 수신기가 포함되어 있는지 확인하세요:

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 명령에서 두 컨테이너가 동일한 네트워크를 사용하도록 설정하십시오.

다음 단계

중요한 메트릭(메모리 사용량 임계값, 연결 제한, 캐시 적중률 저하)에 대한 알림을 설정합니다
특정 사용 사례(복제 지연, 영속성 성능)에 맞는 추가 대시보드를 생성합니다
서로 다른 엔드포인트와 서비스 이름을 사용하도록 수신기 구성을 복제하여 여러 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에 메트릭이 표시되지 않는 경우

인증 오류

네트워크 연결 문제

다음 단계

프로덕션 환경으로 전환하기