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

원문 보기 위키 갱신 2026.10.05

단일 단계 계측(SSI)을 사용하면 단일 Datadog Agent 설치 명령으로 Windows VM에서 Java 및 .NET 애플리케이션에 APM을 활성화할 수 있어요.

출처: 문서

본문

개요

단일 단계 계측(SSI)을 사용하면 단일 Datadog Agent 설치 명령으로 Windows VM에서 Java 및 .NET 애플리케이션에 APM을 활성화할 수 있어요.

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

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

Windows에서 APM 활성화

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

새 Agent 설치

아직 Datadog Agent가 없다면 다음 단계에 따라 Agent를 설치하고 동시에 SSI를 활성화해요.

Windows에서 APM은 다음과 같은 방식으로 활성화할 수 있어요:

IIS에서 .NET 애플리케이션만 계측
Windows 호스트 전체의 모든 Java 및 .NET 애플리케이션 계측

IIS

IIS에서 실행되는 .NET 애플리케이션만 계측하려면:

Windows 호스트의 관리자 PowerShell 세션에서 다음 명령 중 하나를 실행해요. <YOUR_DD_API_KEY>를 Datadog API 키로 바꿔요.

PowerShell 설치 프로그램 사용:

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $env:DD_API_KEY = '<YOUR_DD_API_KEY>'; $env:DD_SITE = '<span class="js-region-param region-param" data-region-param="dd_site"></span>'; $env:DD_APM_INSTRUMENTATION_ENABLED = 'iis'; $env:DD_APM_INSTRUMENTATION_LIBRARIES = 'dotnet:3'; (New-Object System.Net.WebClient).DownloadFile('https://install.datadoghq.com/datadog-installer-x86_64.exe', 'C:\Windows\SystemTemp\datadog-installer-x86_64.exe'); C:\Windows\SystemTemp\datadog-installer-x86_64.exe

또는 MSI로 설치:

$p = Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /norestart /i "https://windows-agent.datadoghq.com/datadog-agent-7-latest.amd64.msi" /log C:\Windows\SystemTemp\install-datadog.log APIKEY="<YOUR_DD_API_KEY>" SITE="<span class="js-region-param region-param" data-region-param="dd_site"></span>" DD_APM_INSTRUMENTATION_ENABLED="iis" DD_APM_INSTRUMENTATION_LIBRARIES="dotnet:3"'
if ($p.ExitCode -ne 0) { Write-Host "msiexec failed with exit code $($p.ExitCode) please check the logs at C:\Windows\SystemTemp\install-datadog.log" -ForegroundColor Red }

다른 .NET 버전을 설치하려면 dotnet:3을 바꾸거나 DD_APM_INSTRUMENTATION_LIBRARIES를 생략해 최신 버전을 설치해요.

참고: Chocolatey 설치 방법은 SSI 설정을 보존하지 않으므로 SSI를 활성화하는 데 사용할 수 없어요.

계측하려는 IIS 애플리케이션을 다시 시작해요. (전체 IIS 서버를 다시 시작할 필요는 없어요.)

그러면 Agent가 지원되는 애플리케이션 프로세스에 Datadog .NET SDK를 자동으로 로드해 분산 트레이싱을 활성화해요.

Datadog에서 명령 생성: API 키와 사이트가 미리 채워진 명령을 얻으려면 Windows에 Datadog Agent 설치로 이동해 Customize your observability coverage 섹션에서 **Application Performance Monitoring (APM)**을 토글해요. .NET SDK 버전을 고정하려면 Instrumentation Configuration 아래에서 Customize Library Versions를 선택해요. 그런 다음 생성된 명령을 복사해 실행해요.

호스트 전체 (프리뷰)

프리뷰 참여! Windows용 호스트 전체 계측은 프리뷰 상태이며 프리뷰 참가자로 제한돼요. 이 탭에 설명된 설치 및 구성 옵션은 등록 후에만 Datadog에 나타나요. 프리뷰에 참여하려면 액세스를 요청하세요.

Windows 호스트 전체의 Java 및 .NET 애플리케이션을 계측하려면:

Datadog에서 Windows에 Datadog Agent 설치로 이동해요.
Customize your observability coverage 섹션에서 **Application Performance Monitoring (APM)**을 토글해요.
(선택 사항) SDK 버전을 설정해요:

