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

원문 보기 위키 갱신 2026.10.05

.NET Core 애플리케이션에 Datadog .NET Tracer를 설치하고 활성화해 트레이스를 Datadog으로 보내는 방법이에요. 플랫폼별 설치·활성화·환경 변수 설정을 다룹니다.

출처: 문서

본문

호환성 요구사항 (Compatibility requirements)

지원되는 .NET Core 런타임

.NET Tracer는 .NET Core 3.1, .NET 5, .NET 6, .NET 7, .NET 8, .NET 9, .NET 10에서 계측을 지원해요.

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

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

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

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

Trimmed 앱을 계측하려면 프로젝트에서 Datadog.Trace.Trimming NuGet 패키지를 참조하세요.

설치 (Installation)

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

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

SDK 설치하기

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

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

Windows

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

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

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

Linux

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

운영체제와 아키텍처를 지원하는 최신 .NET Tracer 패키지를 다운로드하세요.
다음 명령 중 하나를 실행해 패키지를 설치하고 적절한 권한으로 .NET tracer 로그 디렉터리 /var/log/datadog/dotnet을 만드세요.

Debian 또는 Ubuntu: sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && /opt/datadog/createLogPath.sh

CentOS 또는 Fedora: sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && /opt/datadog/createLogPath.sh

Alpine 또는 기타 musl 기반 배포판: sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>-musl.tar.gz && sh /opt/datadog/createLogPath.sh

기타 배포판: sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>.tar.gz && /opt/datadog/createLogPath.sh

Chiseled 컨테이너

셸이 없는 chiseled 또는 distroless Docker 이미지에 .NET Tracer를 설치하려면 다음 Dockerfile 명령을 사용하세요.

ADD를 사용해 SDK 파일을 컨테이너에 넣으세요.
빈 폴더를 소스로 하는 COPY --chown=$APP_UID를 사용해 로그 경로를 만드세요.

예를 들어 Dockerfile에서:

ADD datadog-dotnet-apm-<TRACER_VERSION>.tar.gz /opt/datadog/
COPY --chown=$APP_UID --from=<OTHER_STAGE> /empty/ /var/log/datadog/dotnet/

NuGet

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

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

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

서비스에서 SDK 활성화하기

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

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

Windows

Internet Information Services (IIS)

.NET Tracer MSI 설치 프로그램이 필요한 모든 환경 변수를 추가해요. 구성할 환경 변수는 없어요. 참고: Microsoft가 권장하듯 애플리케이션 풀의 .NET CLR 버전을 No Managed Code로 설정해야 해요.
IIS에서 호스팅되는 애플리케이션을 자동 계측하려면 관리자 권한으로 다음 명령을 실행해 IIS를 완전히 중지했다가 시작하세요.
```
net stop /y was
net start w3svc
# 또한 WAS가 종료됐을 때 중지된 다른 서비스도 시작하세요.
```

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

IIS에 없는 서비스

자동 계측이 애플리케이션에 연결되도록 다음 필수 환경 변수를 설정하세요.
```
CORECLR_ENABLE_PROFILING=1
```
독립 실행형 애플리케이션과 Windows 서비스는 애플리케이션을 수동으로 다시 시작하세요.

Linux

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

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
DD_DOTNET_TRACER_HOME=/opt/datadog

독립 실행형 애플리케이션은 평소처럼 수동으로 다시 시작하세요.

NuGet

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

실시간 데이터 확인하기

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

서비스를 다시 시작하세요.
애플리케이션 부하를 만들어요.
Datadog에서 APM > APM Traces로 이동하세요.

구성 (Configuration)

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

커스텀 계측 (Custom instrumentation)

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

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

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

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

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

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

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

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

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

Windows

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

Windows 서비스

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

CORECLR_ENABLE_PROFILING=1

PowerShell:

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

IIS

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

레지스트리 편집기를 열고 HKLM\System\CurrentControlSet\Services\WAS 키에서 Environment라는 다중 문자열 값을 찾아 환경 변수를 한 줄에 하나씩 추가하세요. 예를 들어 로그 주입과 런타임 메트릭을 추가하려면 값 데이터에 다음 줄을 추가하세요.
```
DD_LOGS_INJECTION=true
DD_RUNTIME_METRICS_ENABLED=true
```

다음 명령을 실행해 IIS를 다시 시작하세요.

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

콘솔 애플리케이션

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

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

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

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

Linux

Bash 스크립트

애플리케이션을 시작하기 전에 bash 파일에서 필수 환경 변수를 설정하려면:

# 필수 환경 변수 설정
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
export CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
export DD_DOTNET_TRACER_HOME=/opt/datadog

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

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

Alpine Linux를 사용한다면 CORECLR_PROFILER_PATH 환경 변수를 musl 기반 배포판용 경로 linux-musl-x64/로 설정하세요.

Linux Docker 컨테이너

Linux Docker 컨테이너에서 필수 환경 변수를 설정하려면:

# 필수 환경 변수 설정
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
ENV DD_DOTNET_TRACER_HOME=/opt/datadog

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

# 애플리케이션 시작
CMD ["dotnet", "example.dll"]

`systemctl` (서비스별)

systemctl로 .NET 애플리케이션을 서비스로 실행할 때, 특정 서비스에 로드될 필수 환경 변수를 추가할 수 있어요.

다음을 포함하는 environment.env라는 파일을 만드세요.

# 필수 환경 변수 설정
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
DD_DOTNET_TRACER_HOME=/opt/datadog

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

서비스 구성 파일에서 서비스 블록에 이것을 EnvironmentFile로 참조하세요.

[Service]
EnvironmentFile=/path/to/environment.env
ExecStart=<command used to start the application>

환경 변수 설정이 적용되도록 .NET 서비스를 다시 시작하세요.

`systemctl` (모든 서비스)

systemctl로 .NET 애플리케이션을 서비스로 실행할 때, systemctl이 실행하는 모든 서비스에 로드될 환경 변수를 설정할 수도 있어요.

systemctl set-environment를 실행해 필수 환경 변수를 설정하세요.

# 필수 환경 변수 설정
systemctl set-environment CORECLR_ENABLE_PROFILING=1
systemctl set-environment CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
systemctl set-environment CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog

# (선택) 추가 Datadog 환경 변수 설정, 예:
systemctl set-environment DD_LOGS_INJECTION=true
systemctl set-environment DD_RUNTIME_METRICS_ENABLED=true

systemctl show-environment를 실행해 환경 변수가 설정됐는지 확인하세요.
환경 변수가 적용되도록 .NET 서비스를 다시 시작하세요.

더 알아보기 (Learn more)

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

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

본문

호환성 요구사항 (Compatibility requirements)

지원되는 .NET Core 런타임

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

설치 (Installation)

SDK 설치하기

Windows

Linux

Chiseled 컨테이너

NuGet

서비스에서 SDK 활성화하기

Windows

Internet Information Services (IIS)

IIS에 없는 서비스

Linux

NuGet

실시간 데이터 확인하기

구성 (Configuration)

커스텀 계측 (Custom instrumentation)

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

Windows

Windows 서비스

IIS

콘솔 애플리케이션

Linux

Bash 스크립트

Linux Docker 컨테이너

systemctl (서비스별)

systemctl (모든 서비스)

더 알아보기 (Learn more)

`systemctl` (서비스별)

`systemctl` (모든 서비스)