본문 바로가기
WIKI 기술 지식 베이스

Java 호환성 요구사항 (Java Compatibility Requirements)

원문 보기 위키 갱신

Datadog Java Trace 라이브러리의 호환성 요구사항을 안내해요.

출처: 문서

본문

호환성 (Compatibility)

Java Datadog Trace 라이브러리는 오픈소스예요. 자세한 내용은 GitHub 저장소를 참고하세요.

지원되는 Java 런타임 (Supported Java runtimes)

Java Tracer는 다음 Oracle JDK, OpenJDK JVM, GraalVM 런타임에 대한 자동 계측을 지원해요.

Java Tracer v1 (최신)
Java 버전 운영체제 지원 수준
27 이상 Windows (x86, x86-64) Linux (x86, x86-64, arm64) Mac (x86, x86-64, arm64) Preview
18~26 Windows (x86, x86-64) Linux (x86, x86-64, arm64) Mac (x86, x86-64, arm64) GA
8~17 Windows (x86, x86-64) Linux (x86, x86-64) Mac (x86, x86-64) GA
Linux (arm64) Mac (arm64) Preview

Datadog는 어떤 Java 얼리 액세스 버전도 공식적으로 지원하지 않아요.

Java Tracer v0
Java 버전 운영체제 지원 수준
7만 Windows (x86, x86-64) Linux (x86, x86-64) Mac (x86, x86-64) EOL
7만 Linux (arm64) Mac (arm64) EOL

지원 수준 (Levels of support)

수준 제공되는 지원
미지원 (Unsupported) 구현이 없어요. 특별 요청은 Datadog 지원에 문의하세요.
Preview 초기 구현이에요. 아직 모든 기능을 포함하지 않을 수 있어요. 새 기능과 버그·보안 수정 지원은 최선 노력 기준으로 제공돼요.
GA(General Availability) 모든 기능의 완전한 구현이에요. 새 기능과 버그·보안 수정에 대한 전체 지원을 제공해요.
유지보수 (Maintenance) 기존 기능의 완전한 구현이에요. 새 기능은 받지 않아요. 버그·보안 수정 지원만 제공해요.
EOL(End-of-life) 지원이 없어요.

통합 (Integrations)

Preview 통합은 기본적으로 비활성화되어 있지만 개별적으로 활성화할 수 있어요:

  • 시스템 속성: -Ddd.integration.<INTEGRATION_NAME>.enabled=true
  • 환경 변수: DD_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

웹 프레임워크 호환성 (Web framework compatibility)

dd-java-agent는 다음 웹 프레임워크를 자동으로 트레이싱하는 것을 지원해요.

웹 프레임워크 트레이싱이 제공하는 것:

  • HTTP 요청~응답 타이밍
  • HTTP 요청 태그(상태 코드, 메서드 등)
  • 오류 및 스택트레이스 캡처
  • 웹 요청 내에서 생성된 작업과 분산 트레이싱 연결
서버 버전 지원 유형 계측 이름(구성에 사용)
Akka-Http Server 10.0+ 완전 지원 akka-http, akka-http-server
Apache Pekko 1.0+ 완전 지원 pekko-http, pekko-http-server
Finatra Web 2.9+ 완전 지원 finatra
Grizzly 2.0+ 완전 지원 grizzly
Grizzly-HTTP 2.3.20+ 완전 지원 grizzly-filterchain
Java Servlet Compatible 2.3+, 3.0+ 완전 지원 servlet, servlet-2, servlet-3
Jax-RS Annotations JSR311-API 완전 지원 jax-rs, jaxrs, jax-rs-annotations, jax-rs-filter
Jetty 7.0-12.x 완전 지원 jetty
Micronaut HTTP Server 2.x+ 완전 지원 micronaut
Mulesoft 4.5.0+ 완전 지원 mule
Netty HTTP Server 3.8+ 완전 지원 netty, netty-3.8, netty-4.0, netty-4.1
Play 2.3-2.8 완전 지원 play, play-action
Ratpack 1.5+ 완전 지원 ratpack
Restlet HTTP Server 2.2 - 2.4 완전 지원 restlet-http
Spark Java 2.3+ Preview sparkjava(jetty 필요)
Spring Boot 1.5 - 3.X 완전 지원 spring-web 또는 spring-webflux
Spring Web (MVC) 4.0+ 완전 지원 spring-web
Spring WebFlux 5.0+ 완전 지원 spring-webflux
Tomcat 5.5+ 완전 지원 tomcat
Undertow 2.0+ 완전 지원 undertow
Vert.x 3.4 - 5.x 완전 지원 vertx, vertx-3.4, vertx-3.9, vertx-4.0, vertx-5.0
Websocket (JSR356) 1.0+ Preview websocket

