예시: OTLP 및 독립 실행형 Aspire 대시보드에서 OpenTelemetry 사용

이는 OpenTelemetry를 사용한 .NET 가시성을 설명하는 일련의 예제 중 하나입니다.

.NET Aspire의 표준 부분일 뿐만 아니라, Aspire 대시보드는 OTLP 엔드포인트 원격 분석을 전송할 수 있는 독립 실행형 docker 컨테이너로 사용할 수 있으며 로그, 메트릭 및 추적을 시각화합니다. 이러한 방식으로 대시보드를 사용하면 .NET Aspire에 대한 종속성이 없으므로 OTLP를 통해 원격 분석을 보내는 모든 애플리케이션에서 원격 분석을 시각화합니다. 원격 분석을 OTLP 엔드포인트로 전송할 수 있다면 Java, GoLang, Python 등으로 작성된 애플리케이션에서도 똑같이 잘 작동합니다.

Aspire 대시보드를 사용하면 Prometheus, Grafana 및 Jaeger와 같은 오픈 소스 솔루션을 사용하는 것보다 구성 및 설정 단계가 적지만, 이러한 도구와 달리 Aspire 대시보드는 프로덕션 모니터링이 아닌 개발자 시각화 도구로 사용됩니다.

1. 프로젝트 만들기

Visual Studio에서 ASP.NET Core Empty 템플릿을 사용하거나 다음 .NET CLI 명령을 사용하여 간단한 웹 API 프로젝트를 만듭니다.

dotnet new web

2. 메트릭 및 활동 정의 추가

다음 코드는 API가 호출된 횟수에 대한 새 메트릭(greetings.count)과 새 활동 소스(Otel.Example)를 정의합니다.

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3. API 엔드포인트 만들기

다음을 builder.Build(); 및 app.Run() 사이에 삽입

app.MapGet("/", SendGreeting);

파일의 밑 부분에 다음 기능을 삽입합니다.

async Task<String> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

4. OpenTelemetry 패키지 참조

NuGet 패키지 관리자 또는 명령줄을 사용하여 다음 NuGet 패키지를 추가합니다.

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

5. 올바른 공급자를 사용하여 OpenTelemetry 구성

builder.Build(); 전에 다음 코드를 삽입합니다.

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

이 코드는 다양한 원격 분석 소스를 사용하여 OpenTelemetry를 설정합니다.

• 로그 기록을 수집하기 위해 ILogger에 OTel 공급자를 추가합니다.
• 메트릭을 설정하고, 계측 공급자 및 ASP.NET용 미터와 사용자 지정 미터를 등록합니다.
• 추적, 계측 공급자 및 사용자 지정 ActivitySource 등록을 설정합니다.

그런 다음 환경 변수를 사용하여 OTLP 내보내기를 구성에 등록합니다.

6. OTLP 환경 변수 구성

OTLP 내보내기는 코드의 API를 통해 구성할 수도 있지만 환경 변수를 통해 구성하는 것이 더 일반적입니다. 다음을 AppSettings.Development.json에 추가합니다.

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

.NET OTLP 내보내기 또는 리소스 특성을 정의하는 것 OTEL_RESOURCE_ATTRIBUTES 등의 일반적인 OTel 변수에 대한 환경 변수를 추가할 수 있습니다.

7. Aspire 대시보드 컨테이너 시작

Docker를 사용하여 대시보드 컨테이너를 다운로드하고 실행합니다.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

대시보드에 표시되는 데이터는 중요할 수 있습니다. 기본적으로 대시보드는 로그인 시 토큰이 필요한 인증으로 보안이 설정되어 있습니다. 토큰은 컨테이너를 실행할 때 결과 출력에 표시됩니다.

[]

