System.Net 라이브러리의 분산 추적

아티클
01/31/2025

분산 추적 엔지니어가 애플리케이션 내의 오류 및 성능 문제, 특히 여러 컴퓨터 또는 프로세스에 분산된 문제를 지역화하는 데 도움이 되는 진단 기술입니다. 이 기술은 서로 다른 구성 요소에서 수행하는 작업을 상호 연결하고 애플리케이션이 동시 요청에 대해 수행할 수 있는 다른 작업과 분리하여 애플리케이션을 통해 요청을 추적합니다. 예를 들어 일반적인 웹 서비스에 대한 요청은 먼저 부하 분산 장치에서 받은 다음 웹 서버 프로세스로 전달된 다음 데이터베이스에 여러 쿼리를 수행합니다. 분산 추적을 사용하면 엔지니어가 이러한 단계 중 실패한 단계와 각 단계의 소요 기간을 구분할 수 있습니다. 실행될 때 각 단계에서 생성된 메시지를 기록할 수도 있습니다.

.NET의 추적 시스템은 OTel(OpenTelemetry)과 작동하도록 설계되었으며 OTel을 사용하여 데이터를 모니터링 시스템으로 내보냅니다. .NET의 추적은 System.Diagnostics API를 사용하여 구현됩니다. 여기서 작업 단위는 OTel 범위해당하는 System.Diagnostics.Activity 클래스로 표시됩니다. OpenTelemetry는 의미 체계 규칙이라고 하는 특성(태그)과 함께 범위(활동)에 대한 업계 전반의 표준 명명 체계를 정의합니다. .NET 원격 분석은 가능한 경우 기존 의미 체계 규칙을 사용합니다.

메모

용어는 및 활동 이 문서의 동의어입니다. .NET 코드의 컨텍스트에서 System.Diagnostics.Activity 인스턴스를 참조합니다. OTel 범위를 System.Span<T>혼동하지 마세요.

팁

태그/특성과 함께 모든 기본 제공 활동의 포괄적인 목록은 .NET 기본 제공 활동을 참조하세요.

계측

추적을 내보내기 위해 System.Net 라이브러리는 기본 제공 ActivitySource 원본을 사용하여 계측된 수행된 작업을 추적하는 Activity 개체를 만듭니다. 활동은 ActivitySource구독하는 수신기가 있는 경우에만 만들어집니다.

기본 제공 계측은 .NET 버전으로 발전했습니다.

.NET 8 이하에서는 계측이 빈 HTTP 클라이언트 요청 작업만들기로 제한됩니다. 즉, 사용자는 OpenTelemetry.Instrumentation.Http 라이브러리를 사용하여 유용한 추적을 내보내는 데 필요한 정보(예: 태그)로 활동을 채워야 합니다.
.NET 9는 HTTP 클라이언트 요청 활동에서 OTel HTTP 클라이언트 의미 체계 규칙에 따라 이름, 상태, 예외 정보, 그리고 가장 중요한 태그를 내보내어 계측을 확장했습니다. 즉, 보강 같은 고급 기능이 필요하지 않으면 .NET 9 이상에서 OpenTelemetry.Instrumentation.Http 종속성을 생략할 수 있습니다.
.NET 9는 또한 실험적 연결 추적도입하여 System.Net 라이브러리에 새로운 활동을 추가하여 연결 문제 진단을 지원합니다.

System.Net 추적 수집

가장 낮은 수준추적 컬렉션은 사용자 정의 논리를 포함하는 ActivityListener 개체를 등록하는 AddActivityListener 메서드를 통해 지원됩니다.

그러나 애플리케이션 개발자는 OpenTelemetry .NET SDK 제공된 기능을 기반으로 구축된 풍부한 에코시스템을 사용하여 추적을 수집, 내보내기 및 모니터링하는 것이 좋습니다.

