OpenTelemetry 추가, 수정 및 필터링

  • 아티클

이 문서에서는 Azure Monitor Application Insights를 사용하여 애플리케이션에 대해 OpenTelemetry를 추가하고, 수정하고, 필터링하는 방법에 대한 지침을 제공합니다.

OpenTelemetry 개념에 대한 자세한 내용은 OpenTelemetry 개요 또는 OpenTelemetry FAQ를 참조하세요.

자동 데이터 수집

배포판은 OpenTelemetry 계측 라이브러리를 번들로 묶어 데이터를 자동으로 수집합니다.

포함된 계측 라이브러리

요청

종속성

로깅

  • ILogger

ILogger에 대한 자세한 내용은 C# 및 .NET의 로깅 및 코드 예제를 참조하세요.

각주

  • ¹: ‘처리되지 않은/잡히지 않은’ 예외의 자동 보고 지원
  • ²: OpenTelemetry 메트릭 지원
  • ³: 로깅은 기본값으로 INFO 수준 이상에서만 수집됩니다. 이 설정을 변경하려면 구성 옵션을 참조하세요.
  • ⁴: 로깅은 기본값으로 경고 수준 이상에서 수행되는 경우에만 수집됩니다.

참고 항목

Azure Monitor OpenTelemetry 배포판에는 Application Insights 표준 메트릭을 자동으로 내보내는 사용자 지정 매핑 및 논리가 포함됩니다.

팁

계측 라이브러리에서 자동으로 수집되거나 사용자 지정 코딩에서 수동으로 수집되거나 관계없이 모든 OpenTelemetry 메트릭은 현재 청구 목적으로 Application Insights "사용자 지정 메트릭"으로 간주됩니다. 자세히 알아보기.

커뮤니티 계측 라이브러리 추가

OpenTelemetry 커뮤니티에서 계측 라이브러리를 포함하면 더 많은 데이터를 자동으로 수집할 수 있습니다.

주의

커뮤니티 계측 라이브러리의 품질을 지원하거나 보장하지 않습니다. 배포판에 대해 제안하려면 피드백 커뮤니티에 게시하거나 투표하세요. 일부는 실험적 OpenTelemetry 사양을 기반으로 하며 향후 호환성이 손상되는 변경이 발생할 수 있습니다.

커뮤니티 라이브러리를 추가하려면 라이브러리에 대한 NuGet 패키지를 추가한 후 ConfigureOpenTelemetryMeterProvider 또는 ConfigureOpenTelemetryTracerProvider 메서드를 사용합니다.

다음 예제에서는 런타임 계측 을 추가하여 추가 메트릭을 수집하는 방법을 보여 줍니다.

dotnet add package OpenTelemetry.Instrumentation.Runtime 

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

사용자 지정 원격 분석 수집

이 섹션에서는 애플리케이션에서 사용자 지정 원격 분석을 수집하는 방법을 설명합니다.

언어 및 신호 유형에 따라 다음을 포함하여 사용자 지정 원격 분석을 수집하는 다양한 방법이 있습니다.

  • OpenTelemetry API
  • 언어별 로깅/메트릭 라이브러리
  • Application Insights Classic API

다음 표는 현재 지원되는 사용자 지정 원격 분석 유형을 나타냅니다.

언어 사용자 지정 이벤트 사용자 지정 메트릭 종속성 예외 페이지 보기 요청 Traces
ASP.NET Core
   OpenTelemetry API 예 예 예 예
   ILogger API 예
   AI Classic API
Java
   OpenTelemetry API 예 예 예 예
   Logback, Log4j, JUL 예 예
   마이크로미터 메트릭 예
   AI Classic API 예 예 예 예 예 예 예
Node.JS
   OpenTelemetry API 예 예 예 예
Python
   OpenTelemetry API 예 예 예 예
   Python 로깅 모듈 예
   이벤트 확장 예 예

참고 항목

Application Insights Java 3.x는 Application Insights Classic API로 전송되는 원격 분석을 수신 대기합니다. 마찬가지로 Application Insights Node.js 3.x는 Application Insights Classic API를 사용하여 만든 이벤트를 수집합니다. 이를 통해 더 쉽게 업그레이드할 수 있으며 모든 사용자 지정 원격 분석 형식이 OpenTelemetry API를 통해 지원될 때까지 사용자 지정 원격 분석 지원의 중요한 격차를 해소할 수 있습니다.

사용자 지정 메트릭 추가

이 컨텍스트에서 사용자 지정 메트릭 용어는 OpenTelemetry 계측 라이브러리가 자동으로 수집하는 것 이상으로 추가 메트릭을 수집하기 위해 코드를 수동으로 계측하는 것을 의미합니다.

