Linux에서 단일 단계 APM 계측 (Single Step APM Instrumentation on Linux)

원문 보기 위키 갱신 2026.10.05

Linux 호스트 또는 VM에서 단일 단계 계측(SSI, Single Step Instrumentation)을 사용하면 Datadog Agent를 설치하고 애플리케이션을 계측하는 작업을 추가 설정 없이 단 한 단계로 끝낼 수 있어요.

출처: 문서

본문

개요

Linux 호스트 또는 VM에서 APM용 단일 단계 계측(SSI)을 사용하면 Datadog Agent를 설치하고 애플리케이션을 계측하는 작업을 추가 설정 없이 단 한 단계로 끝낼 수 있어요.

APM을 설정하려면 AI 코딩 에이전트에 dd-apm 스킬을 설치해 안내에 따라 APM을 설정하세요.

npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y

애플리케이션에서 APM 활성화

진행하기 전에 SSI 호환성 가이드를 확인해 환경이 호환되는지 확인하세요.

새 Agent 설치

아직 Datadog Agent가 없다면 한 단계로 Agent를 설치하고 SSI를 활성화하세요.

Linux 호스트 또는 VM에서 다음 명령을 실행해요:

DD_API_KEY=<YOUR_DD_API_KEY> \
DD_SITE="<YOUR_DATADOG_SITE>" \
DD_APM_INSTRUMENTATION_ENABLED=host \
bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

<YOUR_DD_API_KEY>를 Datadog API 키로 바꿔요. 이 명령은 Agent와 SSI 패키지를 설치하거나 업데이트해요.

기본적으로 SSI는 최신 SDK 버전을 설치해요. 특정 버전을 고정하려면 DD_APM_INSTRUMENTATION_LIBRARIES 변수에 쉼표로 구분된 language:major 쌍을 추가해요. 사용 가능한 버전은 각 언어의 소스 저장소에서 확인할 수 있어요: Java (java), Node.js (js), Python (python), .NET (dotnet), Ruby (ruby), PHP (php).

애플리케이션을 다시 시작해요.

참고: SSI는 계측된 애플리케이션에 약간의 시작 시간을 추가해요. 이 오버헤드가 사용 사례에 맞지 않으면 Datadog 지원에 문의하세요.

Datadog에서 명령 생성

API 키와 사이트가 미리 채워진 명령을 얻으려면 Linux에 Datadog Agent 설치 페이지에서 Core Observability 아래의 Application Performance Monitoring을 켜요.

중요: 다음 Datadog 사이트를 사용하는 사용자 참고: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com

드롭다운에서 SDK 버전을 선택하려면 Customize Library Versions를 클릭해요.

그런 다음 생성된 명령을 복사해 실행해요.

기존 Agent 설치

이미 Datadog Agent가 설치되어 있다면 위의 "새 Agent 설치" 섹션의 Agent 설치 명령을 호스트에서 다시 실행해요. 이 명령은 기존 Agent를 업데이트하고 SSI를 활성화해요.

또는 Fleet Automation을 사용해 Datadog에서 SSI를 활성화할 수 있어요:

Datadog에서 Fleet Automation > Configuration으로 이동해요.
Configure Agents를 클릭해요.
필터를 적용해 구성할 에이전트를 선택한 다음 Next를 클릭해요.
Application Performance Monitoring (APM) 타일을 클릭한 다음 Next를 클릭해요.
Configure SDKs Installation 화면에서 Yes를 클릭해 SDK를 자동으로 설치해요. Use latest version을 선택하거나 선택을 해제해 개별 SDK 버전을 지정해요.
Next를 클릭해요.
구성을 검토하고 Deploy Configuration을 클릭해요.

설치 확인

Agent가 실행 중인지 확인해요:
```
sudo datadog-agent status
```
호스트에서 SSI 주입이 활성화되었는지 확인해요:
```
cat /etc/ld.so.preload && ls /opt/datadog-packages/ | grep apm
```

출력에는 /etc/ld.so.preload에 APM 주입기 라이브러리와 하나 이상의 datadog-apm-* 패키지가 표시돼요.

애플리케이션이 트래픽을 받은 후 서비스가 APM 서비스 페이지에 나타나는지 확인해요. 몇 분 안에 나타나지 않으면 SSI 트러블슈팅 가이드를 참조하세요.

통합 서비스 태그 구성

통합 서비스 태그(UST)는 트레이스, 메트릭, 로그에 일관된 태그를 적용해 옵저버빌리티 데이터를 더 쉽게 탐색하고 연관 지을 수 있게 해줘요. Linux 서비스에 UST를 설정하는 방법을 알아보세요.

SDK 기반 제품 및 기능 활성화

SSI가 애플리케이션에 Datadog SDK를 로드하고 분산 트레이싱을 활성화한 후, SDK에 의존하는 추가 제품을 구성할 수 있어요:

제품	환경 변수
런타임 메트릭	`DD_RUNTIME_METRICS_ENABLED`
로그 주입	`DD_LOGS_INJECTION`
Continuous Profiler	`DD_PROFILING_ENABLED`
Data Streams Monitoring	`DD_DATA_STREAMS_ENABLED`
App and API Protection	`DD_APPSEC_ENABLED`
Runtime Code Analysis (IAST)	`DD_IAST_ENABLED`
Dynamic Instrumentation	`DD_DYNAMIC_INSTRUMENTATION_ENABLED`
Data Jobs Monitoring	`DD_DATA_JOBS_ENABLED`
Software Composition Analysis	`DD_APPSEC_SCA_ENABLED`

