단계별 계측 (SSI) 호환성 (Single Step Instrumentation Compatibility)

원문 보기 위키 갱신 2026.10.05

운영체제, 환경, 언어 런타임에 따라 달라지는 단계별 계측(Single Step Instrumentation, SSI)의 호환성을 안내해요.

출처: 문서

본문

개요 (Overview)

단계별 계측(SSI)은 운영체제, 환경, 언어 런타임에 따라 호환성 요구사항이 달라져요. 이 페이지는 특정 구성에서 SSI에 영향을 줄 수 있는 지원 플랫폼, 요구사항, 알려진 제한 사항을 설명해요.

애플리케이션 환경별 호환성 (Compatibility by application environment)

ECS Fargate는 지원되지 않아요.

환경을 선택해 호환성 요구사항과 제한 사항을 확인하세요:

Linux 호스트 (Linux hosts)

호환성 (Compatibility)

상태: GA
지원 운영체제: Linux 배포판 참조(아래 표)
지원 아키텍처: x86_64, arm64

요구사항 (Requirements)

APM Instrumentation이 활성화된 Datadog Agent
지원되는 Linux 배포판

제한 사항 (Limitations)

SELinux: 강화된(하드닝된) SELinux 환경은 지원되지 않아요.
소형 VM 인스턴스: 아주 작은 인스턴스 타입(예: t2.micro)은 타임아웃이 발생할 수 있어요. t2.small 이상과 같은 더 큰 인스턴스 타입을 사용하세요.

Docker

호환성 (Compatibility)

상태: GA
지원 운영체제: Linux 배포판 참조
지원 아키텍처: x86_64, arm64

요구사항 (Requirements)

APM Instrumentation이 활성화된 Datadog Agent
지원되는 Linux 배포판에서 실행되는 Docker

제한 사항 (Limitations)

루트리스 Docker 모드: 루트리스 모드로 Docker를 실행할 때는 /etc/datadog-agent/inject/docker_config.yaml의 소켓 경로를 업데이트해 SSI가 Docker에 연결할 수 있게 하세요. 기본 경로는 /run/user/$UID/docker.sock이지만 환경에 따라 다를 수 있어요.
사용자 지정 runc shim: 환경에서 사용자 지정 runc shim을 사용한다면(예: GPU 워크로드), /etc/datadog-agent/inject/docker_config.yaml의 runtimes 항목에 사용자 지정 런타임과 SSI에 필요한 Datadog 런타임을 모두 포함하도록 업데이트하세요.

EKS Fargate

EKS Fargate 지원은 Preview 상태예요.

호환성 (Compatibility)

상태: GA
지원 노드 풀: Linux 노드만(Linux 배포판 참조)
지원 아키텍처: x86_64, arm64

요구사항 (Requirements)

Datadog Admission Controller 활성화
지원되는 Linux 배포판을 실행하는 Kubernetes 노드

제한 사항 (Limitations)

Linux 노드 풀만: Linux 노드 풀만 지원돼요.
Windows 포드: Windows 포드가 있는 Kubernetes 클러스터에서는 네임스페이스 포함/제외를 사용하거나 애플리케이션에 주석을 지정해 라이브러리 주입에서 제외하세요.

Windows (IIS)

호환성 (Compatibility)

상태: GA
지원 런타임: .NET만

요구사항 (Requirements)

Datadog Agent v7.67.1 이상
Datadog .NET SDK v3.19.0 이상
IIS에서 실행되는 애플리케이션

제한 사항 (Limitations)

IIS만: IIS에서 실행되는 .NET 애플리케이션만 지원돼요.

지원되는 언어 런타임 (Supported language runtimes)

SSI는 지침에 따라 호환되는 Datadog 언어 SDK를 런타임에 로드하여 다음 언어로 작성된 애플리케이션을 자동으로 계측해요. 언어를 선택해 최소 SDK 버전, 지원 런타임 버전, 제한 사항을 확인하세요.

SSI 호환성은 두 가지 요소에 따라 달라져요:

SDK 버전: SSI가 Datadog 언어 SDK 버전을 지원해야 해요.
런타임 버전: Datadog 언어 SDK가 애플리케이션의 언어 런타임 버전을 지원해야 해요.

두 요구사항 중 하나라도 충족되지 않으면 SSI는 안전하게 대체(fallback)되어 애플리케이션이 계측 없이 실행돼요.

Java

최소 SDK 버전 (Minimum SDK version)

Java SDK: 1.44.0 이상

지원 런타임 버전 (Supported runtime versions)

지원되는 Java 버전의 전체 목록은 Java SDK 호환성 문서를 참고하세요.

SSI는 Java 24+에서 --enable-native-access=ALL-UNNAMED 플래그를 사용해 클래스 패스의 모든 코드에 대한 네이티브 접근을 활성화해요. 이는 네이티브 접근이 필요한 Profiling 같은 제품에 필요해요. 자세한 내용은 JEP 472를 참고하세요.

제한 사항 (Limitations)

기본적으로 SSI는 성능 오버헤드나 실행 가능성이 없는 트레이스를 피하기 위해 일부 Java 애플리케이션과 라이브러리를 계측하지 않아요. 이러한 제외 항목은 Java SDK denylist에 정의되어 있어요. 워크로드가 포함되어 있다면 SSI는 Java SDK 로드를 건너뛰어요.

알려진 문제 (Known issues)

환경 변수 길이: 애플리케이션이 광범위한 명령줄 옵션이나 환경 변수를 사용한다면 초기화 실패가 발생할 수 있어요. 이는 주로 JVM 인자가 많거나 다른 시작 구성이 있을 때 발생해요. 해결하려면:

필수적이지 않은 JVM 인자를 최소화하세요
일부 구성을 .properties 파일로 옮기는 것을 고려하세요
특정 초기화 오류를 확인하려면 애플리케이션 로그를 확인하세요

Python

최소 SDK 버전 (Minimum SDK version)

Python SDK: 2.20.1 이상

지원 런타임 버전 (Supported runtime versions)

최소 Python 버전: 3.7 이상

지원되는 Python 버전의 전체 목록은 Python SDK 호환성 문서를 참고하세요.

운영체제 고려 사항 (Operating system considerations)

Python 3.7+는 기본적으로 다음에서만 사용 가능해요:

CentOS Stream 8+
Red Hat Enterprise Linux 8+

다른 배포판에서는 Python 3.7+를 별도로 설치해야 할 수 있어요.

알려진 문제 (Known issues)

프리포킹 WSGI 서버: 프리포킹(preforking) WSGI 서버에서 실행되는 Python 애플리케이션은 SSI를 활성화하면 시작 시 워커 프로세스 충돌(SIGSEGV)이 발생할 수 있어요. 이는 프리포킹 모드의 uWSGI, --preload가 있는 gunicorn, 프리로드가 있는 디먼 모드의 Apache mod_wsgi에 영향을 줘요.

최근 Python SDK 릴리스에는 부분적인 수정이 포함되어 있어요. 최신 상태는 dd-trace-py 릴리스 페이지를 참고하세요.

완화하려면:

영향을 받는 서비스의 SSI를 비활성화하세요. 제거 단계는 플랫폼별 SSI 설정 페이지를 참고하세요.
지연 로딩 배포 패턴으로 전환하세요(예: --preload 없는 gunicorn, lazy-apps 모드의 uWSGI).
SSI 대신 Python SDK를 수동으로 설치하세요(pip install ddtrace + ddtrace-run).

Ruby

최소 SDK 버전 (Minimum SDK version)

Ruby SDK: 2.6.0 이상

지원 런타임 버전 (Supported runtime versions)

지원되는 Ruby 버전의 전체 목록은 Ruby SDK 호환성 문서를 참고하세요.

운영체제 요구사항 (Operating system requirements)

glibc 2.17 이상을 사용하는 Linux 배포판 필요
Alpine Linux나 기타 musl 기반 배포판과는 호환되지 않아요
Bundler >= 2.4, < 4.0 및 RubyGems >= 3.4, < 4.0 필요

알려진 문제 (Known issues)

SSI 제거: Ruby 애플리케이션에서 단계별 계측을 제거할 때 오류를 방지하려면 다음 단계를 따르세요:

제거 전에: Gemfile과 Gemfile.lock을 백업하세요.
제거 후 다음 중 하나를 수행하세요:
- 원래 Gemfile과 Gemfile.lock을 복원하세요.
- bundle install을 실행해 의존성을 재구성하세요.

Node.js

최소 SDK 버전 (Minimum SDK version)

Node.js SDK: 4.0 이상

지원 런타임 버전 (Supported runtime versions)

지원되는 Node.js 버전의 전체 목록은 Node.js SDK 호환성 문서를 참고하세요.

운영체제 고려 사항 (Operating system considerations)

지원되는 Node.js 버전은 기본적으로 다음에서만 사용 가능해요:

CentOS Stream 9+
Red Hat Enterprise Linux 9+

다른 배포판에서는 Node.js를 별도로 설치해야 할 수 있어요.

제한 사항 (Limitations)

ESM 모듈: ESM(ECMAScript modules) 계측은 지원되지 않아요.

.NET

최소 SDK 버전 (Minimum SDK version)

.NET SDK: 3.7.0 이상

지원 런타임 버전 (Supported runtime versions)

SSI는 .NET Core와 .NET Framework 런타임을 모두 지원해요. 지원 버전의 전체 목록은 다음을 참고하세요:

알려진 문제 (Known issues)

기존 .NET 프로파일러: .NET CLR Profiling API는 프로세스당 하나의 프로파일러만 로드해요. 애플리케이션에 이미 .NET 프로파일러(Datadog 또는 다른 APM 벤더)가 있다면 SSI는 설치되지만 런타임에서는 기존 프로파일러가 우선해요. 그 결과 Datadog 트레이스가 Agent에 도달하지 않아요.

이 문제를 해결하려면 SSI를 활성화하기 전에 기존 프로파일러를 참조하는 충돌하는 CORECLR_* 환경 변수와 LD_PRELOAD 항목을 제거하세요:

Linux 호스트와 Docker: 애플리케이션 시작 환경에서 변수를 제거한 뒤 애플리케이션을 다시 시작하세요.
Kubernetes: SSI admission webhook은 다른 벤더의 operator, init 컨테이너, 포드 템플릿이 주입한 CORECLR_* 변수를 덮어쓰지 않아요. 해당 변수를 그 출처(주입한 operator, init 컨테이너, 포드 템플릿, Helm 값)에서 제거한 뒤 영향받는 포드를 다시 시작하세요.

.NET CLR 원-프로파일러 제약에 대한 자세한 내용은 .NET Core 설치를 참고하세요.

PHP

최소 SDK 버전 (Minimum SDK version)

PHP SDK: 1.6.0 이상

지원 런타임 버전 (Supported runtime versions)

지원되는 PHP 버전의 전체 목록은 PHP SDK 호환성 문서를 참고하세요.

제한 사항 (Limitations)

SSI는 다음을 감지하면 자동으로 비활성화돼요:

PHP의 JIT(Just-In-Time) 컴파일
다음 확장 중 하나:
- Xdebug
- ionCube Loader
- NewRelic
- Blackfire
- pcov

이러한 도구와 함께 SSI를 실행해야 한다면 DD_INJECT_FORCE=true를 설정해 강제로 활성화할 수 있어요.

Linux 배포판 참조 (Linux distributions reference)

모든 배포 플랫폼(Linux 호스트, Docker, Kubernetes)에서 SSI에 대해 지원되는 Linux 배포판과 아키텍처는 다음과 같아요:

OS	버전	아키텍처
Amazon Linux	2022, 2023	x86_64, arm64
CentOS	7, 8	x86_64, arm64
Debian	10, 11, 12	x86_64, arm64
Red Hat	7, 8, 9	x86_64, arm64
Ubuntu	20, 22, 24 (LTS)	x86_64, arm64
Fedora	40	x86_64, arm64
AlmaLinux	8	x86_64, arm64
Oracle Linux	8	x86_64, arm64
Rocky Linux	8	x86_64, arm64

프로그래밍 언어별로 추가 운영체제 요구사항은 "지원되는 언어 런타임"을 참고하세요.

더 알아보기 (Learn more)

단계별 APM 계측 (Single Step APM Instrumentation)