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

.NET Framework 애플리케이션 트레이싱 (Tracing .NET Framework Applications)

원문 보기 위키 갱신

.NET Framework 애플리케이션에 Datadog .NET Tracer를 설치하고 활성화해 트레이스를 Datadog으로 보내는 방법이에요. Windows 머신 전체 설치와 NuGet 방식, 환경 변수 설정을 다룹니다.

출처: 문서

본문

호환성 요구사항 (Compatibility requirements)

지원되는 .NET Framework 런타임

.NET Tracer는 .NET Framework >= 4.6.1에서 계측을 지원해요.

Datadog의 .NET Framework 라이브러리·프로세서 아키텍처 지원(레거시·유지보수 버전 포함) 전체 목록은 호환성 요구사항을 참고하세요.

설치와 시작하기 (Installation and getting started)

AWS Lambda나 Azure Functions 같은 Serverless 환경에서 Datadog APM을 설정하려면 Serverless를 참고하세요.

참고: Datadog의 자동 계측은 .NET CLR 프로파일링 API에 의존해요. 이 API는 구독자를 하나만 허용해요(예: Datadog APM). 최대 가시성을 보장하려면 애플리케이션 환경에서 APM 솔루션을 하나만 실행하세요.

설치 (Installation)

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

  1. SDK를 설치하세요.
  2. 서비스에서 SDK를 활성화하세요.
  3. 실시간 데이터를 확인하세요.

SDK 설치하기

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

Datadog .NET Tracer를 머신 전체에 설치해 머신의 모든 서비스가 계측되게 하거나, 애플리케이션별로 설치해 개발자가 애플리케이션의 의존성으로 계측을 관리하게 할 수 있어요. 머신 전체 설치 지침은 Windows 탭을, 애플리케이션별 설치 지침은 NuGet 탭을 클릭하세요.

Windows

.NET Tracer를 머신 전체에 설치하려면:

  1. .NET Tracer MSI 설치 프로그램을 다운로드하세요. 64비트 Windows를 실행 중이면 x64 MSI 설치 프로그램을 사용하세요. 이것은 64비트와 32비트 애플리케이션을 모두 계측할 수 있어요. 32비트 Windows를 실행 중인 경우에만 x86 설치 프로그램을 선택하세요. v3.0.0부터 32비트 운영체제를 지원하지 않으므로 x64 설치 프로그램만 제공돼요.

  2. 관리자 권한으로 .NET Tracer MSI 설치 프로그램을 실행하세요.

PowerShell에서 다음을 실행해 MSI 설정을 스크립트로 만들 수도 있어요: Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'

NuGet

참고: 이 설치는 IIS에서 실행되는 애플리케이션을 계측하지 않아요. IIS에서 실행되는 애플리케이션은 Windows 머신 전체 설치 절차를 따르세요.

.NET Tracer를 애플리케이션별로 설치하려면:

  1. 애플리케이션에 Datadog.Trace.Bundle NuGet 패키지를 추가하세요.

서비스에서 SDK 활성화하기

서비스에서 .NET Tracer를 활성화하려면 필요한 환경 변수를 설정하고 애플리케이션을 다시 시작하세요.

환경 변수를 설정하는 다양한 방법에 대한 정보는 프로세스 환경 변수 구성(Configuring process environment variables)을 참고하세요.

Windows

Internet Information Services (IIS)

  1. .NET Tracer MSI 설치 프로그램이 필요한 모든 환경 변수를 추가해요. 구성할 환경 변수는 없어요.

  2. IIS에서 호스팅되는 애플리케이션을 자동 계측하려면 관리자 권한으로 다음 명령을 실행해 IIS를 완전히 중지했다가 시작하세요.

    net stop /y was
net start w3svc
# 또한 WAS가 종료됐을 때 중지된 다른 서비스도 시작하세요.

참고: SDK를 활성화하려면 항상 위 명령으로 IIS를 완전히 중지·재시작하세요. IIS Manager GUI 애플리케이션이나 iisreset.exe는 사용하지 마세요.

IIS 밖의 서비스

참고: .NET 런타임은 이러한 환경 변수가 설정된 상태로 시작되는 모든 .NET 프로세스에 .NET 라이브러리를 로드하려고 시도해요. 계측이 필요한 애플리케이션으로만 계측을 제한해야 해요. 이 환경 변수를 전역으로 설정하지 마세요. 호스트의 모든 .NET 프로세스가 계측되기 때문이에요.

  1. 자동 계측이 애플리케이션에 연결되도록 다음 필수 환경 변수를 설정하세요.

    COR_ENABLE_PROFILING=1

  2. 독립 실행형 애플리케이션과 Windows 서비스는 애플리케이션을 수동으로 다시 시작하세요.

