Java 애플리케이션 트레이싱 (Tracing Java Applications)

원문 보기 위키 갱신 2026.10.05

Java 애플리케이션에 Datadog Java SDK(dd-java-agent)를 설치하고 JVM에 추가해 트레이스를 Datadog으로 보내는 방법이에요. 자동 계측과 주요 구성 옵션을 다룹니다.

출처: 문서

본문

호환성 요구사항 (Compatibility requirements)

최신 Java 트레이서는 버전 8 이상의 모든 JVM을 지원해요. 8 미만 JVM 버전에 대한 추가 정보는 지원되는 JVM 런타임을 읽어보세요.

Datadog의 Java 버전·프레임워크 지원(레거시·유지보수 버전 포함) 전체 목록은 호환성 요구사항을 읽어보세요.

시작하기 (Getting started)

시작하기 전에 Agent를 이미 설치·구성했는지 확인하세요.

애플리케이션 계측하기 (Instrument your application)

Datadog Agent를 설치·구성한 다음 단계는 애플리케이션에 SDK를 직접 추가해 계측하는 거예요. 호환성 정보에 대해 더 알아보세요.

애플리케이션 트레이싱을 시작하려면:

최신 트레이서 클래스 파일이 담긴 dd-java-agent.jar를 Datadog 사용자가 접근할 수 있는 폴더에 다운로드하세요.

Wget:

wget -O dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'

cURL:

curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'

Dockerfile:

ADD 'https://dtdg.co/latest-java-tracer' dd-java-agent.jar

참고: 특정 메이저 버전의 최신 빌드를 다운로드하려면 X가 원하는 메이저 버전인 https://dtdg.co/java-tracer-vX 링크를 사용하세요. 예를 들어 최신 버전 1 빌드에는 https://dtdg.co/java-tracer-v1을 사용해요. 마이너 버전 번호는 포함하면 안 돼요. 특정 버전은 Datadog의 Maven 저장소에서도 확인할 수 있어요.

참고: Release Candidate 버전은 GitHub DataDog/dd-trace-java releases에서 제공돼요. 이들은 버전에 "RC"가 있고 프로덕션 환경 밖 테스트에 권장돼요. 새 Release Candidate 테스트가 가능할 때 알려면 GitHub 릴리스 알림을 구독할 수 있어요. Release Candidate에 문제가 있으면 Datadog 지원에 문의하세요.

Continuous Profiler, 배포 추적, 로그 주입(로그를 Datadog으로 보내는 경우)과 함께 IDE, Maven·Gradle 애플리케이션 스크립트, 또는 java -jar 명령으로 앱을 실행하려면 해당되는 경우 -javaagent JVM 인자와 다음 구성 옵션을 추가하세요.

java -javaagent:/path/to/dd-java-agent.jar -Ddd.profiling.enabled=true -Ddd.logs.injection=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar

참고: 이미지 크기를 줄이기 위해 모듈을 생략해야 하는 강한 필요가 있다면 의존성을 식별하는 데 jdeps 명령을 사용할 수 있어요. 그러나 필요한 모듈은 시간이 지나며 바뀔 수 있으므로 이는 본인 책임 하에 하세요.

참고: Java 24+에서 SDK를 실행하면 JNI 네이티브 접근 관련 경고가 보일 수 있어요. --enable-native-access=ALL-UNNAMED 플래그를 추가해 이 경고를 억제하세요. 자세한 내용은 JEP 472를 참고하세요.

프로파일링을 활성화하면 APM 번들에 따라 비용에 영향을 줄 수 있어요. 자세한 내용은 가격 페이지를 참고하세요.

환경 변수	System Property	설명
`DD_ENV`	`dd.env`	애플리케이션 환경(`production`, `staging` 등)
`DD_LOGS_INJECTION`	`dd.logs.injection`	Datadog 트레이스·스팬 ID용 자동 MDC 키 주입을 활성화해요. 자세한 내용은 고급 사용법을 참고하세요. 버전 1.18.3부터, 이 서비스가 실행되는 곳에서 Agent Remote Configuration이 활성화되어 있으면 Catalog UI에서 `DD_LOGS_INJECTION`을 설정할 수 있어요.
`DD_PROFILING_ENABLED`	`dd.profiling.enabled`	Continuous Profiler를 활성화해요.
`DD_SERVICE`	`dd.service`	같은 작업을 하는 프로세스 집합의 이름. 애플리케이션 통계를 그룹화하는 데 사용돼요.
`DD_TRACE_SAMPLE_RATE`	`dd.trace.sample.rate`	모든 서비스의 트레이스 루트에서 샘플링 비율을 설정해요. 버전 1.18.3부터, 이 서비스가 실행되는 곳에서 Agent Remote Configuration이 활성화되어 있으면 Catalog UI에서 `DD_TRACE_SAMPLE_RATE`를 설정할 수 있어요.
`DD_TRACE_SAMPLING_RULES`	`dd.trace.sampling.rules`	지정된 규칙에 일치하는 서비스의 트레이스 루트에서 샘플링 비율을 설정해요.
`DD_VERSION`	`dd.version`	애플리케이션 버전(예: `2.5`, `202003181415`, `1.3-alpha`)