참고: Websphere, Weblogic, JBoss 등 많은 애플리케이션 서버가 Servlet 호환이며 해당 계측으로 자동 처리돼요. 또한 Spring Boot(3버전) 같은 프레임워크는 보통 Tomcat, Jetty, Netty 같은 지원되는 임베디드 애플리케이션 서버를 사용하므로 기본적으로 동작해요.

기본적으로 비활성화된 프레임워크 통합 (Framework Integrations Disabled By Default)

다음 계측은 기본적으로 비활성화되어 있고 다음 설정으로 활성화할 수 있어요:

계측 활성화 방법
Grizzly -Ddd.integration.grizzly-client.enabled=true
Grizzly-HTTP -Ddd.integration.grizzly-filterchain.enabled=true
Hazelcast (클라이언트 측만) -Ddd.integration.hazelcast.enabled=true -Ddd.integration.hazelcast_legacy.enabled=true
Ignite -Ddd.integration.ignite.enabled=true
JAX-WS -Ddd.integration.jax-ws.enabled=true
JDBC Datasource -Ddd.integration.jdbc-datasource.enabled=true
Mulesoft -Ddd.integration.mule.enabled=true
Netty Promise -Ddd.integration.netty-promise.enabled=true
Ning -Ddd.integration.ning.enabled=true
Spark Java -Ddd.integration.sparkjava.enabled=true
TIBCO BusinessWorks -Ddd.integration.tibco.enabled=true
URL Connection -Ddd.integration.urlconnection.enabled=true -Ddd.integration.httpurlconnection.enabled=true
Websocket -Ddd.trace.websocket.messages.enabled=true
ZIO -Ddd.integration.zio.experimental.enabled=true

참고: JAX-WS 통합은 @WebService(JAX-WS 1.x)와 @WebServiceProvider(JAX-WS 2.x)로 주석이 달린 엔드포인트를 계측해요.

원하는 웹 프레임워크가 보이지 않나요? Datadog는 계속 지원을 추가하고 있어요. 도움이 필요하면 Datadog 지원에 문의하세요.

네트워킹 프레임워크 호환성 (Networking framework compatibility)

dd-java-agent는 다음 네트워킹 프레임워크를 자동으로 트레이싱하는 것을 지원해요.

네트워킹 트레이싱이 제공하는 것:

  • 요청~응답 타이밍
  • 요청 태그(예: 응답 코드)
  • 오류 및 스택트레이스 캡처
  • 분산 트레이싱