NuGet

패키지 readme의 지침을 따르세요. readme는 dd-trace-dotnet 저장소에서도 볼 수 있어요. Docker 예시도 저장소에서 확인할 수 있어요.

실시간 데이터 확인하기

서비스에서 .NET Tracer를 활성화한 후:

  1. 서비스를 다시 시작하세요.

  2. 애플리케이션 부하를 만들어요.

  3. Datadog에서 APM > APM Traces로 이동하세요.

구성 (Configuration)

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

커스텀 계측 (Custom instrumentation)

커스텀 계측은 자동 계측에 의존하며 방법에 따라 추가 단계가 필요해요.

참고: v3.0.0부터 커스텀 계측을 사용하려면 자동 계측도 함께 사용해야 해요. 자동 및 커스텀 계측 패키지 버전(예: MSI와 NuGet)을 동기화하고, 패키지의 메이저 버전을 섞지 않도록 하세요.

.NET 애플리케이션에서 커스텀 계측을 사용하려면:

  1. 자동 계측으로 애플리케이션을 계측하세요.
  2. 애플리케이션에 Datadog.Trace NuGet 패키지를 추가하세요.
  3. 애플리케이션 코드에서 Datadog.Trace.Tracer.Instance 속성으로 전역 트레이서에 접근해 새 스팬을 만드세요.

(NuGet 방식) .NET 애플리케이션에서 커스텀 계측을 사용하려면:

  1. 애플리케이션 코드에서 Datadog.Trace.Tracer.Instance 속성으로 전역 트레이서에 접근해 새 스팬을 만드세요.

커스텀 계측에 스팬·태그를 추가하는 방법에 대한 자세한 내용은 .NET 커스텀 계측 문서를 참고하세요.

프로세스 환경 변수 구성 (Configuring process environment variables)

자동 계측을 서비스에 연결하려면 애플리케이션을 시작하기 전에 필수 환경 변수를 설정해야 해요. .NET Tracer 설치 방법에 따라 설정할 환경 변수를 확인하려면 서비스에서 SDK 활성화하기 섹션을 참고하고, 계측된 서비스 환경에 따라 환경 변수를 올바르게 설정하려면 아래 예시를 따르세요.

참고: .NET 런타임은 이러한 환경 변수가 설정된 상태로 시작되는 모든 .NET 프로세스에 .NET 라이브러리를 로드하려고 시도해요. 계측이 필요한 애플리케이션으로만 계측을 제한해야 해요. 이 환경 변수를 전역으로 설정하지 마세요. 호스트의 모든 .NET 프로세스가 계측되기 때문이에요.

Windows 서비스

레지스트리 편집기에서 HKLM\System\CurrentControlSet\Services\<SERVICE NAME> 키에 Environment라는 다중 문자열 값을 만들고 값 데이터를 다음으로 설정하세요.

COR_ENABLE_PROFILING=1

PowerShell:

Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<SERVICE NAME> -Name Environment -Value 'COR_ENABLE_PROFILING=1'

IIS

MSI를 설치한 후에는 IIS 사이트를 자동 계측하기 위해 추가 구성이 필요하지 않아요. 모든 IIS 사이트가 상속하는 추가 환경 변수를 설정하려면 다음 단계를 수행하세요.

  1. 레지스트리 편집기를 열고 HKLM\System\CurrentControlSet\Services\WAS 키에서 Environment라는 다중 문자열 값을 찾아 환경 변수를 한 줄에 하나씩 추가하세요. 예를 들어 로그 주입과 런타임 메트릭을 추가하려면 값 데이터에 다음 줄을 추가하세요. 
    DD_LOGS_INJECTION=true
DD_RUNTIME_METRICS_ENABLED=true
  2. 다음 명령을 실행해 IIS를 다시 시작하세요. 
    net stop /y was
net start w3svc
# 또한 WAS가 종료됐을 때 중지된 다른 서비스도 시작하세요.

콘솔 애플리케이션

콘솔 애플리케이션을 자동 계측하려면 애플리케이션을 시작하기 전에 배치 파일에서 환경 변수를 설정하세요.

rem 필수 환경 변수 설정
SET COR_ENABLE_PROFILING=1

rem (선택) 추가 Datadog 환경 변수 설정, 예:
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true

rem 애플리케이션 시작
dotnet.exe example.dll

더 알아보기 (Learn more)

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