추가 구성 옵션은 아래에 설명돼요.

JVM에 Java SDK 추가하기

-javaagent와 기타 JVM 인자를 올바르게 전달하는 방법은 애플리케이션 서버 문서를 참고하세요. 자주 사용되는 일부 프레임워크의 지침은 다음과 같아요.

Spring Boot: 앱 이름이 my_app.jar라면 다음을 포함한 my_app.conf를 만드세요.

JAVA_OPTS=-javaagent:/path/to/dd-java-agent.jar

자세한 내용은 Spring Boot 문서를 참고하세요.

Tomcat: Linux — Linux에서 Tomcat을 실행할 때 트레이싱을 활성화하려면:

Tomcat 시작 스크립트 파일(예: setenv.sh)을 여세요.

setenv.sh에 다음을 추가하세요.

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/dd-java-agent.jar"

Windows (Tomcat을 Windows 서비스로) — Tomcat을 Windows 서비스로 실행할 때 트레이싱을 활성화하려면:

Tomcat 프로젝트 폴더의 ./bin 디렉터리에 있는 "tomcat@VERSION_[email protected]" 유지보수 유틸리티를 여세요.
Java 탭으로 이동해 Java Options에 다음을 추가하세요.

-javaagent:C:\path\to\dd-java-agent.jar

변경 사항 적용을 위해 Tomcat 서비스를 다시 시작하세요.

JBoss:

standalone 모드에서:

standalone.conf 끝에 다음 줄을 추가하세요.

JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/dd-java-agent.jar"

standalone 모드·Windows에서 standalone.conf.bat 끝에 다음 줄을 추가하세요.

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/path/to/dd-java-agent.jar"

domain 모드에서:

파일 domain.xml의 server-groups.server-group.jvm.jvm-options 태그 아래에 다음 줄을 추가하세요.

<option value="-javaagent:/path/to/dd-java-agent.jar"/>

자세한 내용은 JBoss 문서를 참고하세요.

Jetty: jetty.sh로 Jetty를 서비스로 시작한다면 다음을 추가하도록 편집하세요.

JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/dd-java-agent.jar"

start.ini로 Jetty를 시작한다면 다음 줄을 추가하세요(--exec 아래에, 또는 없으면 --exec 줄을 추가).

-javaagent:/path/to/dd-java-agent.jar

WebSphere: 관리 콘솔에서:

Servers를 선택하세요. Server Type 아래에서 WebSphere application servers를 선택하고 서버를 선택하세요.
Java and Process Management > Process Definition을 선택하세요.
Additional Properties 섹션에서 Java Virtual Machine을 클릭하세요.
Generic JVM arguments 텍스트 필드에 다음을 입력하세요.

-javaagent:/path/to/dd-java-agent.jar

추가 세부 정보와 옵션은 WebSphere 문서를 참고하세요.

참고

java -jar 명령에 -javaagent 인자를 추가한다면, 애플리케이션 인자가 아니라 JVM 옵션으로 -jar 인자 앞에 추가해야 해요. 예를 들어:
```
java -javaagent:/path/to/dd-java-agent.jar -jar my_app.jar
```

자세한 내용은 Oracle 문서를 참고하세요.

dd-java-agent를 클래스패스에 절대 추가하지 마세요. 예기치 않은 동작을 유발할 수 있어요.

자동 계측 (Automatic instrumentation)

Java의 자동 계측은 JVM이 제공하는 java-agent 계측 기능을 사용해요. java-agent가 등록되면 클래스 파일을 로드 시점에 수정할 수 있어요.

참고: 원격 ClassLoader로 로드된 클래스는 자동으로 계측되지 않아요.

계측은 자동 계측, OpenTracing API, 또는 둘의 혼합에서 올 수 있어요. 계측은 일반적으로 다음 정보를 포착해요.

OpenTracing API에서 타임스탬프가 제공되지 않는 한 JVM의 NanoTime 클럭으로 타이밍 기간을 포착해요.
키/값 태그 쌍.
애플리케이션이 처리하지 않은 오류와 스택 트레이스.
시스템을 통과하는 트레이스(요청)의 총 개수.

구성 (Configuration)

필요하다면 Unified Service Tagging 설정을 포함해 원하는 대로 애플리케이션 성능 텔레메트리 데이터를 보내도록 SDK를 구성하세요. 자세한 내용은 라이브러리 구성을 읽어보세요.

원격 구성 (Remote configuration)

Remote Configuration을 사용하면 Datadog Agent가 애플리케이션 재시작 없이 트레이싱 설정을 동적으로 구성할 수 있어요. 기본적으로 Remote Configuration은 활성화되어 있어요. 비활성화하려면 환경 변수를 설정하세요.

DD_REMOTE_CONFIG_ENABLED=false

또는 JVM 시스템 속성을 추가하세요.

-Ddd.remote_config.enabled=false

더 알아보기 (Learn more)

도움이 되는 추가 문서, 링크, 글: