> ## 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으로 JVM 메트릭 모니터링

> ClickStack으로 JVM 모니터링

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>
  **핵심 요약**

  OpenTelemetry Java agent를 사용해 ClickStack에서 JVM 애플리케이션을 모니터링합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함되어 있습니다.
</Info>

<div id="existing-jvm">
  ## 기존 JVM 애플리케이션과의 통합
</div>

이 섹션에서는 OpenTelemetry Java agent를 사용해 기존 JVM 애플리케이션이 ClickStack으로 메트릭을 전송하도록 구성하는 방법을 설명합니다.

프로덕션 환경을 구성하기 전에 통합을 테스트하려면 [데모 데이터세트 섹션](#demo-dataset)의 데모 데이터세트를 사용할 수 있습니다.

<div id="prerequisites">
  ##### 필수 조건
</div>

* 실행 중인 ClickStack 인스턴스
* 기존 Java 애플리케이션(Java 8+)
* JVM 시작 인수를 수정할 수 있는 권한

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

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

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

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

  <Step>
    #### OpenTelemetry Java agent 다운로드

    OpenTelemetry Java agent JAR 파일을 다운로드하십시오:

    ```bash theme={null}
    curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar
    ```

    이 명령은 agent를 현재 디렉터리에 다운로드합니다. 배포 환경에 맞는 위치(예: `/opt/opentelemetry/` 또는 애플리케이션 JAR와 같은 위치)에 둘 수 있습니다.
  </Step>

  <Step>
    #### JVM 시작 인수 구성

    JVM 시작 명령에 Java agent를 추가하십시오. agent는 JVM 메트릭을 자동으로 수집해 ClickStack으로 전송합니다.

    ##### 옵션 1: 명령줄 플래그

    ```bash theme={null}
    java -javaagent:opentelemetry-javaagent.jar \
      -Dotel.service.name=my-java-app \
      -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
      -Dotel.exporter.otlp.protocol=http/protobuf \
      -Dotel.exporter.otlp.headers="authorization=YOUR_API_KEY" \
      -Dotel.metrics.exporter=otlp \
      -Dotel.logs.exporter=none \
      -Dotel.traces.exporter=none \
      -jar my-application.jar
    ```

    **다음을 바꾸십시오:**

    * `opentelemetry-javaagent.jar` → agent JAR의 전체 경로(예: `/opt/opentelemetry/opentelemetry-javaagent.jar`)
    * `my-java-app` → 서비스를 식별할 수 있는 이름(예: `payment-service`, `user-api`)
    * `YOUR_API_KEY` → 위 단계에서 복사한 ClickStack API Key
    * `my-application.jar` → 애플리케이션의 JAR 파일 이름
    * `http://localhost:4318` → ClickStack 엔드포인트(ClickStack이 같은 머신에서 실행 중이면 `localhost:4318`을 사용하고, 그렇지 않으면 `http://your-clickstack-host:4318`을 사용하십시오)

    ##### 옵션 2: 환경 변수

    또는 환경 변수를 사용하십시오:

    ```bash theme={null}
    export JAVA_TOOL_OPTIONS="-javaagent:opentelemetry-javaagent.jar"
    export OTEL_SERVICE_NAME="my-java-app"
    export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
    export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
    export OTEL_EXPORTER_OTLP_HEADERS="authorization=YOUR_API_KEY"
    export OTEL_METRICS_EXPORTER="otlp"
    export OTEL_LOGS_EXPORTER="none"
    export OTEL_TRACES_EXPORTER="none"

    java -jar my-application.jar
    ```

    **다음을 바꾸십시오:**

    * `opentelemetry-javaagent.jar` → agent JAR의 전체 경로
    * `my-java-app` → 서비스 이름
    * `YOUR_API_KEY` → ClickStack API Key
    * `http://localhost:4318` → ClickStack 엔드포인트
    * `my-application.jar` → 애플리케이션의 JAR 파일 이름

    <Tip>
      OpenTelemetry Java agent는 다음 JVM 메트릭을 자동으로 수집합니다:

      * **메모리**: `jvm.memory.used`, `jvm.memory.limit`, `jvm.memory.committed`, `jvm.memory.used_after_last_gc`
      * **가비지 컬렉션**: `jvm.gc.duration`
      * **스레드**: `jvm.thread.count`
      * **클래스**: `jvm.class.count`, `jvm.class.loaded`, `jvm.class.unloaded`
      * **CPU**: `jvm.cpu.time`, `jvm.cpu.count`
    </Tip>
  </Step>

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

    애플리케이션이 agent와 함께 실행되면 메트릭이 ClickStack으로 전송되는지 확인하십시오:

    1. [http://localhost:8080에서](http://localhost:8080에서) HyperDX를 여십시오(또는 ClickStack URL 사용)
    2. **Chart Explorer**로 이동하십시오
    3. `jvm.`로 시작하는 메트릭을 검색하십시오(예: `jvm.memory.used`, `jvm.gc.duration`, `jvm.thread.count`)
  </Step>
</Steps>

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

애플리케이션에 계측을 추가하기 전에 JVM 메트릭 통합을 테스트하려는 사용자를 위해, 안정적으로 중간 수준의 트래픽이 발생하는 중간 규모 마이크로서비스의 실제 JVM 동작을 보여주는 사전 생성 메트릭이 포함된 샘플 데이터세트를 제공합니다.

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

    ```bash theme={null}
    # Gauge 메트릭 다운로드(메모리, 스레드, CPU, 클래스)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-gauge.jsonl

    # Sum 메트릭 다운로드(GC 이벤트)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-sum.jsonl
    ```

    데이터세트에는 다음을 보여주는 24시간 분량의 JVM 메트릭이 포함되어 있습니다:

    * 주기적인 가비지 컬렉션 이벤트와 함께 증가하는 힙 메모리
    * 스레드 수 변화
    * 실제와 유사한 GC 일시 중지 시간
    * 클래스 로딩 활동
    * CPU 사용률 패턴
  </Step>

  <Step>
    #### ClickStack 시작

    아직 ClickStack을 실행 중이 아니라면 다음을 실행합니다:

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

    ClickStack이 완전히 시작될 때까지 잠시 기다리세요.
  </Step>

  <Step>
    #### 데모 데이터세트 가져오기

    ```bash theme={null}
    # Gauge 메트릭 가져오기(메모리, 스레드, CPU, 클래스)
    docker exec -i clickstack clickhouse-client --query="
      INSERT INTO default.otel_metrics_gauge FORMAT JSONEachRow
    " < jvm-metrics-gauge.jsonl

    # Sum 메트릭 가져오기(GC 이벤트)
    docker exec -i clickstack clickhouse-client --query="
      INSERT INTO default.otel_metrics_sum FORMAT JSONEachRow
    " < jvm-metrics-sum.jsonl
    ```

    이 명령은 메트릭을 ClickStack의 메트릭 테이블에 직접 가져옵니다.
  </Step>

  <Step>
    #### 데모 데이터 확인

    가져오기가 완료되면 다음을 수행합니다:

    1. [http://localhost:8080](http://localhost:8080) 에서 HyperDX를 열고 로그인합니다(필요한 경우 계정을 생성합니다)
    2. 검색 view로 이동한 다음 source를 **Metrics**로 설정합니다
    3. 시간 범위를 **2025-12-06 14:00:00 - 2025-12-09 14:00:00**으로 설정합니다
    4. `jvm.memory.used` 또는 `jvm.gc.duration`을 검색합니다

    데모 서비스의 메트릭이 표시되어야 합니다.

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

      HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 **2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC)** 기간을 포함합니다. 위치와 관계없이 데모 메트릭이 표시되도록 시간 범위를 **2025-12-06 14:00:00 - 2025-12-09 14:00:00**으로 설정하세요. 메트릭이 표시되면 더 명확한 시각화를 위해 범위를 24시간으로 좁힐 수 있습니다.
    </Info>
  </Step>
</Steps>

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

ClickStack에서 JVM 애플리케이션을 모니터링할 수 있도록, JVM 메트릭에 필요한 핵심 시각화가 포함된 사전 구축된 대시보드를 제공합니다.

<Steps>
  <Step>
    #### <TrackedLink href={'/ko/examples/jvm-metrics-dashboard.json'} download="jvm-metrics-dashboard.json" eventName="docs.kafka_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. `jvm-metrics-dashboard.json` 파일을 업로드한 다음 **Finish Import**를 클릭합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/jvm/jvm-metrics-import.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=2da97fd75c37000148a373eebdc8229d" alt="가져오기 완료" width="3812" height="1902" data-path="images/clickstack/jvm/jvm-metrics-import.png" />
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/jvm/jvm-metrics-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=4583d1e14923d5c03cb7082386e824a9" alt="Kafka 메트릭 대시보드" width="3812" height="1902" data-path="images/clickstack/jvm/jvm-metrics-dashboard.png" />

    <Note>
      데모 데이터세트의 경우 시간 범위를 \*\*2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC)\*\*로 설정하십시오. 로컬 시간대에 맞게 조정하십시오.
    </Note>
  </Step>
</Steps>

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

<div id="troubleshooting-not-loading">
  ### agent가 시작되지 않는 경우
</div>

**agent JAR 파일이 있는지 확인하세요:**

```bash theme={null}
ls -lh /path/to/opentelemetry-javaagent.jar
```

**Java 버전 호환성을 확인하세요(Java 8 이상 필요):**

```bash theme={null}
java -version
```

**agent 시작 로그 메시지가 있는지 확인하세요:**
애플리케이션이 시작되면 다음과 같은 내용이 표시되어야 합니다:

```text theme={null}
[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started
```

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

**ClickStack이 실행 중이고 접근할 수 있는지 확인하십시오:**

```bash theme={null}
docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics
```

**메트릭 익스포터가 구성되었는지 확인하세요:**

```bash theme={null}
# 환경 변수를 사용하는 경우 다음을 확인하세요:
echo $OTEL_METRICS_EXPORTER
# 예상 출력: otlp
```

**애플리케이션 로그에서 OpenTelemetry 오류를 확인하세요:**
애플리케이션 로그에서 OpenTelemetry 또는 OTLP 내보내기 실패와 관련된 오류 메시지가 있는지 살펴보세요.

**네트워크 연결을 확인하세요:**
ClickStack이 원격 호스트에 있는 경우 애플리케이션 서버에서 4318 포트에 접근할 수 있는지 확인하세요.

**agent 버전을 확인하세요:**
최신 안정 agent 버전(현재 2.22.0)을 사용하고 있는지 확인하세요. 최신 버전에는 성능 개선이 포함되는 경우가 많습니다.

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

* 힙 사용량 증가, 빈번한 GC 일시 중지, 스레드 고갈 등 중요한 메트릭에 대해 [알림](/ko/clickstack/features/alerts)을 설정하세요
* 관측성 데이터를 통합할 수 있는 [다른 ClickStack 통합](/ko/clickstack/integration-examples/index)도 살펴보세요

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

이 가이드는 로컬 테스트를 위해 OpenTelemetry Java agent를 구성하는 방법을 설명합니다. 프로덕션 배포에서는 관리가 더 쉽도록 컨테이너 이미지에 agent JAR를 포함하고 환경 변수를 통해 구성하십시오. JVM 인스턴스가 많은 대규모 환경에서는 ClickStack으로 직접 전송하는 대신 중앙 집중식 OpenTelemetry Collector를 배포하여 여러 애플리케이션의 메트릭을 일괄 처리해 전달하십시오.

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