프레임워크 버전 지원 유형 계측 이름(구성에 사용)
Apache HTTP Client 4.0+ 완전 지원 httpclient, apache-httpclient, apache-http-client
Apache HTTP Async Client 4.0+ 완전 지원 httpasyncclient, apache-httpasyncclient
AWS Java SDK 1.11+, 2.2+ 완전 지원 aws-sdk
Camel-OpenTelemetry 3.12.0+ Preview opentelemetry-1
Commons HTTP Client 2.0+ 완전 지원 commons-http-client
Google HTTP Client 1.19.0+ 완전 지원 google-http-client
Google Pub/Sub 1.116.0+ 완전 지원 google-pubsub
Grizzly HTTP Client 1.9+ Preview grizzly-client
gRPC 1.5+ 완전 지원 grpc, grpc-client, grpc-server
HttpURLConnection all 완전 지원 httpurlconnection, urlconnection
Kafka-Clients 0.11+ 완전 지원 kafka
Kafka-Streams 0.11+ 완전 지원 kafka, kafka-streams
Java RMI all 분산 트레이싱 미지원 rmi, rmi-client, rmi-server
Jax RS Clients 2.0+ 완전 지원 jax-rs, jaxrs, jax-rs-client
Jersey Client 1.9-2.29 완전 지원 jax-rs, jaxrs, jax-rs-client
JMS / Jakarta JMS 1-3.0+ 완전 지원 jms, jms-1, jms-2, jakarta-jms
Netty HTTP Client 4.0+ 완전 지원 netty, netty-4.0, netty-4.1
Ning HTTP Client 1.9.0+ Preview ning
OkHTTP 2.2+ 완전 지원 okhttp, okhttp-2, okhttp-3
Play WSClient 1.0+ 완전 지원 play-ws
Rabbit AMQP 2.7+ 완전 지원 amqp, rabbitmq
SOFA RPC 5.0+ 완전 지원 sofarpc
Spring SessionAwareMessageListener 3.1+ 완전 지원 spring-jms-3.1
Spring WebClient 5.0+ 완전 지원 spring-webflux, spring-webflux-client

Kafka 참고: Datadog의 Kafka 통합은 Header API를 지원하는 Kafka 버전 0.11+에서 동작해요. 이 API는 트레이스 컨텍스트를 주입·추출하는 데 사용돼요. 혼합 버전 환경을 실행 중이라면 Kafka 브로커가 더 새로운 버전의 Kafka를 잘못 보고할 수 있어요. 이로 인해 SDK가 로컬 프로듀서가 지원하지 않는 헤더를 주입하려 할 때 문제가 발생해요. 또한 헤더가 존재하기 때문에 더 오래된 컨슈머는 메시지를 소비할 수 없어요. 이 문제를 방지하려면 0.11보다 오래된 버전의 혼합 버전 Kafka 환경을 실행 중이라면 환경 변수 DD_KAFKA_CLIENT_PROPAGATION_ENABLED=false로 컨텍스트 전파를 비활성화하세요.

JMS 참고: Datadog의 JMS 통합은 컨슈머와 프로듀서 서비스 사이의 컨텍스트 전파를 유지하기 위해 메시지 객체 속성 x__dash__datadog__dash__trace__dash__id와 x__dash__datadog__dash__parent__dash__id를 자동으로 추가·읽어요.

Camel 참고: Camel 라우트를 통한 분산 트레이스 전파는 지원되지 않아요.

SOFA RPC 참고: Datadog의 SOFA RPC 통합은 Bolt, Triple, REST 전송 프로토콜을 지원해요. Triple은 gRPC 전송을 사용하며, Triple 호출의 분산 트레이싱에는 grpc 통합이 활성화된 상태로 유지되어야 해요.

원하는 네트워킹 프레임워크가 보이지 않나요? Datadog는 계속 지원을 추가하고 있어요. 도움이 필요하면 Datadog 지원에 문의하세요.

데이터 저장소 호환성 (Data store compatibility)

dd-java-agent는 다음 데이터베이스 프레임워크/드라이버를 자동으로 트레이싱하는 것을 지원해요.

데이터 저장소 트레이싱이 제공하는 것:

  • 요청~응답 타이밍
  • 쿼리 정보(예: 정리된 쿼리 문자열)
  • 오류 및 스택트레이스 캡처