기본적으로 단일 단계 계측은 지원되는 최신 버전의 Datadog .NET 및 Java SDK를 설치해요. 특정 버전을 고정해야 한다면:

Instrumentation Configuration 아래에서 Customize Library Versions를 선택해요.
.NET 아래에서 사용할 버전을 선택해요.
제공된 설치 명령을 복사해 Windows 호스트에서 실행해요. Datadog은 프리뷰에 등록한 후 앱 내에서 이 명령을 생성해요.
계측 규칙을 구성해요.

호스트 전체 SSI는 호스트의 모든 Java 애플리케이션과 IIS에서 실행되는 모든 .NET 애플리케이션을 자동으로 계측해요. IIS 외부에서 실행되는 .NET 애플리케이션을 계측하려면 이를 허용하는 계측 규칙을 정의해야 해요. 호스트의 특정 Java 애플리케이션이나 IIS의 .NET 애플리케이션을 계측할지 세밀하게 제어하려면 계측 규칙을 사용할 수도 있어요.

계측하려는 서비스를 다시 시작해요.

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

기존 Agent 설치

이미 Datadog Agent가 있다면 Fleet Automation을 사용해 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을 클릭해요.
계측 규칙을 구성해요.

설치 확인

관리자 PowerShell 세션에서 Agent가 정상이고 APM Agent가 실행 중인지 확인해요:
```
& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" status
```

출력의 APM Agent 섹션을 확인해요.

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

통합 서비스 태그 구성

통합 서비스 태그(UST)는 트레이스, 메트릭, 로그에 일관된 태그를 적용해 옵저버빌리티 데이터를 더 쉽게 탐색하고 연관 지을 수 있게 해줘요. Windows 서비스에 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에 권장돼요.

제품을 활성화하려면 애플리케이션 구성에서 환경 변수를 설정해요.

고급 옵션

계측 규칙 정의

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

참고: 계측 규칙(Agent v7.73+에서 사용 가능)은 호스트 전체 계측에만 적용돼요. IIS 전용 설치에서는 지원되지 않아요.

계측 규칙은 Windows 호스트에서 SSI가 자동으로 계측할 프로세스를 제어할 수 있게 해줘요. IIS 외부에서 실행되는 .NET 애플리케이션을 계측하려면 규칙이 필요해요. 또한 호스트의 특정 Java 애플리케이션이나 IIS의 .NET 애플리케이션을 계측할지 세밀하게 제어하는 데 유용해요.

참고: 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.	`windows`
Executable	프로세스의 실행 파일 이름.	`w3wp.exe`
Executable Full Path	실행 파일의 전체 경로.	`C:\Windows\System32\inetsrv\w3wp.exe`
Arguments	프로세스를 시작할 때 사용된 명령줄 인수.	`--env=production`
Working Directory	프로세스의 작업 디렉터리.	`C:\inetpub\wwwroot`
Language	프로세스에서 감지된 프로그래밍 언어.	`dotnet`
Entry Point File	애플리케이션을 실행하는 데 사용한 파일.	`MyService.dll`, `app.py`
IIS Application Pool	워커 프로세스를 호스팅하는 IIS 애플리케이션 풀. 모든 IIS 워커가 `w3wp.exe` 실행 파일을 공유하므로 IIS에서 특정 .NET 앱을 타기팅하는 가장 신뢰할 수 있는 방법이에요.	`DefaultAppPool`, `MyWebApp`

예시 사용 사례

특정 프로세스만 계측하는 방법을 보여주는 다음 예시를 검토해보세요.

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

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

예시 2: 특정 IIS 애플리케이션만 계측

기본적으로 모든 계측을 차단해요. 특정 IIS 애플리케이션을 APM에 옵트인하려면 허용 규칙을 추가해요. 모든 IIS 워커가 w3wp.exe 실행 파일을 공유하므로 IIS Application Pool을 사용해 대상 애플리케이션을 식별해요. 이 방식은 점진적 배포에 유용해요.

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

호스트에서 .NET에 대한 SSI를 비활성화하려면 다음을 실행해요:

&"C:\Program Files\Datadog\Datadog Agent\bin\datadog-installer.exe" remove datadog-apm-library-dotnet

트러블슈팅

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

더 알아보기 (Learn more)

Enable Runtime Metrics