OTel을 사용하여 추적 컬렉션에 대한 기본적인 이해를 얻으려면 OpenTelemetry 사용하여 추적을 수집하는가이드를 참조하세요.
프로덕션 시간 추적 수집 및 모니터링을 위해 OpenTelemetry를 Prometheus, Grafana, Jaeger와 함께 사용하거나, Azure Monitor 및 Application Insights와 함께 사용할 수 있습니다. 그러나 이러한 도구는 매우 복잡하며 개발 시 사용하기가 불편할 수 있습니다.
개발 시간 추적 수집 및 모니터링의 경우 애플리케이션에서 분산 추적을 시작하고 로컬에서 문제를 진단하는 간단하지만 확장 가능한 방법을 제공하는 .NET Aspire 사용하는 것이 좋습니다.
또한 Aspire 오케스트레이션 없이 Aspire Service 기본 설정 프로젝트를 재사용할 수도 있습니다. 이는 ASP.NET 프로젝트에서 OpenTelemetry 추적 및 메트릭을 소개하고 구성하는 편리한 방법입니다.

.NET Aspire를 사용하여 추적 수집

ASP.NET 애플리케이션에서 추적 및 메트릭을 수집하는 간단한 방법은 .NET Aspire사용하는 것입니다. .NET Aspire는 분산 애플리케이션을 쉽게 만들고 사용할 수 있도록 .NET에 대한 확장 집합입니다. .NET Aspire를 사용할 때의 이점 중 하나는 .NET용 OpenTelemetry 라이브러리를 사용하여 원격 분석이 기본 제공된다는 것입니다.

.NET Aspire의 기본 프로젝트 템플릿에는 ServiceDefaults 프로젝트가 포함되어 있습니다. .NET Aspire 솔루션의 각 서비스에는 서비스 기본값 프로젝트에 대한 참조가 있습니다. 서비스는 OTel을 설정하고 구성하는 데 사용합니다.

서비스 기본값 프로젝트 템플릿에는 OTel SDK, ASP.NET, HttpClient 및 런타임 계측 패키지가 포함됩니다. 이러한 계측 구성 요소는 Extensions.cs 파일에 구성됩니다. Aspire 대시보드에서 원격 분석 시각화를 지원하기 위해 서비스 기본값 프로젝트에는 기본적으로 OTLP 내보내기도 포함됩니다.

Aspire 대시보드는 로컬 디버그 주기에 원격 분석 관찰을 제공하도록 설계되어 개발자가 애플리케이션에서 원격 분석을 생성하도록 할 수 있습니다. 원격 분석 시각화는 이러한 애플리케이션을 로컬로 진단하는 데도 도움이 됩니다. 서비스 간의 호출을 관찰할 수 있다는 것은 프로덕션에서처럼 디버그 시 유용합니다. .NET Aspire 대시보드는 Visual Studio에서 AppHost 프로젝트를 F5를 명령줄에서 AppHost 프로젝트를 dotnet run 때 자동으로 시작됩니다.

.NET Aspire에 대한 자세한 내용은 다음을 참조하세요.

.NET Aspire 오케스트레이션 없이 서비스 기본값 프로젝트 다시 사용

Aspire Service Defaults 프로젝트는 오케스트레이션에 AppHost와 같은 나머지 .NET Aspire 사용하지 않더라도 ASP.NET 프로젝트에 OTel을 쉽게 구성할 수 있는 방법을 제공합니다. 서비스 기본값 프로젝트는 Visual Studio 또는 dotnet new통해 프로젝트 템플릿으로 사용할 수 있습니다. OTel을 구성하고 OTLP 내보내기를 설정합니다. 그런 다음 OTel 환경 변수 사용하여 원격 분석을 보내고 애플리케이션에 대한 리소스 속성을 제공하도록 OTLP 엔드포인트를 구성할 수 있습니다.

.NET Aspire 외부에서 ServiceDefaults 사용하는 단계는 다음과 같습니다.

Visual Studio에서 새 프로젝트 추가를 사용하여 ServiceDefaults 프로젝트를 솔루션에 추가하거나 dotnet new사용합니다.
```
dotnet new aspire-servicedefaults --output ServiceDefaults
```
ASP.NET 애플리케이션에서 ServiceDefaults 프로젝트를 참조합니다. Visual Studio에서 >추가 프로젝트 참조선택하고 ServiceDefaults 프로젝트"를 선택합니다.

애플리케이션 작성기 초기화의 일부로 OpenTelemetry 설치 함수 ConfigureOpenTelemetry() 호출합니다.

var builder = WebApplication.CreateBuilder(args)
builder.ConfigureOpenTelemetry(); // Extension method from ServiceDefaults.
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();

전체 설명은 예제: OTLP와 함께 OpenTelemetry 사용 및 독립 실행형 Aspire 대시보드를에서 확인하십시오.