데이터베이스 버전 지원 유형 계측 이름(구성에 사용)
Aerospike 4.0+ 완전 지원 aerospike
Couchbase 2.0+ 완전 지원 couchbase
Cassandra 3.0+ 완전 지원 cassandra
Elasticsearch Transport 2.0+ 완전 지원 elasticsearch, elasticsearch-transport, elasticsearch-transport-{2,5,6,7}(하나 선택)
Elasticsearch Rest 5.0+ 완전 지원 elasticsearch, elasticsearch-rest, elasticsearch-rest-{5,6,7}(하나 선택)
Ignite 2.0-3.0 Preview ignite
JDBC N/A 완전 지원 jdbc, jdbc-datasource
Jedis 1.4+ 완전 지원 jedis, redis
Lettuce 4.0+ 완전 지원 lettuce, lettuce-4-async, lettuce-5-rx
MongoDB 3.0-4.0+ 완전 지원 mongo
OpenSearch Rest 1.x-2.x 완전 지원 opensearch, opensearch-rest
OpenSearch Transport 1.x-2.x 완전 지원 opensearch, opensearch-transport
RediScala 1.5+ 완전 지원 rediscala, redis
Redisson 2.x-3.x 완전 지원 redisson, redis
SpyMemcached 2.12+ 완전 지원 spymemcached
Vert.x Cassandra Client 3.9-4.x 완전 지원 cassandra
Vert.x Redis Client 3.9-4.x 완전 지원 vertx-redis-client
Vert.x MySQL Client 3.9-4.x 완전 지원 vertx-sql-client

참고: Redis 6.0+는 HELLO, MIGRATE, ACL SETUSER 같은 명령에서 인라인 인증을 지원해요.

  • Datadog Trace Agent: 인증 매개변수가 트레이스 메타데이터에서 자동으로 난독화되도록 보장하는 최소 권장 버전은 7.76.1이에요.
  • Datadog Lambda Extension(서버리스 환경): 최소 필요 버전은 v28.0.0이에요.

dd-java-agent는 다음을 포함한 일반적인 JDBC 드라이버와도 호환돼요:

  • Apache Derby
  • Firebird SQL
  • H2 Database Engine
  • HSQLDB
  • IBM DB2
  • MariaDB
  • MSSQL (Microsoft SQL Server)
  • MySQL
  • Oracle
  • Postgres SQL
  • ScalikeJDBC

기본적으로 비활성화된 데이터베이스 통합 (Database Integrations Disabled By Default)

다음 계측은 기본적으로 비활성화되어 있고 다음 설정으로 활성화할 수 있어요:

계측 활성화 방법
JDBC-Datasource - 시스템 속성: -Ddd.integration.jdbc-datasource.enabled=true - 환경 변수: DD_INTEGRATION_JDBC_DATASOURCE_ENABLED=true

원하는 데이터 저장소가 보이지 않나요? Datadog는 계속 지원을 추가하고 있어요. 도움이 필요하면 Datadog 지원에 문의하세요.

추가 프레임워크 호환성 (Additional framework compatibility)

dd-java-agent는 다음 프레임워크를 자동으로 트레이싱하는 것을 지원해요.

프레임워크 버전 지원 유형 계측 이름(구성에 사용)
Apache CXF (Jax-WS) 3.0+ OpenTelemetry 확장 cxf
Datanucleus JDO 4.0+ 완전 지원 datanucleus
Dropwizard Views 0.7+ 완전 지원 dropwizard, dropwizard-view
GraphQL 14.0+ 완전 지원 graphql-java
Hazelcast (클라이언트) 3.6+ Preview hazelcast, hazelcast_legacy
Hibernate 3.5+ 완전 지원 hibernate, hibernate-core
Hystrix 1.4+ 완전 지원 hystrix
JSP Rendering 2.3+ 완전 지원 jsp, jsp-render, jsp-compile
JUnit 4.1+, 5.3+ 완전 지원 junit, junit-4, junit-5
Kotlin Coroutines 1.3+ 완전 지원 kotlin_coroutine
Project Reactor 3.1+ 완전 지원 reactor-core
Quartz 2.x 완전 지원 quartz
RxJava 2.x 완전 지원 rxjava
Spring Data 1.8+ 완전 지원 spring-data
Spring Scheduling 3.1+ 완전 지원 spring-scheduling
TIBCO BusinessWorks 5.14.0 - 6.11.0 Preview tibco, tibco_bw
Twilio SDK < 8.0 완전 지원 twilio-sdk

