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

# ClickStack를 사용한 Kafka 로그 모니터링

> ClickStack를 사용한 Kafka 로그 모니터링

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 `filelog` 수신기를 사용해 ClickStack에서 Kafka 브로커 로그(Log4j 포맷)를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 제공됩니다.
</Info>

<div id="existing-kafka">
  ## 기존 Kafka 통합
</div>

이 섹션에서는 ClickStack OTel collector 구성을 수정하여 기존 Kafka 설치에서 브로커 로그를 ClickStack으로 전송하도록 설정하는 방법을 설명합니다.
기존 환경을 직접 구성하기 전에 Kafka 로그 통합을 테스트하려면 ["데모 데이터세트"](/ko/clickstack/integration-examples/kafka-logs#demo-dataset) 섹션의 사전 구성된 설정과 샘플 데이터를 사용해 테스트할 수 있습니다.

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

* 실행 중인 ClickStack 인스턴스
* 기존 Kafka 설치(버전 2.0 이상)
* Kafka 로그 파일(`server.log`, `controller.log` 등)에 대한 접근 권한

<Steps>
  <Step>
    #### Kafka 로깅 구성 확인

    Kafka는 Log4j를 사용하며, `kafka.logs.dir` 시스템 속성 또는 `LOG_DIR` 환경 변수로 지정된 디렉터리에 로그를 씁니다. 로그 파일 위치를 확인하십시오:

    ```bash theme={null}
    # 기본 위치
    ls $KAFKA_HOME/logs/      # 표준 Apache Kafka (기본값: <install-dir>/logs/)
    ls /var/log/kafka/        # RPM/DEB 패키지 설치
    ```

    주요 Kafka 로그 파일:

    * **`server.log`**: 일반 브로커 로그(시작, 연결, 복제, 오류)
    * **`controller.log`**: 컨트롤러 관련 이벤트(리더 선출, 파티션 재할당)
    * **`state-change.log`**: 파티션 및 레플리카 상태 전환

    Kafka의 기본 Log4j 패턴은 다음과 같은 행을 생성합니다:

    ```text theme={null}
    [2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)
    ```

    <Note>
      Docker 기반 Kafka 배포(예: `confluentinc/cp-kafka`)에서는 기본 Log4j 구성에 콘솔 appender만 포함되어 있으며 file appender는 없으므로 logs는 stdout에만 기록됩니다. `filelog` 수신기를 사용하려면 `log4j.properties`에 file appender를 추가하거나 stdout을 파이프로 전달하는 방식(예: `| tee /var/log/kafka/server.log`)으로 logs를 파일로 리디렉션해야 합니다.
    </Note>
  </Step>

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

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

    다음 내용으로 `kafka-logs-monitoring.yaml` 파일을 만드세요:

    ```yaml theme={null}
    receivers:
      filelog/kafka:
        include:
          - /var/log/kafka/server.log
          - /var/log/kafka/controller.log  # 선택 사항, log4j가 별도의 파일 어펜더로 구성된 경우에만 존재
          - /var/log/kafka/state-change.log  # 선택 사항, 위와 동일
        start_at: beginning
        multiline:
          line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
        operators:
          - type: regex_parser
            regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
            parse_from: body
            parse_to: attributes
            timestamp:
              parse_from: attributes.timestamp
              layout: '%Y-%m-%d %H:%M:%S,%L'
            severity:
              parse_from: attributes.severity

          - type: move
            from: attributes.message
            to: body

          - type: add
            field: attributes.source
            value: "kafka"

          - type: add
            field: resource["service.name"]
            value: "kafka-production"

    service:
      pipelines:
        logs/kafka:
          receivers: [filelog/kafka]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    ```

    <Note>
      * 사용자 지정 구성에서는 새 수신기와 파이프라인만 정의합니다. 프로세서(`memory_limiter`, `transform`, `batch`)와 익스포터(`clickhouse`)는 기본 ClickStack 구성에 이미 정의되어 있으므로 이름만 참조하면 됩니다.
      * `multiline` 구성은 스택 트레이스가 하나의 로그 항목으로 수집되도록 합니다.
      * 이 구성은 collector가 시작될 때 기존 로그를 모두 읽도록 `start_at: beginning`을 사용합니다. 운영 환경에 배포할 때는 collector가 다시 시작될 때 로그를 다시 수집하지 않도록 `start_at: end`로 변경하십시오.
    </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. collector가 Kafka 로그를 읽을 수 있도록 Kafka 로그 디렉터리를 마운트합니다.

    <Tabs>
      <Tab title="Docker Compose">
        ClickStack 배포 구성을 업데이트합니다.

        ```yaml theme={null}
        services:
          clickstack:
            # ... 기존 구성 ...
            environment:
              - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
              # ... 기타 환경 변수 ...
            volumes:
              - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
              - /var/log/kafka:/var/log/kafka:ro
              # ... 기타 볼륨 ...
        ```
      </Tab>

      <Tab title="Docker Run (All-in-One Image)">
        docker에서 All-in-One image를 사용하는 경우 다음을 실행합니다.

        ```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)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
          -v /var/log/kafka:/var/log/kafka:ro \
          clickhouse/clickstack-all-in-one:latest
        ```
      </Tab>
    </Tabs>

    <Note>
      ClickStack collector에 Kafka 로그 파일을 읽을 수 있는 적절한 권한이 있는지 확인하십시오. 운영 환경에서는 읽기 전용 마운트(`:ro`)를 사용하고 최소 권한 원칙을 따르십시오.
    </Note>
  </Step>

  <Step>
    #### HyperDX에서 로그 확인

    구성이 완료되면 HyperDX에 로그인하여 로그가 정상적으로 유입되는지 확인합니다:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/kafka/logs/search-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=3686938272330fbd9a0e5a4eeaede1a3" alt="검색 뷰" width="3838" height="1934" data-path="images/clickstack/kafka/logs/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/kafka/logs/log-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=78cde5b194317c3e10bf55c8b51317cc" alt="로그 뷰" width="3838" height="1934" data-path="images/clickstack/kafka/logs/log-view.png" />
  </Step>
</Steps>

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

프로덕션 시스템을 구성하기 전에 미리 생성된 샘플 데이터세트로 Kafka 로그 통합을 테스트하십시오.

<Steps>
  <Step>
    #### 샘플 데이터세트 다운로드

    샘플 로그 파일을 다운로드합니다:

    ```bash theme={null}
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log
    ```
  </Step>

  <Step>
    #### 테스트 collector 구성 생성

    다음 구성으로 `kafka-logs-demo.yaml` 파일을 생성합니다:

    ```yaml theme={null}
    cat > kafka-logs-demo.yaml << 'EOF'
    receivers:
      filelog/kafka:
        include:
          - /tmp/kafka-demo/server.log
        start_at: beginning
        multiline:
          line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
        operators:
          - type: regex_parser
            regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
            parse_from: body
            parse_to: attributes
            timestamp:
              parse_from: attributes.timestamp
              layout: '%Y-%m-%d %H:%M:%S,%L'
            severity:
              parse_from: attributes.severity

          - type: move
            from: attributes.message
            to: body

          - type: add
            field: attributes.source
            value: "kafka-demo"

          - type: add
            field: resource["service.name"]
            value: "kafka-demo"

    service:
      pipelines:
        logs/kafka-demo:
          receivers: [filelog/kafka]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    EOF
    ```
  </Step>

  <Step>
    #### 데모 구성으로 ClickStack 실행

    데모 로그와 구성으로 ClickStack을 실행합니다:

    ```bash theme={null}
    docker run --name clickstack-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
      clickhouse/clickstack-all-in-one:latest
    ```

    ## HyperDX에서 로그 확인

    ClickStack이 실행되면 다음을 수행합니다:

    1. [HyperDX](http://localhost:8080/)를 열고 계정에 로그인합니다(먼저 계정을 생성해야 할 수 있습니다)
    2. Search 보기로 이동한 다음 source를 `Logs`로 설정합니다
    3. 시간 범위에 \*\*2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)\*\*가 포함되도록 설정합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/kafka/logs/search-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=3686938272330fbd9a0e5a4eeaede1a3" alt="검색 보기" width="3838" height="1934" data-path="images/clickstack/kafka/logs/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/kafka/logs/log-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=78cde5b194317c3e10bf55c8b51317cc" alt="로그 보기" width="3838" height="1934" data-path="images/clickstack/kafka/logs/log-view.png" />
  </Step>
</Steps>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/ko/examples/kafka-logs-dashboard.json'} download="kafka-logs-dashboard.json" eventName="docs.kafka_logs_monitoring.dashboard_download">다운로드</TrackedLink>하여 대시보드 구성 파일을 받습니다
  </Step>

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

    1. HyperDX를 열고 대시보드 섹션으로 이동합니다.
    2. 오른쪽 상단의 점 3개 메뉴에서 "Import Dashboard"를 클릭합니다.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/import-dashboard.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=916537724b4bfd47afb8cccdb5dc4902" alt="대시보드 가져오기" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. kafka-logs-dashboard.json 파일을 업로드한 다음 "Finish Import"를 클릭합니다.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/kafka/logs/finish-import.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=f3cb33d0bd562ff1b411d90fc35e133c" alt="Kafka 로그 대시보드 가져오기 완료" width="3382" height="1934" data-path="images/clickstack/kafka/logs/finish-import.png" />
  </Step>

  <Step>
    #### 모든 시각화가 사전 구성된 상태로 대시보드가 생성됩니다

    데모 데이터세트를 사용하는 경우 시간 범위를 \*\*2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)\*\*를 포함하도록 설정합니다.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/kafka/logs/example-dashboard.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=826425c8a0208ee24276ffdbcb5727bd" alt="Kafka 로그 예시 대시보드" width="3838" height="1934" data-path="images/clickstack/kafka/logs/example-dashboard.png" />
  </Step>
