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

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

> ClickStack를 사용한 Systemd 및 Journald 로그 모니터링

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>
  **TL;DR**

  OpenTelemetry Collector의 journald 수신기를 사용해 ClickStack에서 systemd journal 로그를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함됩니다.
</Info>

<div id="existing-systems">
  ## 기존 시스템 통합
</div>

OpenTelemetry Collector를 journald 수신기와 함께 실행해 기존 Linux 시스템의 journald 로그를 수집하고, OTLP를 통해 ClickStack으로 전송하여 모니터링할 수 있습니다.

기존 설정을 변경하지 않고 먼저 이 통합을 테스트하려면 [데모 데이터세트 섹션](#demo-dataset)으로 이동하십시오.

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

* 실행 중인 ClickStack 인스턴스
* systemd를 사용하는 Linux 시스템(Ubuntu 16.04+, CentOS 7+, Debian 8+)
* 모니터링 대상 시스템에 Docker 또는 Docker Compose가 설치되어 있어야 합니다

<Steps>
  <Step>
    #### ClickStack API Key 가져오기

    OpenTelemetry Collector는 ClickStack의 OTLP 엔드포인트로 데이터를 전송하며, 이 엔드포인트에는 인증이 필요합니다.

    1. ClickStack URL(예: [http://localhost:8080)에서](http://localhost:8080\)에서) HyperDX를 엽니다
    2. 필요하면 계정을 생성하거나 로그인합니다
    3. **Team Settings → API Keys**로 이동합니다
    4. **수집 API key**를 복사합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/vQMVv9Ng6hRPWQ0d/images/clickstack/api-key.png?fit=max&auto=format&n=vQMVv9Ng6hRPWQ0d&q=85&s=d3451b04e25288d1df17aa2eb35670b7" alt="ClickStack API Key" width="3810" height="1924" data-path="images/clickstack/api-key.png" />

    5. 이를 환경 변수로 설정합니다:

    ```bash theme={null}
    export CLICKSTACK_API_KEY=your-api-key-here
    ```
  </Step>

  <Step>
    #### systemd journal 실행 여부 확인

    시스템에서 systemd를 사용 중이며 journal 로그가 있는지 확인합니다:

    ```bash theme={null}
    # systemd 버전 확인
    systemctl --version

    # 최근 journal 항목 보기
    journalctl -n 20

    # journal 디스크 사용량 확인
    journalctl --disk-usage
    ```

    journal 저장소가 메모리에만 유지되는 경우 영구 저장소를 활성화합니다:

    ```bash theme={null}
    sudo mkdir -p /var/log/journal
    sudo systemd-tmpfiles --create --prefix /var/log/journal
    sudo systemctl restart systemd-journald
    ```
  </Step>

  <Step>
    #### OpenTelemetry Collector 구성 생성

    OpenTelemetry Collector용 설정 파일을 생성합니다:

    ```yaml theme={null}
    cat > otel-config.yaml << 'EOF'
    receivers:
      journald:
        directory: /var/log/journal
        priority: info
        units:
          - sshd
          - nginx
          - docker
          - containerd
          - systemd

    processors:
      batch:
        timeout: 10s
        send_batch_size: 10000
      
      resource:
        attributes:
          - key: service.name
            value: systemd-logs
            action: insert
          - key: host.name
            from_attribute: _HOSTNAME
            action: upsert
      
      attributes:
        actions:
          - key: unit
            from_attribute: _SYSTEMD_UNIT
            action: upsert
          - key: priority
            from_attribute: PRIORITY
            action: upsert

    exporters:
      otlphttp:
        endpoint: ${CLICKSTACK_ENDPOINT}
        headers:
          authorization: ${CLICKSTACK_API_KEY}

    service:
      pipelines:
        logs:
          receivers: [journald]
          processors: [resource, attributes, batch]
          exporters: [otlphttp]
    EOF
    ```
  </Step>

  <Step>
    #### Docker Compose로 배포

    <Note>
      `journald` 수신기는 journal 파일을 읽기 위해 `journalctl` 바이너리가 필요합니다. 공식 `otel/opentelemetry-collector-contrib` 이미지에는 기본적으로 `journalctl`이 포함되어 있지 않습니다.

      컨테이너 환경에 배포하는 경우, collector를 호스트에 직접 설치하거나 systemd 유틸리티가 포함된 사용자 지정 이미지를 빌드할 수 있습니다. 자세한 내용은 [문제 해결 섹션](#journalctl-not-found)을 참조하십시오.
    </Note>

    이 예시는 ClickStack과 함께 OTel Collector를 배포하는 방법을 보여줍니다:

    ```yaml theme={null}
    services:
      clickstack:
        image: clickhouse/clickstack-all-in-one:latest
        ports:
          - "8080:8080"
          - "4317:4317"
          - "4318:4318"
        networks:
          - monitoring
      
      otel-collector:
        image: otel/opentelemetry-collector-contrib:0.115.1
        depends_on:
          - clickstack
        environment:
          - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
          - CLICKSTACK_ENDPOINT=http://clickstack:4318
        volumes:
          - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
          - /var/log/journal:/var/log/journal:ro
          - /run/log/journal:/run/log/journal:ro
          - /etc/machine-id:/etc/machine-id:ro
        command: ["--config=/etc/otelcol/config.yaml"]
        networks:
          - monitoring

    networks:
      monitoring:
        driver: bridge
    ```

    서비스를 시작합니다:

    ```bash theme={null}
    docker compose up -d
    ```
  </Step>

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

    구성이 완료되면 HyperDX에 로그인하여 로그가 수집되는지 확인합니다:

    1. Search view로 이동합니다
    2. source를 Logs로 설정합니다
    3. `service.name:systemd-logs`로 필터링합니다
    4. `unit`, `priority`, `MESSAGE`, `_HOSTNAME` 등의 필드가 포함된 구조화된 로그 항목이 표시되어야 합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/systemd/systemd-search-view.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=162cc2cf97f3caf0a2ca7e2d6749f48a" alt="Log search view" width="3838" height="1934" data-path="images/clickstack/systemd/systemd-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/systemd/systemd-log-view.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=a11f24e2666c78ff6567c6823d280505" alt="Log view" width="3838" height="1934" data-path="images/clickstack/systemd/systemd-log-view.png" />
  </Step>
</Steps>

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

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

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

    샘플 로그 파일을 다운로드하세요:

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

  <Step>
    #### 데모 collector 구성 생성

    데모용 설정 파일을 생성하세요:

    ```bash theme={null}
    cat > systemd-demo.yaml << 'EOF'
    receivers:
      filelog:
        include:
          - /tmp/systemd-demo/systemd-demo.log
        start_at: beginning
        operators:
          - type: regex_parser
            regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
            parse_from: body
            parse_to: attributes
          - type: time_parser
            parse_from: attributes.timestamp
            layout: '%Y-%m-%dT%H:%M:%S%z'
          - type: add
            field: attributes.source
            value: "systemd-demo"

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

  <Step>
    #### 데모 데이터로 ClickStack 실행

    데모 로그와 함께 ClickStack을 시작하세요:

    ```bash theme={null}
    docker run -d --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)/systemd-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v "$(pwd)/systemd-demo.log:/tmp/systemd-demo/systemd-demo.log:ro" \
      clickhouse/clickstack-all-in-one:latest
    ```

    <Note>
      이 데모는 컨테이너에서 `journalctl`이 필요하지 않도록 `journald` 대신 텍스트 로그와 `filelog` 수신기를 사용합니다.
    </Note>
  </Step>

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

    ClickStack이 실행되면 다음을 수행하세요:

    1. [HyperDX](http://localhost:8080/)를 열고 계정에 로그인합니다
    2. Search view로 이동한 다음 source를 `Logs`로 설정합니다
    3. 시간 범위를 **2025-11-14 00:00:00 - 2025-11-17 00:00:00**으로 설정합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/systemd/systemd-search-view.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=162cc2cf97f3caf0a2ca7e2d6749f48a" alt="로그 검색 view" width="3838" height="1934" data-path="images/clickstack/systemd/systemd-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/systemd/systemd-log-view.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=a11f24e2666c78ff6567c6823d280505" alt="로그 view" width="3838" height="1934" data-path="images/clickstack/systemd/systemd-log-view.png" />

    <Info>
      **시간대 표시**

      HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 **2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC)** 기간에 해당합니다. 시간 범위를 넉넉하게 설정했기 때문에 어느 지역에서 접속하더라도 데모 로그를 확인할 수 있습니다.
    </Info>
  </Step>
</Steps>

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

ClickStack으로 systemd 로그 모니터링을 시작할 수 있도록 systemd journal 데이터에 대한 핵심 시각화를 제공합니다.

<Steps>
  <Step>
    #### <TrackedLink href={'/ko/examples/systemd-logs-dashboard.json'} download="systemd-logs-dashboard.json" eventName="docs.systemd_logs_monitoring.dashboard_download">다운로드</TrackedLink>할 대시보드 구성 파일
  </Step>

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

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

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/systemd/finish-import-systemd.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=1eae9ab82fd5afdefa48a83ac0bd75a7" alt="가져오기 완료" width="3350" height="1908" data-path="images/clickstack/systemd/finish-import-systemd.png" />
  </Step>

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

    대시보드에는 다음 시각화가 포함되어 있습니다:

    * 시간에 따른 로그량
    * 로그 수 기준 상위 systemd 유닛
    * SSH 인증 이벤트
    * 서비스 실패
    * 오류율

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/systemd/systemd-logs-dashboard.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=3e45947e32179b01c118aeba44c81085" alt="예시 대시보드" width="3808" height="1908" data-path="images/clickstack/systemd/systemd-logs-dashboard.png" />

    <Note>
      데모 데이터세트에서는 시간 범위를 \*\*2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC)\*\*로 설정한 뒤, 로컬 시간대에 맞게 조정하십시오.
    </Note>
  </Step>
</Steps>

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

<div id="no-logs">
  ### HyperDX에 로그가 표시되지 않는 경우
</div>

로그가 ClickHouse에 수집되고 있는지 확인하세요:

```bash theme={null}
docker exec clickstack clickhouse-client --query "
SELECT COUNT(*) as log_count
FROM otel_logs
WHERE ServiceName = 'systemd-logs'
"
```

결과가 표시되지 않으면 collector 로그를 확인하세요:

```bash theme={null}
docker logs otel-collector | grep -i "error\|journald" | tail -20
```

<div id="journalctl-not-found">
  ### journalctl not found 오류
</div>

`exec: "journalctl": executable file not found in $PATH`가 표시되면 다음과 같이 하십시오:

`otel/opentelemetry-collector-contrib` 이미지에는 `journalctl`이 포함되어 있지 않습니다. 다음 중 하나를 선택할 수 있습니다:

1. **호스트에 collector를 설치하세요**:

```bash theme={null}
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.115.0/otelcol-contrib_0.115.0_linux_amd64.tar.gz
tar -xzf otelcol-contrib_0.115.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/
otelcol-contrib --config=otel-config.yaml
```

2. **텍스트 내보내기 방식을 사용하세요**(데모와 같이). `filelog` 수신기가 journald 내보내기 데이터를 읽도록 구성합니다

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

* 중요한 시스템 이벤트(서비스 장애, 인증 실패, OOM kill)에 대한 [알림](/ko/clickstack/features/alerts)을 설정하세요
* 특정 용도(SSH 보안 모니터링, 서비스 상태)에 맞는 추가 [대시보드](/ko/clickstack/features/dashboards/overview)를 만드세요
* 특정 systemd 유닛으로 필터링하여 노이즈를 줄이고 중요한 서비스에 집중하세요

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

이 가이드에서는 systemd 로그를 읽어 ClickStack의 OTLP 엔드포인트로 전송하기 위해 별도의 OpenTelemetry Collector를 사용하며, 이는 프로덕션 환경에서 권장되는 패턴입니다.

여러 호스트가 있는 프로덕션 환경에서는 다음 사항을 고려하세요.

* Kubernetes에서 collector를 데몬셋으로 배포
* 각 호스트에서 collector를 systemd 서비스로 실행
* 자동 배포를 위해 OpenTelemetry Operator 사용

프로덕션 배포 패턴은 [OpenTelemetry로 수집하기](/ko/clickstack/ingesting-data/opentelemetry)를 참조하십시오.