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

트러블슈팅에 .NET 진단 도구 사용하기 (Using the .NET diagnostic tool for troubleshooting)

원문 보기 위키 갱신

.NET 트레이서를 설치한 후에도 애플리케이션이 예상대로 트레이스를 생성하지 않는다면, 이 페이지에서 설명하는 진단 도구 dd-dotnet을 실행해 기본적인 트러블슈팅을 해보세요. 이 도구는 환경 변수 누락, 불완전한 설치, 또는 Agent에 접근할 수 없는 문제 등 설정의 문제를 파악하는 데 도움을 줘요.

진단 도구 dd-dotnet은 2.42.0 버전부터 SDK에 포함되어 있어요. SDK 설치 폴더에 있으며, 어디서든 호출할 수 있도록 시스템 PATH에 자동으로 추가됩니다.

출처: 문서

본문

dd-trace 설치 (Installing dd-trace)

이 섹션은 2.42.0보다 오래된 SDK 버전을 위한 내용이에요.

이전 버전의 SDK에는 dd-dotnet 도구가 포함되어 있지 않았어요. 대신 dd-trace 도구를 설치할 수 있어요. 그 기능과 구문은 dd-dotnet과 유사합니다.

dd-trace는 다음 방법 중 하나로 설치할 수 있어요:

다음 섹션에서 명령을 실행할 때는 dd-dotnet을 dd-trace로 바꿔서 사용하세요.

프로세스 진단 (Process diagnostics)

대부분의 애플리케이션에서는 프로세스 진단을 사용해 문제를 찾을 수 있어요.

  1. 애플리케이션이 실행 중인지 확인하고, 프로세스 ID(pid)를 가져옵니다.

Windows 프로세스의 pid를 얻으려면 작업 관리자(Task Manager)를 열고 Details 탭에서 PID 열을 확인하세요. tasklist /FI "IMAGENAME eq target.exe" 명령을 실행할 수도 있어요. 여기서 target.exe는 프로세스 이름입니다.

Linux에서 프로세스의 pid를 얻으려면 ps aux | grep target 명령을 실행하세요. 여기서 target은 프로세스 이름입니다(Docker 컨테이너에서 실행 중일 때 pid는 보통 1이에요).

  1. pid를 dd-dotnet 도구에 전달합니다:

    dd-dotnet check process <pid>

이 명령은 기본 구성 검사를 실행하고, 문제가 발견되면 권장 사항을 표시합니다.

문제가 없는 경우의 출력 예시:

$ dd-dotnet check process 35888

Running checks on process 35888
Process name: SimpleApp

---- STARTING TRACER SETUP CHECKS -----
Target process is running with .NET Core
1. Checking Modules Needed so the Tracer Loads:
 [SUCCESS]: The native library version 2.42.0.0 is loaded into the process.
 [SUCCESS]: The tracer version 2.42.0.0 is loaded into the process.
2. Checking DD_DOTNET_TRACER_HOME and related configuration value:
 [SUCCESS]: DD_DOTNET_TRACER_HOME is set to 'C:\git\dd-trace-dotnet-2\shared\bin\monitoring-home\win-x64\..' and the
directory was found correctly.
3. Checking CORECLR_PROFILER_PATH and related configuration value:
 [SUCCESS]: The environment variable CORECLR_PROFILER_PATH_32 is set to the correct value of
C:\git\dd-trace-dotnet-2\shared\bin\monitoring-home\win-x86\Datadog.Trace.ClrProfiler.Native.dll.
 [SUCCESS]: The environment variable CORECLR_PROFILER_PATH_64 is set to the correct value of
C:\git\dd-trace-dotnet-2\shared\bin\monitoring-home\win-x64\Datadog.Trace.ClrProfiler.Native.dll.
4. Checking CORECLR_PROFILER and related configuration value:
 [SUCCESS]: The environment variable CORECLR_PROFILER is set to the correct value of
{846F5F1C-F9AE-4B07-969E-05C26BC060D8}.
5. Checking CORECLR_ENABLE_PROFILING and related configuration value:
 [SUCCESS]: The environment variable CORECLR_ENABLE_PROFILING is set to the correct value of 1.

---- CONFIGURATION CHECKS -----
1. Checking if tracing is disabled using DD_TRACE_ENABLED.
 [INFO]: DD_TRACE_ENABLED is not set, the default value is true.
2. Checking if profiling is enabled using DD_PROFILING_ENABLED.
 [INFO]: DD_PROFILING_ENABLED is not set, the continuous profiler is disabled.

---- DATADOG AGENT CHECKS -----
Detected agent url: http://127.0.0.1:8126/. Note: this url may be incorrect if you configured the application through a
configuration file.
Connecting to Agent at endpoint http://127.0.0.1:8126/ using HTTP
Detected agent version 7.48.0
 [SUCCESS]: No issue found with the target process.

문제가 있는 경우의 출력 예시:

$ dd-dotnet check process 4464

