ClickStack으로 JVM 메트릭 모니터링

ClickStack으로 JVM 모니터링

핵심 요약

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

​

기존 JVM 애플리케이션과의 통합

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

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

필수 조건

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

1. ​

   ClickStack API Key 가져오기

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

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

   OpenTelemetry Java agent 다운로드

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

   curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar
   

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

3. ​

   JVM 시작 인수 구성

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

   옵션 1: 명령줄 플래그

   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: 환경 변수

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

   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 파일 이름

   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
4. ​

   HyperDX에서 메트릭 확인

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

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

​

데모 데이터세트

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

1. ​

   샘플 데이터세트 다운로드

   # 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 사용률 패턴
2. ​

   ClickStack 시작

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

   docker run -d --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

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

3. ​

   데모 데이터세트 가져오기

   # 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의 메트릭 테이블에 직접 가져옵니다.

4. ​

   데모 데이터 확인

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

   1. 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을 검색합니다

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

   시간대 표시

   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시간으로 좁힐 수 있습니다.

​

대시보드 및 시각화

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

1. ​

   대시보드 구성 파일

2. ​

   사전 구축된 대시보드 가져오기

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

   3. jvm-metrics-dashboard.json 파일을 업로드한 다음 Finish Import를 클릭합니다
3. ​

   대시보드 보기

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

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

​

문제 해결

​

agent가 시작되지 않는 경우

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

ls -lh /path/to/opentelemetry-javaagent.jar

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

java -version

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

[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started

​

HyperDX에 메트릭이 표시되지 않을 때

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

docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics

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

# 환경 변수를 사용하는 경우 다음을 확인하세요:
echo $OTEL_METRICS_EXPORTER
# 예상 출력: otlp

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

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

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

​

다음 단계

• 힙 사용량 증가, 빈번한 GC 일시 중지, 스레드 고갈 등 중요한 메트릭에 대해 알림을 설정하세요
• 관측성 데이터를 통합할 수 있는 다른 ClickStack 통합도 살펴보세요

​

프로덕션 환경으로 전환

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

프로덕션 배포 패턴과 collector 구성 예시는 OpenTelemetry로 수집하기를 참조하십시오.