표시된 URL을 복사하고 0.0.0.0을(를) localhost(예: http://localhost:18888/login?t=123456780abcdef123456780)(으)로 교체하고 브라우저에서 열거나 로그인 대화 상자가 표시되면 /login?t= 뒤에 키를 붙여넣을 수도 있습니다. 컨테이너를 시작할 때마다 토큰이 변경됩니다.

8. 프로젝트 실행

프로젝트를 실행한 다음, 브라우저 또는 curl을 사용하여 API에 액세스합니다.

curl -k http://localhost:7275

페이지를 요청할 때마다 만들어진 인사말 수의 수가 증가합니다.

8.1 로그 출력

코드의 로깅 문은 ILogger를 사용하여 출력됩니다. 출력이 콘솔로 전달되도록 콘솔 공급자는 기본적으로 활성화됩니다.

.NET에서 로그를 송신하는 방법에는 몇 가지 옵션이 있습니다.

• stdout 및 stderr 출력은 Kubernetes와 같은 컨테이너 시스템에 의해 로그 파일로 리디렉션됩니다.
• ILogger와 통합할 로깅 라이브러리를 사용하면 Serilog 또는 NLog가 포함됩니다.
• OTel에 대한 로깅 공급자 사용(예: OTLP) 5단계의 코드에서 로깅 섹션은 OTel 공급자를 추가합니다.

로그는 대시보드에 구조화된 로그로 표시되며, 로그 메시지에서 설정한 모든 속성은 로그 레코드의 필드로 추출됩니다.

8.2 메트릭 보기

Aspire 대시보드는 리소스별로 메트릭을 표시합니다(리소스는 프로세스와 같은 원격 분석 원본에 대해 이야기하는 OTel 방식임). 리소스를 선택하면 대시보드에 리소스에 의해 해당 OTLP 엔드포인트로 전송된 각 메트릭이 열거됩니다. 메트릭 목록은 동적이며 새로운 메트릭이 수신되면 업데이트됩니다.

메트릭에 대한 보기는 사용 중인 메트릭 유형에 따라 달라집니다.

• Counter가 직접 표시됩니다.
• 요청당 전송된 시간 또는 바이트와 같이 요청당 값을 추적하는 히스토그램은 일련의 버킷으로 수집됩니다. 대시보드는 P50, P90 및 P99 백분위수 그래프를 표시합니다. 히스토그램 결과에는 해당 요청에 대한 trace/spanId와 함께 개별 데이터 포인트인 예시가 포함될 수 있습니다. 그래프에 점으로 표시됩니다. 하나를 선택하면 해당 추적으로 이동하여 해당 값의 원인이 무엇인지 확인할 수 있습니다. 이는 이상값을 진단하는 데 유용합니다.
• 메트릭에는 개별 값과 연관된 키/값 쌍인 차원이 포함될 수 있습니다. 값은 차원별로 집계됩니다. 보기의 드롭다운을 사용하여 결과를 필터링하고 특정 차원(예: GET 요청만 또는 ASP.NET 특정 URL 경로에 대한 차원)을 확인할 수 있습니다.

8.3 추적 보기

추적 보기에는 추적 목록이 표시됩니다. 각 추적은 동일한 traceId를 공유하는 활동 집합입니다. 작업은 작업 단위를 나타내는 범위로 추적됩니다. ASP.NET 요청을 처리하면 범위가 생성됩니다. HttpClient 요청을 만드는 것은 범위가 됩니다. 범위의 부모를 추적하여 범위 계층 구조를 시각화할 수 있습니다. 각 리소스(프로세스)에서 범위를 수집하여 일련의 서비스에서 발생하는 작업을 추적합니다. Http 요청에는 traceId와 상위 spanId를 다음 서비스로 전달하는 데 사용되는 헤더가 있습니다. 각 리소스는 원격 분석을 수집하고 동일한 수집기로 보내야 합니다. 그런 다음, 범위의 계층 구조를 집계하고 표시합니다.

대시보드에는 요약 정보가 포함된 추적 목록이 표시됩니다. 새 traceId가 있는 범위가 발견될 때마다 테이블에 행이 표시됩니다. 보기를 클릭하면 추적의 모든 범위가 표시됩니다.

범위를 선택하면 3단계에서 설정한 greeting 태그와 같은 범위의 모든 속성을 포함하여 세부 정보가 표시됩니다.