실험적 연결 추적

HttpClient 문제 또는 병목 상태를 해결할 때 HTTP 요청을 보낼 때 소요되는 시간을 확인하는 것이 중요할 수 있습니다. 일반적으로 DNS 조회, TCP 연결 및 TLS 핸드셰이크로 분류되는 HTTP 연결 설정 중에 문제가 발생합니다.

.NET 9에서는 연결 설정의 DNS, TCP 및 TLS 단계를 나타내는 3개의 자식 범위가 있는 HTTP connection setup 범위를 추가하는 실험적 연결 추적을 도입했습니다. 연결 추적의 HTTP 부분은 SocketsHttpHandler내에서 구현됩니다. 즉, 활동 모델은 기본 연결 풀링 동작을 준수해야 합니다.

메모

SocketsHttpHandler연결 및 요청에는 독립적인 수명 주기가 있습니다. 풀된 연결 오랜 시간 동안 유지될 수 있으며 많은 요청을 처리할 수 있습니다. 요청을 수행할 때 연결 풀에서 즉시 사용할 수 있는 연결이 없는 경우 요청이 요청 큐에 추가되어 사용 가능한 연결을 기다립니다. 대기 요청과 연결 사이에는 직접적인 관계가 없습니다. 다른 연결을 사용할 수 있게 되었을 때 연결 프로세스가 시작되었을 수 있습니다. 이 경우 해제된 연결이 사용됩니다. 따라서 HTTP connection setup 범위는 HTTP client request 범위의 자식으로 모델링되지 않습니다. 대신 범위 링크가 사용됩니다.

.NET 9에서는 자세한 연결 정보를 수집할 수 있도록 다음 범위를 도입했습니다.

이름	ActivitySource	묘사
`HTTP wait_for_connection`	`Experimental.System.Net.Http.Connections`	요청 큐에서 사용 가능한 연결을 기다리는 시간 간격을 나타내는 `HTTP client request` 범위의 하위 범위입니다.
`HTTP connection_setup`	`Experimental.System.Net.Http.Connections`	HTTP 연결의 설치를 나타냅니다. 자체 `TraceId`있는 별도의 추적 루트 범위입니다. `HTTP client request` 범위에는 `HTTP connection_setup`대한 링크가 포함될 수 있습니다.
`DNS lookup`	`Experimental.System.Net.NameResolution`	Dns 클래스에서 수행하는 DNS 조회입니다.
`socket connect`	`Experimental.System.Net.Sockets`	Socket 연결 설정
`TLS handshake`	`Experimental.System.Net.Security`	TLS 클라이언트 또는 서버 핸드셰이크가 SslStream에 의해 수행됩니다.

메모

해당 ActivitySource 이름은 Experimental접두사로 시작합니다. 이러한 범위는 프로덕션 환경에서 얼마나 잘 작동하는지에 대해 자세히 알아보면서 이후 버전에서 변경될 수 있습니다.

이러한 범위는 워크로드가 많은 프로덕션 시나리오에서 24x7을 사용하기에는 너무 자세한 정보입니다. 이는 시끄럽고 일반적으로 이 수준의 계측이 필요하지 않습니다. 그러나 연결 문제를 진단하거나 네트워크 및 연결 대기 시간이 서비스에 미치는 영향을 자세히 이해하려는 경우 다른 수단으로 수집하기 어려운 인사이트를 제공합니다.

Experimental.System.Net.Http.Connections ActivitySource를 사용하도록 설정하면 HTTP client request 범위에 요청제공하는 연결에 해당하는 HTTP connection_setup 범위에 대한 링크가 포함됩니다. HTTP 연결은 수명이 길어질 수 있으므로 각 요청 활동에서 연결 범위에 대한 많은 링크가 발생할 수 있습니다. 일부 APM 모니터링 도구는 보기 화면을 구축하기 위해 범위 간 링크를 적극적으로 탐색하므로, 이 범위를 포함하면 많은 링크를 처리할 수 없도록 설계된 경우 문제가 발생할 수 있습니다.

다음 다이어그램은 범위 및 해당 관계의 동작을 보여 줍니다.

.NET 9에서 실험적 연결 추적 사용 안내

