Java 제로 코드 계측¶

Beacon Java는 단일 Agent JAR로 배포됩니다. 에이전트에는 JDK가 지원하는 런타임이 필요하며 Profile에는 JDK 11 이상이 필요합니다. 동일한 JAR에 선택적으로 활성화할 수 있는 Security 기능도 포함되어 있습니다.

연동 전에 공통 설정에 따라 DataKit OpenTelemetry 수집기를 활성화하세요. 아래 명령은 Linux/macOS 셸을 기준으로 하며 애플리케이션과 DataKit이 같은 호스트에 있다고 가정합니다. 서로 다른 호스트나 컨테이너에서는 127.0.0.1을 바꾸고 수신 주소를 조정하세요.

설치¶

Beacon Java 릴리스 페이지에서 전체 Agent JAR을 다운로드하고 현재 디렉터리에 beacon-javaagent.jar로 저장하세요.

시작¶

export OTEL_SERVICE_NAME=my-java-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
java -javaagent:./beacon-javaagent.jar -jar app.jar

-javaagent는 반드시 -jar 또는 애플리케이션 메인 클래스 앞에 지정하고 기존 JVM 및 애플리케이션 인수는 유지하세요.

디버깅 및 진단¶

위의 서비스 이름과 OTLP 설정을 유지한 채 Agent 디버그 로그를 일시적으로 활성화하고 출력을 저장하세요.

OTEL_JAVAAGENT_DEBUG=true \
  java -javaagent:./beacon-javaagent.jar -jar app.jar \
  > beacon-java-debug.log 2>&1

-jar 앞에 JVM 인수 -Dotel.javaagent.debug=true를 추가할 수도 있습니다. JVM 시스템 속성이 해당 환경 변수보다 우선합니다. 로그를 통해 Agent 로드, 계측 대상 일치 및 내보내기 오류를 확인할 수 있습니다.

문제 해결 후 원래 시작 명령으로 복원하세요. 서비스 설정에 이 변수나 JVM 인수를 추가했다면 제거하고 애플리케이션을 재시작하세요.

Profile¶

먼저 DataKit Profile 수집기를 활성화한 뒤 아래 변수를 설정하고 위의 시작 방식을 유지하세요. Profile은 OTLP Trace 주소와 별개의 HTTP 업로드 주소를 사용합니다.

Beacon Java Profile은 실험적 기능이며 기본적으로 비활성화되어 있습니다. Java 11 이상과 JFR을 지원하는 런타임이 필요합니다. 애플리케이션은 Java 제로 코드 가이드의 동일한 -javaagent 명령을 사용합니다.

HTTP로 업로드¶

호환 HTTP 내보내기는 multipart/form-data로 JFR 스냅샷과 메타데이터를 전송합니다.

export OTEL_SERVICE_NAME=my-java-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=datakit
export OTEL_PROFILING_ENDPOINT=http://127.0.0.1:9529/profiling/v1/input
java -javaagent:./beacon-javaagent.jar -jar app.jar

datakit은 현재 호환 내보내기를 선택하는 설정 값입니다. 수신 측은 main.jfr과 event.json이라는 두 multipart 필드를 지원해야 합니다. 기본 스냅샷 주기는 1분입니다.

로컬 JFR 파일에 기록¶

수신 측과 무관하게 검증하려면 file 내보내기를 사용할 수 있습니다.

mkdir -p profiles
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=file
export OTEL_PROFILING_EXPERIMENTAL_FILE_EXPORT_PATH="$PWD/profiles"
java -javaagent:./beacon-javaagent.jar -jar app.jar

profiles/에 .jfr 파일이 생성되는지 확인하세요. 운영 환경에서 활성화하기 전에 디스크 보존 정책을 수립하고 애플리케이션 부하를 적용해 성능 오버헤드를 검증하세요.

선택적 메모리 이벤트¶

export OTEL_PROFILING_MEMORY_ENABLED=true

이 설정은 표준 Profile 템플릿에 메모리 분석용 JFR 설정을 추가합니다.

파라미터 참조¶

환경 변수 이름은 대소문자를 구분합니다. 기간 값은 숫자와 ns, us, ms, s, m, h, d 단위로 지정합니다.

환경 변수	유형 / 허용 값	기본값	설명
`OTEL_PROFILING_ENABLED`	불리언	`false`	JFR Profiler를 활성화합니다.
`OTEL_PROFILING_INTERVAL`	양의 기간	`1m`	JFR 스냅샷 생성 간격.
`OTEL_PROFILING_STARTUP_DELAY`	0 이상의 기간	`0s`	Profile 수집을 시작하기 전 대기 시간.
`OTEL_PROFILING_MAX_AGE`	양의 기간	`5m`	진행 중인 JFR 기록의 최대 데이터 보존 기간.
`OTEL_PROFILING_STACK_DEPTH`	양의 정수	`64`	최대 호출 스택 깊이.
`OTEL_PROFILING_MAX_SIZE`	0 이상의 정수, 바이트	`0`	진행 중인 JFR 기록의 최대 크기. `0`이면 JFR 기본 동작을 따릅니다.
`OTEL_PROFILING_TEMP_DIR`	디렉터리 경로	설정되지 않음	JFR 임시 데이터 디렉터리. 설정하지 않으면 런타임의 임시 디렉터리 동작을 따릅니다.
`OTEL_PROFILING_MEMORY_ENABLED`	불리언	`false`	메모리 분석 중심의 JFR 설정을 활성화합니다.
`OTEL_PROFILING_MEMORY_ALLOCATION_SAMPLING`	불리언	설정되지 않음	설정하면 JFR 메모리 할당 샘플링 활성화 설정을 덮어씁니다.
`OTEL_PROFILING_MEMORY_OLD_OBJECT_SAMPLING`	불리언	설정되지 않음	설정하면 JFR 장수명 객체 샘플링 활성화 설정을 덮어씁니다.
`OTEL_PROFILING_EXPORTER`	`none`、`file`、`datakit`	`none`	각각 내보내기 없음, 로컬 JFR 파일 기록, 호환 HTTP multipart 내보내기 사용을 의미합니다.
`OTEL_PROFILING_ENDPOINT`	HTTP(S) URL	`http://localhost:9529/profiling/v1/input`	`datakit` 내보내기의 업로드 주소.
`OTEL_PROFILING_DATAKIT_TIMEOUT`	양의 기간	`10s`	호환 내보내기의 HTTP 업로드 제한 시간.
`OTEL_PROFILING_EXPERIMENTAL_FILE_EXPORT_PATH`	디렉터리 경로	`${java.io.tmpdir}/otel-profiles`	`file` 내보내기의 출력 디렉터리.

datakit 값과 해당 제한 시간 변수는 현재 Java Agent에 필요한 호환 식별자이므로 그대로 유지해야 합니다.

Security¶

같은 Agent에서 선택적으로 활성화한 보안 탐지 결과와 런타임 SBOM을 OpenTelemetry Logs로 내보낼 수 있습니다. Java Security 가이드를 참조하세요.

연동 확인¶

지원되는 프레임워크나 라이브러리를 거치는 요청을 애플리케이션 API에 보낸 뒤 Guance의 APM > 트레이스에서 위에 설정한 서비스 이름으로 필터링하세요. 전체 확인 절차는 공통 설정을, 데이터가 없으면 문제 해결을 참조하세요.