OpenTelemetry API는 다양한 메트릭 시나리오를 처리하기 위해 6개의 메트릭 "계측기"를 제공하며 메트릭 탐색기에서 메트릭을 시각화할 때 올바른 "집계 형식"을 선택해야 합니다. 이 요구 사항은 OpenTelemetry Metric API를 사용하여 메트릭을 전송하고 계측 라이브러리를 사용할 때 적용됩니다.

다음 표는 각 OpenTelemetry Metric Instruments에 권장되는 집계 형식을 보여 줍니다.

OpenTelemetry 계측기 Azure Monitor 집계 형식
카운터 Sum
비동기 카운터 Sum
히스토그램 최소, 최대, 평균, 합계 및 개수
비동기 계기 평균
UpDownCounter Sum
비동기식 UpDownCounter Sum

주의

일반적으로 테이블에 표시된 것 이외의 집계 형식은 의미가 없습니다.

OpenTelemetry 사양은 계측기에 대해 설명하고 각 계측기를 사용할 수 있는 경우의 예를 제공합니다.

팁

히스토그램은 가장 기능이 많으며 Application Insights GetMetric Classic API와 가장 유사합니다. Azure Monitor는 현재 히스토그램 계측기를 지원되는 5가지 집계 형식으로 평면화하며 백분위수 지원이 진행 중입니다. 비록 만능과는 거리가 있지만 다른 OpenTelemetry 계측기는 애플리케이션 성능에 미치는 영향이 적습니다.

히스토그램 예

애플리케이션 시작은 이름으로 미터를 구독해야 합니다.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

동일한 이름을 사용하여 Meter를 초기화해야 합니다.

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

카운터 예제

애플리케이션 시작은 이름으로 미터를 구독해야 합니다.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

동일한 이름을 사용하여 Meter를 초기화해야 합니다.

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

계기 예

애플리케이션 시작은 이름으로 미터를 구독해야 합니다.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

동일한 이름을 사용하여 Meter를 초기화해야 합니다.

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

사용자 지정 예외 추가

일부 계측 라이브러리는 Application Insights에 대한 예외를 자동으로 보고합니다. 그러나 계측 라이브러리가 보고하는 것 이상의 예외를 수동으로 보고해야 할 수 있습니다. 예를 들어, 코드에서 포착한 예외는 일반적으로 보고되지 않습니다. 실패 섹션 및 엔드투엔드 트랜잭션 보기를 비롯한 관련 환경에서 주의를 끌기 위해 이러한 예외를 보고할 수 있습니다.

  • 작업을 사용하여 예외를 기록하려면:

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • ILogger를 사용하여 예외를 기록하려면:

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

사용자 지정 범위 추가

두 가지 시나리오에서 사용자 지정 범위를 추가할 수 있습니다. 첫째, 계측 라이브러리에서 아직 수집되지 않은 종속성 요청이 있는 경우입니다. 둘째, 엔드투엔드 트랜잭션 뷰에서 애플리케이션 프로세스를 범위로 모델링하려는 경우입니다.

참고 항목

System.Diagnostics 네임스페이스의 Activity 및 ActivitySource 클래스는 각각 Span 및 Tracer의 OpenTelemetry 개념을 나타냅니다. TracerProvider를 사용하는 대신 생성자를 사용하여 직접 ActivitySource를 만듭니다. 각 ActivitySource 클래스는 AddSource()를 사용하여 TracerProvider에 명시적으로 연결되어야 합니다. OpenTelemetry 추적 API의 일부가 .NET 런타임에 직접 통합되기 때문입니다. 자세한 내용은 OpenTelemetry .NET 추적 API 소개를 참조하세요.

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity의 기본값은 ActivityKind.Internal이지만 다른 ActivityKind를 제공할 수 있습니다. ActivityKind.Client, ActivityKind.Producer및 ActivityKind.Internal은 Application Insights dependencies에 매핑됩니다. ActivityKind.Server 및 ActivityKind.Consumer는 Application Insights requests에 매핑됩니다.

Application Insights Classic API를 사용하여 사용자 지정 원격 분석 보내기

가능하면 OpenTelemetry API를 사용하는 것이 좋지만 Application Insights Classic API를 사용해야 하는 경우 몇 가지 시나리오가 있을 수 있습니다.

이벤트

  1. 애플리케이션에 Microsoft.ApplicationInsights을 추가합니다.

  2. TelemetryClient 인스턴스를 만듭니다.

    참고 항목

    애플리케이션당 TelemetryClient 인스턴스를 한 번만 만들어야 합니다.

    var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };
var telemetryClient = new TelemetryClient(telemetryConfiguration);

  3. 클라이언트를 사용하여 사용자 지정 원격 분석을 보냅니다.

    telemetryClient.TrackEvent("testEvent");

원격 분석 수정