이 연습에서는 .NET 9 Aspire Starter 앱을 사용하여 연결 추적을 시연합니다. 하지만 다른 모니터링 도구 를 사용해도 쉽게 설정할 수 있습니다. 주요 단계는 ActivitySources를 사용하도록 설정하는 것입니다.

dotnet new를 사용하여 .NET Aspire 9 Starter 앱을 만드십시오.
```
dotnet new aspire-starter-9 --output ConnectionTracingDemo
```
또는 Visual Studio에서 다음을 수행합니다.

ServiceDefaults 프로젝트에서 Extensions.cs을 열고, 추적 구성 콜백에서 연결에 필요한 ActivitySources를 추가하도록 ConfigureOpenTelemetry 메서드를 편집합니다.

.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation()
        // Instead of using .AddHttpClientInstrumentation()
        // .NET 9 allows to add the ActivitySources directly.
        .AddSource("System.Net.Http")
        // Add the experimental connection tracking ActivitySources using a wildcard.
        .AddSource("Experimental.System.Net.*");
});

솔루션을 시작합니다. 그러면 .NET Aspire 대시보드 열립니다.
webfrontend 앱의 날씨 페이지로 이동하여 apiservice쪽으로 HttpClient 요청을 생성합니다.
대시보드로 돌아가서 흔적 페이지로 이동합니다. webfrontend: GET /weather 추적을 엽니다.

Aspire 대시보드

연결 계측을 사용하도록 설정된 상태에서 HTTP 요청을 수행하면 클라이언트 요청 범위에 다음과 같은 변경 내용이 표시됩니다.

연결을 설정해야 하거나 앱이 연결 풀에서 연결을 기다리는 경우 추가 HTTP wait_for_connection 범위가 표시되며 이는 연결이 만들어질 때까지 기다리는 지연을 나타냅니다. 이렇게 하면 코드에서 수행되는 HttpClient 요청과 요청 처리가 실제로 시작되는 시점 사이의 지연을 이해하는 데 도움이 됩니다. 이전 이미지에서:
- 선택한 범위는 HttpClient 요청입니다.
- 아래 범위는 요청이 연결이 설정되기를 기다리는 데 소요되는 시간을 나타냅니다.
- 노란색의 마지막 범위는 요청을 처리하는 대상에서 가져옵니다.
HttpClient 범위에는 요청에 사용되는 HTTP 연결을 만드는 활동을 나타내는 HTTP connection_setup 범위에 대한 링크가 있습니다.

에 포함됩니다.

앞서설명한 대로 HTTP connection_setup 범위는 고유한 TraceId있는 별도의 범위이며 수명은 각 개별 클라이언트 요청과 독립적입니다. 이 범위에는 일반적으로 자식 범위 DNS lookup, (TCP) socket connect및 TLS client handshake가 있습니다.

농축

경우에 따라 기존 System.Net 추적 기능을 보강해야 합니다. 일반적으로 이는 기본 제공 작업에 추가 태그/특성을 삽입하는 것을 의미합니다. 이것을 보강이라 부릅니다.

OpenTelemetry 계측 라이브러리의 보강 API

HTTP 클라이언트 요청 활동에 태그/특성을 추가하려면 가장 간단한 방법은 OpenTelemetry HttpClient 및 HttpWebRequest 계측 라이브러리의 HttpClient 보강 API를 사용하는 것입니다. 이렇게 하려면 OpenTelemetry.Instrumentation.Http 패키지에 종속되어야 합니다.

수동 보강

HTTP client request 활동의 강화를 수동으로 수행할 수 있습니다. 이를 위해 작업이 완료되기 전에 요청 활동의 범위에서 실행되는 코드의 Activity.Current 액세스해야 합니다. 이 작업은 IObserver<DiagnosticListener> 구현하고 AllListeners 구독하여 네트워킹 작업이 발생하는 경우에 대한 콜백을 가져와서 수행할 수 있습니다. 실제로 OpenTelemetry HttpClient 및 HttpWebRequest 계측 라이브러리는 이렇게 구현되었습니다. 코드 예제는 DiagnosticSourceSubscriber.cs 구독 코드와 알림이 위임된 HttpHandlerDiagnosticListener.cs 기본 구현을 참조하세요.

더 많은 추적이 필요하세요?

추적을 통해 노출될 수 있는 다른 유용한 정보에 대한 제안이 있는 경우 dotnet/runtime 이슈을 만듭니다.

다음을 통해 공유