> ## 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의 로컬 및 시스템 데이터와 메트릭 시작하기

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

이 시작하기 가이드를 통해 시스템의 로컬 로그와 메트릭을 수집해 ClickStack으로 전송하고, 이를 시각화하고 분석할 수 있습니다.

**이 예시는 OSX 및 Linux 시스템에서만 사용할 수 있습니다**

<Tabs>
  <Tab title="Managed ClickStack">
    이 가이드는 [Managed ClickStack 시작하기 가이드](/ko/clickstack/deployment/managed)를 완료하고 [연결 자격 증명을 기록](/ko/clickstack/getting-started/managed#next-steps)해 두었음을 전제로 합니다.

    <Steps>
      <Step>
        ### 사용자 지정 OpenTelemetry 구성 생성

        다음 내용을 포함한 `custom-local-config.yaml` 파일을 생성하세요:

        ```yaml theme={null}
        receivers:
          filelog:
            include:
              - /host/var/log/**/*.log        # 호스트에서 수집한 Linux 로그
              - /host/var/log/syslog
              - /host/var/log/messages
              - /host/private/var/log/*.log   # 호스트에서 수집한 macOS 로그
            start_at: beginning
            resource:
              service.name: "system-logs"

          hostmetrics:
            collection_interval: 1s
            scrapers:
              cpu:
                metrics:
                  system.cpu.time:
                    enabled: true
                  system.cpu.utilization:
                    enabled: true
              memory:
                metrics:
                  system.memory.usage:
                    enabled: true
                  system.memory.utilization:
                    enabled: true
              filesystem:
                metrics:
                  system.filesystem.usage:
                    enabled: true
                  system.filesystem.utilization:
                    enabled: true
              paging:
                metrics:
                  system.paging.usage:
                    enabled: true
                  system.paging.utilization:
                    enabled: true
                  system.paging.faults:
                    enabled: true
              disk:
              load:
              network:
              processes:

        service:
          pipelines:
            logs/local:
              receivers: [filelog]
              processors:
                - memory_limiter
                - batch
              exporters:
                - clickhouse
            metrics/hostmetrics:
              receivers: [hostmetrics]
              processors:
                - memory_limiter
                - batch
              exporters:
                - clickhouse
        ```

        이 구성은 OSX 및 Linux 시스템의 시스템 로그와 메트릭을 수집하여 결과를 ClickStack으로 전송합니다. 이 구성은 새로운 수신기와 파이프라인을 추가해 ClickStack collector를 확장합니다. 기본 ClickStack collector에 이미 구성되어 있는 기존 `clickhouse` exporter와 processor(`memory_limiter`, `batch`)를 참조합니다.

        <Info>
          **수집 타임스탬프**

          이 구성은 수집 시점에 타임스탬프를 조정하여 각 이벤트에 갱신된 시간 값을 할당합니다. 정확한 이벤트 시간이 유지되도록 하려면, OTel processor 또는 연산자를 사용해 로그 파일의 [타임스탬프를 전처리하거나 파싱](/ko/clickstack/ingesting-data/collector#processing-filtering-transforming-enriching)하는 것이 가장 좋습니다.

          이 예시 설정에서는 수신기 또는 파일 processor가 파일의 시작부터 읽도록 구성된 경우, 기존의 모든 로그 항목에 동일한 조정된 타임스탬프가 할당됩니다. 즉, 원래 이벤트 시간이 아니라 처리 시점의 시간이 할당됩니다. 이후 파일에 추가되는 새 이벤트에는 실제 생성 시각에 가까운 타임스탬프가 부여됩니다.

          이러한 동작을 피하려면 수신기 구성에서 시작 위치를 `end`로 설정할 수 있습니다. 이렇게 하면 새 항목만 수집되며 실제 도착 시간에 가까운 타임스탬프가 지정됩니다.
        </Info>

        OpenTelemetry (OTel) 구성 구조에 대한 자세한 내용은 [공식 가이드](https://opentelemetry.io/docs/collector/configuration/)를 참고하십시오.
      </Step>

      <Step>
        ### OpenTelemetry collector 시작하기

        다음 명령으로 독립 실행형 collector를 실행합니다:

        ```shell theme={null}
        docker run -d \
          -p 4317:4317 -p 4318:4318 \
          --user 0:0 \
          -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
          -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
          -e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
          -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
          -v "$(pwd)/custom-local-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
          -v /var/log:/host/var/log:ro \
          -v /private/var/log:/host/private/var/log:ro \
          clickhouse/clickstack-otel-collector:latest
        ```

        collector는 즉시 로컬 시스템 로그와 메트릭을 수집하기 시작합니다.
      </Step>

      <Step>
        ### 서비스를 선택하세요

        ClickHouse Cloud 메인 랜딩 페이지에서 Managed ClickStack이 포함된 서비스를 선택하세요.

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/_TDydWLKO6Z3njo9/images/clickstack/select_service.png?fit=max&auto=format&n=_TDydWLKO6Z3njo9&q=85&s=5a981e65294c5e4831352fb4ac556338" alt="서비스 선택" size="lg" width="3600" height="2040" data-path="images/clickstack/select_service.png" />
      </Step>

      <Step>
        ### 시스템 logs 탐색

        왼쪽 메뉴에서 `ClickStack`을 선택하면 ClickStack UI로 이동하며 자동으로 인증됩니다.

        검색 UI에 로컬 시스템 logs가 표시되어야 합니다. 필터를 펼쳐 `system.log`를 선택하십시오:

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-20.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=810a5e8ebb0ee2178a32ff1082feadaa" alt="HyperDX 로컬 로그" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-20.png" />
      </Step>

      <Step>
        ### 시스템 메트릭 탐색

        차트를 사용해 메트릭을 살펴볼 수 있습니다.

        왼쪽 메뉴에서 Chart Explorer로 이동합니다. source로 `Metrics`를 선택하고 집계 유형으로 `Maximum`을 선택합니다.

        `Select a Metric` 메뉴에서 `memory`를 입력한 다음 `system.memory.utilization (Gauge)`를 선택합니다.

        시간 경과에 따른 메모리 사용률을 시각화하려면 `Run` 버튼을 누르십시오.

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-21.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=6e2f40c61b0f7355874e734728b2c21f" alt="시간 경과에 따른 메모리" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-21.png" />

        값은 부동소수점 `%`로 반환됩니다. 더 명확하게 표시하려면 `Set number format`을 선택합니다.

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-22.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=631cd0d3fd6ac046e01e5db680ba684b" alt="숫자 형식" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-22.png" />

        다음 메뉴에서 `Output format` 드롭다운에서 `Percentage`를 선택한 후 `Apply`를 클릭합니다.

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-23.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=550224322fc52a8a8eddbbb15928ac07" alt="시간에 따른 메모리 %" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-23.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="ClickStack Open Source">
    ### 사용자 정의 OpenTelemetry 구성 만들기

    다음 내용으로 `custom-local-config.yaml` 파일을 생성하십시오.

    ```yaml theme={null}
    receivers:
      filelog:
        include:
          - /host/var/log/**/*.log        # 호스트의 Linux 로그
          - /host/var/log/syslog
          - /host/var/log/messages
          - /host/private/var/log/*.log   # 호스트의 macOS 로그
        start_at: beginning
        resource:
          service.name: "system-logs"

      hostmetrics:
        collection_interval: 1s
        scrapers:
          cpu:
            metrics:
              system.cpu.time:
                enabled: true
              system.cpu.utilization:
                enabled: true
          memory:
            metrics:
              system.memory.usage:
                enabled: true
              system.memory.utilization:
                enabled: true
          filesystem:
            metrics:
              system.filesystem.usage:
                enabled: true
              system.filesystem.utilization:
                enabled: true
          paging:
            metrics:
              system.paging.usage:
                enabled: true
              system.paging.utilization:
                enabled: true
              system.paging.faults:
                enabled: true
          disk:
          load:
          network:
          processes:

    service:
      pipelines:
        logs/local:
          receivers: [filelog]
          processors:
            - memory_limiter
            - batch
          exporters:
            - clickhouse
        metrics/hostmetrics:
          receivers: [hostmetrics]
          processors:
            - memory_limiter
            - batch
          exporters:
            - clickhouse
    ```

    이 구성은 OSX 및 Linux 시스템의 시스템 로그와 메트릭을 수집하여 ClickStack으로 전송합니다. 새로운 수신기(receivers)와 파이프라인(pipelines)을 추가하여 ClickStack collector를 확장하며, 기본 ClickStack collector에 이미 구성된 `clickhouse` exporter와 processors(`memory_limiter`, `batch`)를 참조합니다.

    <Info>
      **수집 타임스탬프**

      이 구성은 수집 시점에 타임스탬프를 조정하여 각 이벤트에 갱신된 시간 값을 할당합니다. 정확한 이벤트 시간이 유지되도록 하려면 OTel processor 또는 연산자를 사용해 로그 파일에서 [타임스탬프를 전처리하거나 파싱](/ko/clickstack/ingesting-data/collector#processing-filtering-transforming-enriching)하는 것이 가장 좋습니다.

      이 예시 구성을 사용하면 수신기 또는 파일 processor가 파일의 처음부터 시작하도록 구성된 경우, 기존의 모든 로그 항목에 동일하게 조정된 타임스탬프가 할당됩니다. 즉, 원래 이벤트 시간이 아니라 처리 시점의 시간이 할당됩니다. 이후 파일에 추가되는 새 이벤트에는 실제 생성 시간에 가까운 타임스탬프가 부여됩니다.

      이 동작을 방지하려면 수신기 구성에서 시작 위치를 `end`로 설정할 수 있습니다. 이렇게 하면 새 항목만 수집되고 실제 도착 시간에 가까운 시점으로 타임스탬프가 지정됩니다.
    </Info>

    OpenTelemetry (OTel) 구성 구조에 대한 자세한 내용은 [공식 가이드](https://opentelemetry.io/docs/collector/configuration/)를 참조하십시오.

    ### 사용자 정의 구성으로 ClickStack 시작

    다음 docker 명령을 실행하여 사용자 지정 구성으로 올인원 컨테이너를 시작하세요:

    ```shell theme={null}
    docker run -d --name clickstack \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      --user 0:0 \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/custom-local-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v /var/log:/host/var/log:ro \
      -v /private/var/log:/host/private/var/log:ro \
      clickhouse/clickstack-all-in-one:latest
    ```

    <Info>
      **루트 사용자**

      모든 시스템 로그에 접근하기 위해 collector를 루트 사용자로 실행합니다. 이는 Linux 기반 시스템의 보호된 경로에 있는 로그를 수집하는 데 필요합니다. 하지만 이 방식은 프로덕션 환경에서는 권장되지 않습니다. 프로덕션 환경에서는 OpenTelemetry Collector를 로컬 agent로 배포하고, 의도한 로그 소스에 접근하는 데 필요한 최소한의 권한만 부여해야 합니다.

      또한 컨테이너 자체의 로그 파일과 충돌하지 않도록 호스트의 `/var/log`를 컨테이너 내부의 `/host/var/log`에 마운트합니다.
    </Info>

    ### 시스템 로그 탐색

    로컬에 배포하는 경우 [http://localhost:8080](http://localhost:8080)에 접속하여 ClickStack UI를 확인하십시오.

    데이터 소스는 미리 생성되어 있습니다. 검색 UI에는 로컬 시스템 로그가 표시되어 있습니다. 필터를 펼쳐 `system.log`를 선택하십시오:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-20.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=810a5e8ebb0ee2178a32ff1082feadaa" alt="HyperDX 로컬 로그" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-20.png" />

    ### 시스템 메트릭 탐색

    차트를 활용하여 메트릭을 살펴볼 수 있습니다.

    왼쪽 메뉴에서 Chart Explorer로 이동하십시오. 소스로 `Metrics`를, 집계 유형으로 `Maximum`을 선택하십시오.

    `Select a Metric` 메뉴에서 `system.memory.utilization (Gauge)`를 선택하기 전에 `memory`를 입력하면 됩니다.

    실행 버튼을 눌러 시간에 따른 메모리 사용률을 시각화하십시오.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-21.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=6e2f40c61b0f7355874e734728b2c21f" alt="시간에 따른 메모리" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-21.png" />

    숫자는 부동 소수점 `%`로 반환됩니다. 더 명확하게 표시하려면 `Set number format`을 선택하십시오.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-22.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=631cd0d3fd6ac046e01e5db680ba684b" alt="숫자 형식" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-22.png" />

    이후 메뉴에서 `Output format` 드롭다운에 `Percentage`를 선택한 후 `Apply`를 클릭하십시오.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-23.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=550224322fc52a8a8eddbbb15928ac07" alt="시간 대비 메모리 비율" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-23.png" />
  </Tab>
</Tabs>