원하는 프레임워크가 보이지 않나요? Datadog는 계속 지원을 추가하고 있어요. 프레임워크를 요청하려면 훌륭한 지원팀에 문의하세요.

지원되지 않는 프레임워크를 사용하는 애플리케이션의 가시성을 개선하려면 다음을 고려하세요:

통합 비활성화 (Disabling integrations)

대부분의 통합은 기본적으로 활성화돼요. 다음 설정으로 기본값을 비활성화로 변경할 수 있어요.

  • 시스템 속성: -Ddd.integrations.enabled=false
  • 환경 변수: DD_INTEGRATIONS_ENABLED=false

통합은 개별적으로 활성화하거나 비활성화할 수 있어요(위 기본값을 재정의).

  • 시스템 속성: -Ddd.integration.<INTEGRATION_NAME>.enabled=true
  • 환경 변수: DD_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

(각 통합의 이름은 위를 참고하세요.)

알려진 문제 (Known issues)

  • Bitbucket에서 Java 트레이서를 실행하는 것은 지원되지 않아요.
  • APM/트레이싱 기능을 수행하는 여러 Java Agent를 로드하는 것은 권장되거나 지원되는 구성이 아니에요.
  • Java 24+에서 SDK를 실행하면 JNI 네이티브 접근 관련 경고가 표시될 수 있어요. --enable-native-access=ALL-UNNAMED 플래그를 추가해 이러한 경고를 억제하세요. 자세한 내용은 JEP 472를 참고하세요.

AOT(Ahead-of-time) 클래스 로딩·연결 지원

시작 시간을 개선하기 위해 AOT(사전 컴파일) 클래스 로딩·연결은 JVM 시작 시 애플리케이션 클래스를 로드되고 연결된 상태로 즉시 사용할 수 있게 해 줘요. 자세한 내용은 JEP 483과 JEP 514를 참고하세요.

요구사항 (Requirements)

다음을 사용하세요:

설정 (Setup)

APM용 AOT 클래스 로딩·연결을 설정하려면 훈련 실행(training run) 중에 Datadog Java SDK를 추가하세요:

java -javaagent:/path/to/dd-java-agent.jar -XX:AOTCacheOutput=app.aot -jar App.jar
사용 (Usage)

프로덕션 중에는 이전에 캐시된 훈련 데이터와 함께 동일한 Datadog Java SDK를 추가하세요:

java -javaagent:/path/to/dd-java-agent.jar -XX:AOTCache=app.aot -jar App.jar

Trace Explorer를 사용해 트레이스를 볼 수 있어요.

문제 해결 (Troubleshooting)
훈련 실행 중 Datadog Java SDK를 부착하지 않은 경우

프로덕션에서 다음 경고가 보인다면 훈련 중에 Datadog Java SDK가 부착되지 않았다는 뜻이에요:

Mismatched values for property jdk.module.addmods: java.instrument specified during runtime but not during dump time

그러면 JVM이 AOT 캐시를 사용해 시작 시간을 개선할 수 없어요. 해결 방법은 훈련 중에 SDK를 부착하는 것이에요.

GraalVM Native Image 지원

GraalVM Native Image는 Java 애플리케이션을 네이티브 실행 파일로 컴파일할 수 있게 해 주는 기술이에요. Datadog Java SDK는 GraalVM Native Image를 지원해요. 이를 통해 라이브러리가 제공하는 트레이싱 기능의 이점을 그대로 누리면서 애플리케이션을 네이티브 실행 파일로 컴파일할 수 있어요.

요구사항 (Requirements)

다음을 사용하세요:

설정 (Setup)