Running checks on process 4464
Process name: SimpleApp

---- STARTING TRACER SETUP CHECKS -----
Target process is running with .NET Core
1. Checking Modules Needed so the Tracer Loads:
 [WARNING]: The native loader library is not loaded into the process
 [WARNING]: The native tracer library is not loaded into the process
 [WARNING]: Tracer is not loaded into the process
2. Checking DD_DOTNET_TRACER_HOME and related configuration value:
 [WARNING]: DD_DOTNET_TRACER_HOME is set to 'C:\Program Files\Datadog\.NET Tracer\' but the directory does not exist.
3. Checking CORECLR_PROFILER_PATH and related configuration value:
 [FAILURE]: The environment variable CORECLR_PROFILER_PATH_32 is set to C:\Program Files\Datadog\.NET
Tracer\win-x86\Datadog.Trace.ClrProfiler.Native.dll but the file is missing or you don't have sufficient permission.
 [FAILURE]: The environment variable CORECLR_PROFILER_PATH_64 is set to C:\Program Files\Datadog\.NET
Tracer\win-x64\Datadog.Trace.ClrProfiler.Native.dll but the file is missing or you don't have sufficient permission.
4. Checking CORECLR_PROFILER and related configuration value:
 [SUCCESS]: The environment variable CORECLR_PROFILER is set to the correct value of
{846F5F1C-F9AE-4B07-969E-05C26BC060D8}.
5. Checking CORECLR_ENABLE_PROFILING and related configuration value:
 [FAILURE]: The environment variable CORECLR_ENABLE_PROFILING should be set to '1' (current value: not set)
6. Checking if process tracing configuration matches Installer or Bundler:
Installer/MSI related documentation:
https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/dotnet-core/?tab=windows#install-the-tracer
 [FAILURE]: Unable to find Datadog .NET Tracer program, make sure the tracer has been properly installed with the MSI.
 [WARNING]: The registry key SOFTWARE\Classes\CLSID\{846F5F1C-F9AE-4B07-969E-05C26BC060D8}\InprocServer32 is missing. If
using the MSI, make sure the installation was completed correctly try to repair/reinstall it.
 [WARNING]: The registry key SOFTWARE\Classes\Wow6432Node\CLSID\{846F5F1C-F9AE-4B07-969E-05C26BC060D8}\InprocServer32 is
missing. If using the MSI, make sure the installation was completed correctly try to repair/reinstall it.

IIS 진단 (IIS diagnostics)

IIS 애플리케이션의 경우 다음 명령을 사용해 더 자세한 진단을 받을 수 있어요. 여기서 <FULL SITE NAME>은 IIS의 사이트 이름 뒤에 애플리케이션 이름이 붙은 형태입니다:

dd-dotnet check iis "<FULL SITE NAME>"

IIS에서는 애플리케이션 풀이 지연 시작되므로, 명령을 실행하기 전에 사이트가 최소한 한 번의 요청을 받았는지 확인하세요.

이름에 공백이 있으면 따옴표로 묶어야 해요.

예를 들어, 아래 표시된 애플리케이션의 전체 사이트 이름은 Default Web Site/WebApplication1입니다:

{이미지: IIS 매니저}

이 애플리케이션에 대해 IIS 진단을 실행하는 명령은 다음과 같아요:

dd-dotnet check iis "Default Web Site/WebApplication1"

사이트의 루트 애플리케이션을 계측하려면 다음을 실행하세요:

dd-dotnet check iis "Default Web Site"

check iis 명령에는 프로세스 진단이 포함되어 있으며, 기본 구성 검사를 실행하고 문제가 발견되면 권장 사항을 표시합니다.

문제가 없는 경우의 출력 예시:

$ dd-dotnet check iis "Default Web Site/WebFormsTestApp"

Fetching IIS application "Default Web Site/WebFormsTestApp".
Inspecting worker process 39852

---- STARTING TRACER SETUP CHECKS -----
Target process is running with .NET Framework
1. Checking Modules Needed so the Tracer Loads:
 [SUCCESS]: The native library version 2.42.0.0 is loaded into the process.
 [SUCCESS]: The tracer version 2.42.0.0 is loaded into the process.
2. Checking DD_DOTNET_TRACER_HOME and related configuration value:
 [SUCCESS]: DD_DOTNET_TRACER_HOME is set to 'C:\Program Files\Datadog\.NET Tracer\' and the directory was found
correctly.
3. Checking COR_PROFILER_PATH and related configuration value:
 [SUCCESS]: The environment variable COR_PROFILER_PATH_32 is set to the correct value of C:\Program Files\Datadog\.NET
Tracer\win-x86\Datadog.Trace.ClrProfiler.Native.dll.
 [SUCCESS]: The environment variable COR_PROFILER_PATH_64 is set to the correct value of C:\Program Files\Datadog\.NET