</Steps>

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

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

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

**collector 오류 확인:**

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log
```

**Kafka 로그 포맷이 예상 패턴과 일치하는지 확인하세요:**

```bash theme={null}
tail -1 /var/log/kafka/server.log
```

Kafka 설치에서 사용자 지정 Log4j 패턴을 사용한다면, 이에 맞게 `regex_parser` 정규식을 조정하세요.

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

* 중요한 이벤트(브로커 장애, 복제 오류, consumer group 관련 문제)에 대한 [알림](/ko/clickstack/features/alerts)을 설정합니다
* 보다 포괄적인 Kafka 모니터링을 위해 [Kafka 메트릭](/ko/clickstack/integration-examples/kafka-metrics)과 함께 사용합니다
* 특정 사용 사례(컨트롤러 이벤트, 파티션 재할당)를 위한 추가 [대시보드](/ko/clickstack/features/dashboards/overview)를 생성합니다

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

이 가이드는 빠르게 설정할 수 있도록 ClickStack에 내장된 OpenTelemetry Collector를 기반으로 작성되었습니다. 프로덕션 배포에서는 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 방식을 권장합니다. 프로덕션용 구성은 [OpenTelemetry 데이터 전송](/ko/clickstack/ingesting-data/opentelemetry)을 참조하십시오.