> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickStack으로 Redis 메트릭 모니터링

> ClickStack으로 Redis 메트릭 모니터링

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **요약**

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

<div id="existing-redis">
  ## 기존 Redis와의 통합
</div>

이 섹션에서는 ClickStack OTel collector를 Redis 수신기로 구성해, 기존 Redis 환경에서 ClickStack으로 메트릭을 전송하도록 설정하는 방법을 설명합니다.

기존 환경을 직접 구성하기 전에 Redis Metrics 통합을 테스트하려면, [다음 섹션](#demo-dataset)에서 미리 구성된 데모 데이터셋로 먼저 테스트할 수 있습니다.

<div id="prerequisites">
  ##### 사전 요구 사항
</div>

* 실행 중인 ClickStack 인스턴스
* 기존 Redis 설치본(버전 3.0 이상)
* ClickStack에서 Redis로의 네트워크 접근(기본 포트 6379)
* 인증이 enabled된 경우 Redis 비밀번호

<Steps>
  <Step>
    #### Redis 연결 확인

    먼저 Redis에 연결할 수 있는지, 그리고 INFO 명령이 정상적으로 작동하는지 확인합니다:

    ```bash theme={null}
    # 연결 테스트
    redis-cli ping
    # 예상 출력: PONG

    # INFO 명령 테스트 (메트릭 collector에서 사용)
    redis-cli INFO server
    # Redis 서버 정보가 표시됩니다
    ```

    Redis 인증이 필요한 경우:

    ```bash theme={null}
    redis-cli -a <your-password> ping
    ```

    **일반적으로 사용되는 Redis 엔드포인트:**

    * **로컬 설치**: `localhost:6379`
    * **Docker**: 컨테이너 이름 또는 서비스 이름을 사용합니다(예: `redis:6379`)
    * **원격**: `<redis-host>:6379`
  </Step>

  <Step>
    #### 사용자 지정 OTel collector 구성 만들기

    ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성과 머지됩니다.

    다음 구성으로 `redis-metrics.yaml` 파일을 생성하십시오:

    ```yaml title="redis-metrics.yaml" theme={null}
    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](https://opentelemetry.io/docs/specs/semconv/resource/#service)에 따라 **필수 `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` - 거부된 연결 수

    <Note>
      - 사용자 지정 구성에서는 새 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"`)
    </Note>
  </Step>

  <Step>
    #### 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 배포 구성을 업데이트합니다:

    ```yaml theme={null}
    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`으로 올인원 이미지를 실행하는 경우:

    ```bash theme={null}
    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 네트워킹을 사용하세요:

    ```bash theme={null}
    # 네트워크 생성
    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
    ```
  </Step>

  <Step>
    #### HyperDX에서 메트릭 확인

    구성이 완료되면 HyperDX에 로그인한 다음 메트릭이 정상적으로 수집되는지 확인합니다:

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

<div id="demo-dataset">
  ## 데모 데이터셋
</div>

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

<Steps>
  <Step>
    #### 샘플 메트릭 데이터셋 다운로드

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

    ```bash theme={null}
    # 게이지 메트릭 다운로드(메모리, 단편화 비율)
    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이 발생하고 캐시 성능이 저하됨
    * **일일 트래픽 패턴** - 업무 시간대 피크, 저녁 시간대 감소, 불규칙한 미세 스파이크
  </Step>

  <Step>
    #### ClickStack 시작

    ClickStack 인스턴스를 시작합니다:

    ```bash theme={null}
    docker run -d --name clickstack-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    ClickStack이 완전히 시작될 때까지 약 30초 동안 기다리십시오.
  </Step>

  <Step>
    #### ClickStack에 메트릭 로드

    메트릭을 ClickHouse에 직접 로드합니다:

    ```bash theme={null}
    # 게이지 메트릭 로드(메모리, 단편화)
    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"
    ```
  </Step>

  <Step>
    #### HyperDX에서 메트릭 확인

    로드가 완료되면 메트릭을 가장 빠르게 확인하는 방법은 사전 구축된 대시보드를 사용하는 것입니다.

    [Dashboards and visualization](#dashboards) 섹션으로 이동하여 대시보드를 가져오고 모든 Redis Metrics를 한 번에 확인하십시오.

    <Note>
      데모 데이터셋의 시간 범위는 2025-10-20 00:00:00부터 2025-10-21 05:00:00까지입니다. HyperDX의 시간 범위도 이 기간에 맞추십시오.

      다음 패턴을 확인해 보십시오:

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

<div id="dashboards">
  ## 대시보드 및 시각화
</div>

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

<Steps>
  <Step>
    #### 대시보드 구성을 <TrackedLink href={'/ko/examples/redis-metrics-dashboard.json'} download="redis-metrics-dashboard.json" eventName="docs.redis_metrics_monitoring.dashboard_download">다운로드</TrackedLink>
  </Step>

  <Step>
    #### 사전 구축된 대시보드 가져오기

    1. HyperDX를 열고 Dashboards 섹션으로 이동합니다
    2. 오른쪽 상단의 줄임표 메뉴에서 **Import Dashboard**를 클릭합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=21af53f2ddc48534745ebc3f01de39ef" alt="대시보드 가져오기 버튼" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. `redis-metrics-dashboard.json` 파일을 업로드하고 **Finish Import**를 클릭합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-redis-metrics-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=9359d42142104688fb2cfb842e9644aa" alt="가져오기 완료 대화상자" width="3814" height="1914" data-path="images/clickstack/import-redis-metrics-dashboard.png" />
  </Step>

  <Step>
    #### 대시보드 보기

    대시보드는 모든 시각화가 사전 구성된 상태로 생성됩니다:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/_TDydWLKO6Z3njo9/images/clickstack/redis-metrics-dashboard.png?fit=max&auto=format&n=_TDydWLKO6Z3njo9&q=85&s=acd6e275ec33c3c7bd48dd1cd10bceb6" alt="Redis Metrics 대시보드" width="3814" height="1914" data-path="images/clickstack/redis-metrics-dashboard.png" />

    <Note>
      데모 데이터세트의 경우 시간 범위를 \*\*2025-10-20 05:00:00 - 2025-10-21 05:00:00 (UTC)\*\*로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되어 있지 않습니다.
    </Note>
  </Step>
</Steps>

<div id="troubleshooting">
  ## 문제 해결
</div>

<div id="troubleshooting-not-loading">
  ### 사용자 지정 구성이 로드되지 않는 경우
</div>

환경 변수 `CUSTOM_OTELCOL_CONFIG_FILE`이 올바르게 설정되었는지 확인하세요:

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

사용자 정의 구성 파일이 `/etc/otelcol-contrib/custom.config.yaml`에 마운트되었는지 확인하세요:

```bash theme={null}
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
```

사용자 지정 구성 내용을 확인하여 정상적으로 읽을 수 있는지 확인합니다:

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-metrics">
  ### HyperDX에 메트릭이 표시되지 않는 경우
</div>

collector에서 Redis에 접근할 수 있는지 확인하세요:

```bash theme={null}
# ClickStack 컨테이너에서 실행
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# 예상 출력: PONG
```

Redis INFO 명령이 정상적으로 작동하는지 확인하세요:

```bash theme={null}
docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# Redis 통계 정보가 표시되어야 합니다
```

실제로 적용된 구성에 Redis 수신기가 포함되어 있는지 확인하세요:

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "redis:"
```