Tracer\win-x64\Datadog.Trace.ClrProfiler.Native.dll.
4. Checking COR_PROFILER and related configuration value:
 [SUCCESS]: The environment variable COR_PROFILER is set to the correct value of {846F5F1C-F9AE-4B07-969E-05C26BC060D8}.
5. Checking COR_ENABLE_PROFILING and related configuration value:
 [SUCCESS]: The environment variable COR_ENABLE_PROFILING is set to the correct value of 1.

---- CONFIGURATION CHECKS -----
1. Checking if tracing is disabled using DD_TRACE_ENABLED.
 [INFO]: DD_TRACE_ENABLED is not set, the default value is true.
2. Checking if profiling is enabled using DD_PROFILING_ENABLED.
 [INFO]: DD_PROFILING_ENABLED is not set, the continuous profiler is disabled.

---- DATADOG AGENT CHECKS -----
Detected agent url: http://127.0.0.1:8126/. Note: this url may be incorrect if you configured the application through a
configuration file.
Connecting to Agent at endpoint http://127.0.0.1:8126/ using HTTP
Detected agent version 7.48.0
Found Datadog.Trace version 2.42.0.0 in the GAC
 [SUCCESS]: No issue found with the IIS site.

문제가 있는 경우의 출력 예시:

$ dd-dotnet check iis "Default Web Site/WebFormsTestApp"

Fetching IIS application "Default Web Site/WebFormsTestApp".
Inspecting worker process 35152

---- STARTING TRACER SETUP CHECKS -----
Target process is running with .NET Framework
1. Checking Modules Needed so the Tracer Loads:
 [SUCCESS]: The native library version 2.42.0.0 is loaded into the process.
 [SUCCESS]: The tracer version 2.42.0.0 is loaded into the process.
2. Checking DD_DOTNET_TRACER_HOME and related configuration value:
 [SUCCESS]: DD_DOTNET_TRACER_HOME is set to 'C:\Program Files\Datadog\.NET Tracer\' and the directory was found
correctly.
3. Checking COR_PROFILER_PATH and related configuration value:
 [SUCCESS]: The environment variable COR_PROFILER_PATH_32 is set to the correct value of C:\Program Files\Datadog\.NET
Tracer\win-x86\Datadog.Trace.ClrProfiler.Native.dll.
 [SUCCESS]: The environment variable COR_PROFILER_PATH_64 is set to the correct value of C:\Program Files\Datadog\.NET
Tracer\win-x64\Datadog.Trace.ClrProfiler.Native.dll.
4. Checking COR_PROFILER and related configuration value:
 [SUCCESS]: The environment variable COR_PROFILER is set to the correct value of {846F5F1C-F9AE-4B07-969E-05C26BC060D8}.
5. Checking COR_ENABLE_PROFILING and related configuration value:
 [SUCCESS]: The environment variable COR_ENABLE_PROFILING is set to the correct value of 1.

---- CONFIGURATION CHECKS -----
1. Checking if tracing is disabled using DD_TRACE_ENABLED.
 [INFO]: DD_TRACE_ENABLED is not set, the default value is true.
2. Checking if profiling is enabled using DD_PROFILING_ENABLED.
 [INFO]: DD_PROFILING_ENABLED is not set, the continuous profiler is disabled.

---- DATADOG AGENT CHECKS -----
Detected agent url: http://127.0.0.1:8126/. Note: this url may be incorrect if you configured the application through a
configuration file.
Connecting to Agent at endpoint http://127.0.0.1:8126/ using HTTP
Detected agent version 7.48.0
 [FAILURE]: The Datadog.Trace assembly could not be found in the GAC. Make sure the tracer has been properly installed
with the MSI.

Agent 연결 진단 (Agent connectivity diagnostics)

특정 애플리케이션에 대한 검사를 실행하지 않고 Agent와의 연결만 테스트하려면 다음을 실행하세요:

dd-dotnet check agent <url>

이 명령은 Agent에 요청을 보내 오류가 있는지 확인합니다. 선택적 url 매개변수를 생략하면 Agent의 위치는 환경 변수에서 결정됩니다. 지원되는 프로토콜은 http:// 또는 unix://(도메인 소켓용)입니다.

문제가 없는 경우의 출력 예시:

$ dd-dotnet check agent

No Agent URL provided, using environment variables
Connecting to Agent at endpoint http://127.0.0.1:8126/ using HTTP
Detected agent version 7.48.0
 [SUCCESS]: Connected successfully to the Agent.

문제가 있는 경우의 출력 예시:

$ dd-dotnet check agent

No Agent URL provided, using environment variables
Connecting to Agent at endpoint http://127.0.0.1:8126/ using HTTP
 [FAILURE]: Error connecting to Agent at http://127.0.0.1:8126/: System.Net.Http.HttpRequestException: No connection
could be made because the target machine actively refused it. (127.0.0.1:8126)

Agent 연결 문제에 대한 자세한 내용은 연결 오류 (Connection Errors) 문서를 읽어보세요.

더 알아보기 (Learn more)