GraalVM Native Image로 Datadog Java SDK를 설정하려면 다음 단계를 따르세요:

  1. Java 애플리케이션 트레이싱에 설명된 단계에 따라 애플리케이션을 계측하세요.
  2. native-image 명령으로 네이티브 실행 파일을 빌드할 때 -J-javaagent:/path/to/dd-java-agent.jar 인자를 추가하세요. 예: 
    native-image -J-javaagent:/path/to/dd-java-agent.jar -jar App.jar
  3. (선택 사항) 다음 인자를 추가해 프로파일러 통합을 활성화하세요: -J-Ddd.profiling.enabled=true --enable-monitoring=jfr.
    • 1.39.1 이전 트레이서 버전의 경우, 생성된 네이티브 실행 파일을 실행할 때 DD_PROFILING_START_FORCE_FIRST=true를 환경 변수로 설정했는지 확인하세요.

Quarkus Native로 Datadog Java SDK를 설정하려면 다음 단계를 따르세요:

  1. Java 애플리케이션 트레이싱에 설명된 단계에 따라 애플리케이션을 계측하세요.
  2. 네이티브 실행 파일을 빌드할 때 quarkus.native.additional-build-args 속성을 사용하세요. 예: 
    ./mvnw package -Dnative -Dquarkus.native.additional-build-args='-J-javaagent:/path/to/dd-java-agent.jar'
  3. (선택 사항) 다음 인자를 추가해 프로파일러 통합을 활성화하세요: -J-Ddd.profiling.enabled=true --enable-monitoring=jfr.
    • 1.39.1 이전 트레이서 버전의 경우, 생성된 네이티브 실행 파일을 실행할 때 DD_PROFILING_START_FORCE_FIRST=true를 환경 변수로 설정했는지 확인하세요.

Spring Native로 Datadog Java SDK를 설정하려면 다음 단계를 따르세요:

  1. Java 애플리케이션 트레이싱에 설명된 단계에 따라 애플리케이션을 계측하세요.

  2. Buildpacks 기반의 Spring Native 빌드에서는 BP_DATADOG_ENABLED=true로 Datadog용 Paketo Buildpack을 활성화하세요.

    • 이는 Maven 같은 빌드 도구 수준에서 할 수 있어요:
    <build>
<plugins>
  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
      <image>
        ...
        <env>
          ...
          <BP_DATADOG_ENABLED>true</BP_DATADOG_ENABLED>
          ...
        </env>
      </image>
    </configuration>
  </plugin>
</plugins>
</build>
    • 또는 --env BP_DATADOG_ENABLED=true 옵션과 함께 pack build 명령을 사용해 Datadog buildpack을 활성화할 수 있어요.

  3. (선택 사항) 환경 변수 BP_NATIVE_IMAGE_BUILD_ARGUMENTS='-J-Ddd.profiling.enabled=true --enable-monitoring=jfr'를 설정해 프로파일러 통합을 활성화하세요.

    • 1.39.1 이전 트레이서 버전의 경우, 생성된 네이티브 실행 파일을 실행할 때 DD_PROFILING_START_FORCE_FIRST=true를 환경 변수로 설정했는지 확인하세요.

GraalVM 25에서는 Use of Unsafe 관련 오류가 표시될 수 있어요. 네이티브 실행 파일 빌드 시 -Dnet.bytebuddy.safe=false를 추가해 해결하세요.

사용 (Usage)

설정을 완료하면 서비스가 Datadog로 트레이스를 보내야 해요.

Trace Explorer를 사용해 트레이스를 볼 수 있어요.

문제 해결 (Troubleshooting)
네이티브 이미지에서 기능이 활성화되거나 구성되지 않는 문제

Graal Native Image로 빌드된 바이너리에서 런타임에 시스템 속성에 접근할 때 알려진 문제가 있어요.

  • 런타임 구성에는 시스템 속성(-Ddd.property.name=value) 대신 환경 변수(DD_PROPERTY_NAME=value)를 사용하세요.
  • 이 규칙의 예외는 프로파일러를 활성화할 때예요. 이 경우 빌드 시점에 native-image 도구에 -J-Ddd.profiling.enabled=true를 전달하세요.
