다음을 통해 공유

.NET, Java, Node.js 및 Python 애플리케이션용 Azure Monitor OpenTelemetry 추가 및 수정

이 가이드에서는 Azure Monitor Application Insights 내에서 OTel(OpenTelemetry) 계측을 통합하고 사용자 지정하는 방법에 대한 지침을 제공합니다.

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

참고 항목

Azure Function Apps의 경우 Azure Functions에서 OpenTelemetry 사용을 참조하세요.

자동 데이터 수집

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

포함된 계측 라이브러리

요청

종속성

로깅

  • ILogger

Azure Monitor로 전송되는 로그 수를 줄이거나 늘리려면 적절한 로그 수준을 설정하거나 필터를 적용하도록 로깅을 구성합니다. 예를 들어 OpenTelemetry/Azure Monitor에만 WarningError 로그를 보내도록 선택할 수 있습니다. OpenTelemetry는 로그 라우팅 또는 필터링을 제어하지 않습니다. 구성에서 ILogger 이러한 결정을 내립니다. ILogger을(를) 설정하는 방법에 대한 자세한 내용은 로깅 구성을 참조하세요.

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

각주

  • ¹: ‘처리되지 않은/잡히지 않은’ 예외의 자동 보고 지원
  • ²: OpenTelemetry 메트릭 지원

참고 항목

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();

사용자 지정 원격 분석 수집

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

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

  • 오픈텔레메트리 API
  • 언어별 로깅/메트릭 라이브러리
  • Application Insights 클래식 API

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

언어 사용자 지정 이벤트 사용자 지정 메트릭 종속성 예외 페이지 보기 요청 흔적
ASP.NET Core
   OpenTelemetry API 예 예 예 예
    ILogger API 예
   AI 클래식 API
자바
   OpenTelemetry API 예 예 예 예
   Logback, Log4j, JUL 예 예
   마이크로미터 메트릭 예
   AI 클래식 API 예 예 예 예 예 예 예
Node.js
   OpenTelemetry API 예 예 예 예
파이썬
   OpenTelemetry API 예 예 예 예
   Python 로깅 모듈 예
   이벤트 확장 예 예

참고 항목

Application Insights Java 3.x 및 Application Insights Node.js 3.x는 Application Insights 클래식 API에서 원격 분석을 수집합니다. 이 동작은 업그레이드를 간소화하고 OpenTelemetry API에 모든 사용자 지정 원격 분석 유형이 포함될 때까지 사용자 지정 원격 분석을 일시적으로 지원합니다.

사용자 지정 메트릭 추가

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

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

다음 표에서는 각 OpenTelemetry 메트릭 계측에 대해 권장되는 집계 형식 을 보여줍니다.

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

주의

대부분의 경우 다른 집계 형식은 의미가 없습니다.

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" });
}

사용자 지정 범위 추가

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

참고 항목

Activity 네임스페이스의 ActivitySource 및 System.Diagnostics 클래스는 각각 Span 및 Tracer의 OpenTelemetry 개념을 나타냅니다. ActivitySource를 사용하는 대신 생성자를 사용하여 직접 TracerProvider를 만듭니다. 각 ActivitySource 클래스는 TracerProvider를 사용하여 AddSource()에 명시적으로 연결되어야 합니다. 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는 사용자 지정 이벤트를 테이블에 저장합니다 customEvents . 이를 분석, 필터링 및 시각화하는 한 가지 방법은 Application Insights 사용 환경을 사용하는 것입니다.

클라이언트 쪽 상호 작용 이벤트의 컬렉션을 자동화하려는 경우 JavaScript SDK에서 플러그 인을 사용할 수 있습니다.

사용자 지정 이벤트는 공개 미리 보기로 제공되며 1.3.0-beta.3을 사용합니다 Azure.Monitor.OpenTelemetry.AspNetCore .

중요합니다

베타, 미리 보기 또는 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 법적 용어는 Microsoft Azure 미리 보기에 대한 추가 사용 약관 을 참조하세요.

CustomEvent을 사용하여 ILogger을 보내려면 메시지 템플릿에서 "microsoft.custom_event.name" 특성을 설정합니다.

// Create a logger factory and configure OpenTelemetry with Azure Monitor
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddOpenTelemetry(options =>
        {
            options.AddAzureMonitorLogExporter();
        });
});

// Create a logger for the specified category
var logger = loggerFactory.CreateLogger(logCategoryName);

// Log a custom event with a custom name and additional attribute
// The 'microsoft.custom_event.name' value will be used as the name of the customEvent
logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}", "test-event-name", "val1");

원격 분석 수정

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

범위 특성 추가

이러한 특성에는 원격 분석에 사용자 지정 속성을 추가하는 것이 포함될 수 있습니다. 특성을 사용하여 클라이언트 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는 알려진 사용자 식별자입니다.

중요합니다

인증된 사용자 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. 메시지 템플릿을 사용하여 로그에 사용자 지정 차원을 연결할 수 있습니다.

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

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

참고 항목

Activity 네임스페이스의 ActivitySource 및 System.Diagnostics 클래스는 각각 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();

다음 단계