collector 로그에서 오류가 있는지 확인하세요:

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# 연결 오류 또는 인증 실패 항목을 확인하세요
```

<div id="auth-errors">
  ### 인증 오류
</div>

로그에 인증 관련 오류가 표시되면:

```bash theme={null}
# Redis 인증 필요 여부 확인
redis-cli CONFIG GET requirepass

# 인증 테스트
redis-cli -a <password> ping

# ClickStack 환경에 비밀번호가 설정되어 있는지 확인
docker exec <clickstack-container> printenv REDIS_PASSWORD
```

비밀번호를 사용하도록 구성을 업데이트하세요:

```yaml theme={null}
receivers:
  redis:
    endpoint: "redis:6379"
    password: ${env:REDIS_PASSWORD}
```

<div id="network-issues">
  ### 네트워크 연결 문제
</div>

ClickStack에서 Redis에 연결할 수 없는 경우:

```bash theme={null}
# 두 컨테이너가 동일한 네트워크에 있는지 확인
docker network inspect <network-name>

# 연결 테스트
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379
```

Docker Compose 파일 또는 `docker run` 명령에서 두 컨테이너가 동일한 네트워크를 사용하도록 설정하십시오.

<div id="next-steps">
  ## 다음 단계
</div>

* 중요한 메트릭(메모리 사용량 임계값, 연결 제한, 캐시 적중률 저하)에 대한 [알림](/ko/clickstack/features/alerts)을 설정합니다
* 특정 사용 사례(복제 지연, 영속성 성능)에 맞는 추가 대시보드를 생성합니다
* 서로 다른 엔드포인트와 서비스 이름을 사용하도록 수신기 구성을 복제하여 여러 Redis 인스턴스를 모니터링합니다

<div id="going-to-production">
  ## 프로덕션 환경으로 전환하기
</div>

이 가이드는 빠른 설정을 위해 ClickStack에 내장된 OpenTelemetry Collector를 기반으로 설명합니다. 프로덕션 배포에서는 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 것을 권장합니다. 프로덕션 구성은 [OpenTelemetry 데이터 전송](/ko/clickstack/ingesting-data/opentelemetry)을 참조하십시오.