이 섹션에서는 원격 분석을 수정하는 방법에 대해 설명합니다.

범위 특성 추가

이러한 특성에는 원격 분석에 사용자 지정 속성을 추가하는 것이 포함될 수 있습니다. 특성을 사용하여 클라이언트 IP와 같은 Application Insights 스키마의 선택적 필드를 설정할 수도 있습니다.

범위에 사용자 지정 속성 추가

범위에 추가하는 모든 특성은 사용자 지정 속성으로 내보내집니다. 요청, 종속성, 추적 또는 예외 테이블의 customDimensions 필드가 채워집니다.

범위 특성을 추가하려면 다음 두 가지 방법 중 하나를 사용합니다.

  • 계측 라이브러리에서 제공하는 옵션을 사용합니다.
  • 사용자 지정 범위 프로세서를 추가합니다.

팁

사용 가능한 경우 계측 라이브러리에서 제공하는 옵션을 사용하는 이점은 전체 컨텍스트를 사용할 수 있다는 것입니다. 결과적으로 사용자는 더 많은 특성을 추가하거나 필터링하도록 선택할 수 있습니다. 예를 들어 HttpClient 계측 라이브러리의 보강 옵션은 사용자에게 HttpRequestMessage 및 HttpResponseMessage 자체에 대한 액세스를 제공합니다. 여기에서 무엇이든 선택하고 특성으로 저장할 수 있습니다.

  1. 많은 계측 라이브러리가 보강 옵션을 제공합니다. 지침은 개별 계측 라이브러리의 추가 정보 파일을 참조하세요.

  2. 사용자 지정 프로세서 사용:

    팁

    Azure Monitor를 추가하기 전에 여기에 표시된 프로세서를 추가합니다.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    다음 코드를 사용하여 프로젝트에 ActivityEnrichingProcessor.cs를 추가합니다.

    public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

사용자 IP 설정

범위에서 특성을 설정하여 요청에 대한 client_IP 필드를 채울 수 있습니다. Application Insights는 IP 주소를 사용하여 사용자 위치 특성을 생성한 다음 기본적으로 삭제합니다.

사용자 지정 속성 예제를 사용하지만 다음 코드 줄을 바꿉다.ActivityEnrichingProcessor.cs

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

사용자 ID 또는 인증된 사용자 ID 설정

다음 지침을 사용하여 요청에 대한 user_Id 또는 user_AuthenticatedId 필드를 채울 수 있습니다. 사용자 ID는 익명 사용자 식별자입니다. 인증된 사용자 ID는 알려진 사용자 식별자입니다.

Important

인증된 사용자 ID를 설정하기 전에 해당 개인 정보 보호법을 참조하세요.

사용자 지정 속성 예제를 사용합니다.

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

로그 특성 추가

OpenTelemetry는 를 사용합니다. NET의 입니다 ILogger. 메시지 템플릿을 사용하여 사용자 지정 차원을 로그에 연결할 수 있습니다.

필터 원격 분석

다음 방법을 사용하여 원격 분석이 애플리케이션을 떠나기 전에 필터링할 수 있습니다.

  1. 많은 계측 라이브러리가 필터 옵션을 제공합니다. 지침은 개별 계측 라이브러리의 추가 정보 파일을 참조하세요.

  2. 사용자 지정 프로세서 사용:

    팁

    Azure Monitor를 추가하기 전에 여기에 표시된 프로세서를 추가합니다.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityFilteringProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityFilteringProcessor()));
// Configure the OpenTelemetry tracer provider to add a new source named "ActivitySourceName".
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));
// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    다음 코드를 사용하여 프로젝트에 ActivityFilteringProcessor.cs를 추가합니다.

    public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
    // The OnStart method is called when an activity is started. This is the ideal place to filter activities.
    public override void OnStart(Activity activity)
    {
        // prevents all exporters from exporting internal activities
        if (activity.Kind == ActivityKind.Internal)
        {
            activity.IsAllDataRequested = false;
        }
    }
}

  3. 특정 원본이 AddSource("ActivitySourceName")을 사용하여 명시적으로 추가되지 않은 경우 해당 원본을 사용하여 만들어진 작업은 내보내지지 않습니다.

추적 ID 또는 범위 ID를 가져옵니다.

다음 단계를 사용하여 현재 활성 상태인 Span의 Trace ID 및 Span ID를 가져올 수 있습니다.

참고 항목

System.Diagnostics 네임스페이스의 Activity 및 ActivitySource 클래스는 각각 Span 및 Tracer의 OpenTelemetry 개념을 나타냅니다. OpenTelemetry 추적 API의 일부가 .NET 런타임에 직접 통합되기 때문입니다. 자세한 내용은 OpenTelemetry .NET 추적 API 소개를 참조하세요.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

다음 단계