참고: 모든 변수는 true 또는 false를 허용해요. DD_PROFILING_ENABLED는 또한 auto를 허용하며, auto는 적격 프로세스만 프로파일링하며 SSI에 권장돼요.

다음 설정 방법 중 하나를 사용해요:

application_monitoring.yaml에서 구성: 애플리케이션 명령줄을 수정하지 않고 호스트의 모든 서비스에 걸쳐 제품과 기능을 구성해요.
환경 변수 설정: 애플리케이션 구성에서 직접 환경 변수를 설정해 제품을 활성화해요.

고급 옵션

SDK 버전 업데이트

SDK 버전은 Agent 설치 명령을 실행할 때 고정돼요.

SDK 버전을 업데이트하려면:

Agent 설치 명령을 다시 실행해요. 이 명령은 Agent도 최신 버전으로 업데이트해요.
애플리케이션을 다시 시작해요.

계측 규칙 정의

경고: 계측 규칙은 선택한 Datadog 사이트에서는 지원되지 않아요 (user-datadog-site-name).

계측 규칙(Agent v7.73+에서 사용 가능)은 Linux 호스트에서 SSI가 자동으로 계측할 프로세스를 제어할 수 있게 해줘요.

참고: Bits AI를 사용해 자연어로 계측 규칙을 만들 수 있어요. 계측할 프로세스를 설명하면 Bits AI가 해당 규칙을 생성해요.

계측 규칙을 구성하려면:

Datadog에서 APM > Service Setup > Manage Instrumentation Rules로 이동해요.
Add or Edit Rules를 클릭해요.
계측 규칙을 정의해요:
1. Add New Rule을 클릭한 다음 Allow Rule 또는 Block Rule을 선택해 일치하는 프로세스를 계측할지 여부를 지정해요.
2. 규칙 이름을 지정해요.
3. 하나 이상의 조건을 추가해요. 자세한 내용은 "규칙 조건 정의"를 참조하세요.
(선택 사항) 규칙을 끌어서 놓아 순서를 변경해요.

참고: 규칙은 순서대로 평가돼요. 프로세스가 규칙과 일치하면 이후 규칙은 무시돼요.

어떤 규칙과도 일치하지 않는 프로세스의 기본 동작(허용 또는 차단)을 설정해요.
Next를 클릭해 규칙을 미리 봐요.
Deploy Rules를 클릭해요.

Remote Configuration이 활성화되어 있으면 규칙이 모든 호스트에 배포되고 SSI가 활성화된 호스트에 50초 이내에 적용돼요. 또는 Export를 클릭해 구성 파일을 내보내 호스트에 수동으로 적용할 수 있어요.

규칙 조건 정의

각 규칙은 하나 이상의 조건으로 구성돼요. 조건에는 다음 요소가 포함돼요:

Attribute(속성): 규칙이 평가하는 프로세스 속성.
Operator(연산자): 비교 로직(equals, not equals, prefix, 또는 contains).
Value(값): 프로세스 이름이나 명령줄 플래그 같은 일치시킬 텍스트 또는 패턴.

지원되는 속성은 다음과 같아요:

속성	설명	예시
Operating System	호스트의 OS.	`linux`
Executable	프로세스의 실행 파일 이름.	`python3.11`
Executable Full Path	실행 파일의 전체 경로.	`/usr/bin/python3.11`
Arguments	프로세스를 시작할 때 사용된 명령줄 인수.	`--env=production`
Working Directory	프로세스의 작업 디렉터리.	`/app`
Language	프로세스에서 감지된 프로그래밍 언어.	`python`
Entry Point File	애플리케이션을 실행하는 데 사용한 파일.	`app.py`, `server.js`

예시 사용 사례

계측 규칙을 적용하는 방법을 보여주는 다음 예시를 검토해보세요.

예시 1: 특정 프로세스를 제외한 모든 프로세스 계측

기본적으로 모든 프로세스를 계측해요. 분석 크론 작업이나 Java 배치 프로세서처럼 가치 없이 노이즈만 추가하는 서비스를 제외하려면 블록 규칙을 추가해요.

예시 2: 특정 프로세스만 계측

기본적으로 모든 계측을 차단해요. 특정 프로세스를 APM에 옵트인하려면 허용 규칙을 추가해요. 이 방식은 정밀한 제어를 제공하며 점진적 배포에 잘 맞아요. 예를 들어 체크아웃 서비스와 고객 포털만 계측하려면 Working Directory를 사용하는 허용 규칙을 만들고 기본 동작을 Block Instrumentation으로 설정해요.

Agent에서 단일 단계 APM 계측 제거

인프라의 모든 서비스에 대해 트레이스 생성을 중지하려면:

다음을 실행해요:
```
dd-host-install --uninstall
```
호스트 또는 VM의 서비스를 다시 시작해요.

트러블슈팅

SSI로 APM을 활성화하는 데 문제가 발생하면 SSI 트러블슈팅 가이드를 참조하세요.