5.12.2보다 오래된 native-image buildpack 버전

오래된 native-image buildpack 버전은 다음 옵션을 노출해요: USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM.

이 옵션이 false면 다음과 같은 예외가 발생할 수 있어요:

Caused by: org.graalvm.compiler.java.BytecodeParser$BytecodeParserError:
com.oracle.graal.pointsto.constraints.UnsupportedFeatureException:
No instances of datadog.trace.bootstrap.DatadogClassLoader are allowed in the image heap
as this class should be initialized at image runtime. To see how this object got
instantiated use --trace-object-instantiation=datadog.trace.bootstrap.DatadogClassLoader.

이 문제의 해결 방법은:

  • 이미지 env 구성에서 USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM을 명시적으로 true로 설정,
  • 또는 native-image buildpack을 5.12.2 이상으로 업그레이드. 가장 좋은 방법은 java-native-image buildpack을 8.13.0 이상으로 업그레이드하는 것이에요.
4.6.0보다 오래된 Datadog용 Paketo buildpack 버전

Datadog용 Paketo buildpack은 오래된 버전에서 다음 오류 메시지로 나타나는 버그가 있었어요:

disabling Datadog at launch time is unsupported for Node
ERROR: failed to launch: exec.d: failed to execute exec.d file at path '/layers
paketo-buildpacks_datadog/helper/exec.d/toggle': exit status 1

이 문제의 해결 방법은 버전 4.6.0 이상으로 업그레이드하는 것이에요.

Spring Native 빌드가 exec.d/toggle 오류로 중단되는 문제

Spring Boot 네이티브 이미지를 빌드할 때 4.6.0보다 새로운 buildpack 버전에서도 위와 유사한 오류가 발생할 수 있어요:

disabling Datadog at launch time is unsupported for Node
ERROR: failed to launch: exec.d: failed to execute exec.d file at path '/layers
paketo-buildpacks_datadog/helper/exec.d/toggle': exit status 1

이것은 일반적으로 Datadog buildpack이 네이티브 이미지 buildpack보다 먼저 실행되어 네이티브 이미지 빌드가 의도된 것임을 알지 못하기 때문이에요. JVM 빌드용으로 만들어진 토글 스크립트를 잘못 추가하는데, 이는 최종 네이티브 실행 파일과 호환되지 않아요.

해결 방법은 spring-boot-maven-plugin 구성에서 BP_NATIVE_IMAGE 환경 변수를 명시적으로 true로 설정하는 것이에요. 이렇게 하면 모든 buildpack이 처음부터 네이티브 이미지 빌드임을 알게 돼요.

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <configuration>
        <image>
          ...
          <env>
            ...
            <BP_NATIVE_IMAGE>true</BP_NATIVE_IMAGE>
            ...
          </env>
        </image>
      </configuration>
    </plugin>
  </plugins>
</build>
Datadog SDK 활성화 문제

트레이서 구성이 네이티브 이미지에서 지원되지 않는 Unix Domain Sockets(UDS)에 의존한다면 초기화 오류가 발생할 수 있어요:

dd.trace 2024-12-30 08:34:43:306 +0000] [main] WARN datadog.trace.agent.tooling.nativeimage.TracerActivation - Problem activating datadog tracer
java.lang.NoClassDefFoundError: Could not initialize class jnr.unixsocket.UnixSocketChannel

해결 방법은 소켓 기반 통신(socket 모드) 대신 호스트 기반 통신(hostip 또는 service 모드)을 사용하도록 Java 트레이서를 구성하는 것이에요.

자세한 내용은 APM 및 DogstatsD 통신 모드 구성을 참고하세요. Admission Controller에 의존하지 않는 구성은 DD_TRACE_AGENT_URL 문서를 참고하세요.

더 알아보기 (Learn more)