> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 로컬 로그 및 메트릭

> ClickStack의 로컬 및 시스템 데이터와 메트릭 시작하기

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

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

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

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

    <Steps>
      <Step title="사용자 정의 OpenTelemetry 구성 만들기" id="create-otel-configuration">
        다음 내용으로 `custom-local-config.yaml` 파일을 생성하십시오.

        ```yaml theme={null}
        receivers:
          filelog:
            include:
              - /host/var/log/**/*.log        # Linux logs from host
              - /host/var/log/syslog
              - /host/var/log/messages
              - /host/private/var/log/*.log   # macOS logs from host
            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 또는 연산자를 사용해 로그 파일의 [타임스탬프를 전처리하거나 파싱](/docs/ko/clickstack/ingesting-data/collector#processing-filtering-transforming-enriching)하는 것이 가장 좋습니다.

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

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

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

      <Step title="OpenTelemetry collector 시작하기" id="start-the-otel-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 title="서비스를 선택하세요" id="select-your-service">
        ClickHouse Cloud 메인 랜딩 페이지에서 Managed ClickStack이 포함된 서비스를 선택하세요.

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

      <Step title="시스템 로그 탐색" id="navigate-to-the-hyperdx-ui">
        왼쪽 메뉴에서 `ClickStack`을 선택하면 ClickStack UI로 이동하며 자동으로 인증됩니다.

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

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

      <Step title="시스템 메트릭 탐색" id="explore-system-metrics">
        차트를 사용해 메트릭을 살펴볼 수 있습니다.

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

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

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

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

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

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

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

        <Image img="https://mintcdn.com/private-7c7dfe99/xE8TEsdF6028Tf3x/images/use-cases/observability/hyperdx-23.webp?fit=max&auto=format&n=xE8TEsdF6028Tf3x&q=85&s=18ad1c73ab48862c6f28ff1032696ee2" alt="시간 대비 메모리 비율" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-23.webp" />
      </Step>
    </Steps>
  </Tab>

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

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

    ```yaml theme={null}
    receivers:
      filelog:
        include:
          - /host/var/log/**/*.log        # Linux logs from host
          - /host/var/log/syslog
          - /host/var/log/messages
          - /host/private/var/log/*.log   # macOS logs from host
        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 또는 연산자를 사용해 로그 파일의 [타임스탬프를 전처리하거나 파싱](/docs/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/xE8TEsdF6028Tf3x/images/use-cases/observability/hyperdx-20.webp?fit=max&auto=format&n=xE8TEsdF6028Tf3x&q=85&s=8bb054a0e9fe3f40c45dac8ca545f37b" alt="HyperDX 로컬 로그" size="lg" width="4800" height="2700" data-path="images/use-cases/observability/hyperdx-20.webp" />

    ### 시스템 메트릭 탐색

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

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

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

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

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

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

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

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

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