다음을 통해 공유

Azure Monitor OpenTelemetry 구성

  • 아티클

이 문서에서는 Azure Monitor OpenTelemetry 배포판에 대한 구성 설정을 다룹니다.

Connection string

Application Insights의 연결 문자열은 원격 분석 데이터를 보내기 위한 대상 위치를 정의합니다.

다음 세 가지 방법 중 하나를 사용하여 연결 문자열을 구성합니다.

  • program.cs 파일에 UseAzureMonitor()를 추가합니다.

    var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    options.ConnectionString = "<Your Connection String>";
});

var app = builder.Build();

app.Run();

  • 환경 변수를 설정합니다.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • appsettings.json 구성 파일에 다음 섹션을 추가합니다.

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

참고 항목

둘 이상의 위치에서 연결 문자열을 설정하는 경우 다음 우선순위를 준수합니다.

  1. 코드
  2. 환경 변수
  3. 구성 파일

클라우드 역할 이름 및 클라우드 역할 인스턴스 설정

지원되는 언어의 경우 Azure Monitor OpenTelemetry Distro는 리소스 컨텍스트를 자동으로 검색하고 구성 요소의 클라우드 역할 이름 및 클라우드 역할 인스턴스 속성에 대한 기본값을 제공합니다. 그러나 기본값을 팀에 적합한 값으로 재정의하는 것이 좋습니다. 클라우드 역할 이름 값은 애플리케이션 맵의 노드 아래에 이름으로 표시됩니다.

리소스 특성을 통해 클라우드 역할 이름 및 클라우드 역할 인스턴스를 설정합니다. Cloud 역할 이름은 service.namespace 및 service.name 특성을 사용하지만 service.namespace가 설정되지 않은 경우 service.name으로 대체됩니다. Cloud Role Instance는 service.instance.id 특성 값을 사용합니다. 리소스의 표준 특성에 대한 자세한 내용은 OpenTelemetry 의미 규칙을 참조하세요.

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(_testResourceAttributes));

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

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

샘플링 사용

샘플링을 사용하도록 설정하고 데이터 수집 볼륨을 줄여서 비용을 절감할 수 있습니다. Azure Monitor는 Application Insights가 ItemCount로 변환하는 샘플링 비율로 이벤트를 채우는 사용자 지정 고정 속도 샘플러를 제공합니다. 고정 속도 샘플러는 정확한 환경과 이벤트 수를 보장합니다. 샘플러는 서비스 전반에서 추적을 보존하도록 설계되었으며 이전 Application Insights SDK(소프트웨어 개발 키트)와 상호 운용 가능합니다. 자세한 내용은 샘플링에 대해 자세히 알아보기를 참조하세요.

참고 항목

메트릭과 로그는 샘플링의 영향을 받지 않습니다.

샘플러는 0과 1 사이의 샘플 속도를 예상합니다. 0.1의 속도는 추적의 약 10%가 전송됨을 의미합니다.

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.SamplingRatio = 0.1F;
});

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

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

팁

고정 비율/백분율 샘플링을 사용하며 샘플링 비율을 어느 정도로 설정해야 할지 잘 모르겠다면 5%(즉, 샘플링 비율 0.05)에서 시작하고 실패 및 성능 창에 표시된 작업의 정확도에 따라 비율을 조정합니다. 일반적으로 비율이 높을수록 정확도가 높아집니다. 그러나 모든 샘플링은 정확도에 영향을 미치므로 샘플링의 영향을 받지 않는 OpenTelemetry 메트릭에 경고하는 것이 좋습니다.

라이브 메트릭

라이브 메트릭은 애플리케이션 작업 및 성능에 대한 인사이트를 제공하는 실시간 분석 대시보드를 제공합니다.

Important

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

이 기능은 기본적으로 활성화되어 있습니다.

사용자는 배포판을 구성할 때 라이브 메트릭을 사용하지 않도록 설정할 수 있습니다.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Microsoft Entra ID(이전에는 Azure AD) 인증 사용

Azure에 대한 보다 안전한 연결을 위해 Microsoft Entra 인증을 사용하도록 설정하여 권한 없는 원격 분석이 구독에 수집되지 않도록 할 수 있습니다.

Azure ID에서 제공하는 자격 증명 클래스를 지원합니다.

  • 로컬 개발에는 DefaultAzureCredential을 권장합니다.
  • 시스템 할당 및 사용자 할당 관리 ID에는 ManagedIdentityCredential을 권장합니다.
    • 시스템 할당의 경우, 매개 변수 없이 기본 생성자를 사용합니다.
    • 사용자 할당의 경우 생성자에 클라이언트 ID를 제공합니다.
  • 서비스 주체의 경우 ClientSecretCredential을 권장합니다.
    • 생성자에게 테넌트 ID, 클라이언트 ID 및 클라이언트 암호를 제공합니다.

  1. 최신 Azure.Identity 패키지를 설치합니다.

    dotnet add package Azure.Identity

  2. 원하는 자격 증명 클래스 제공:

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    // Set the Azure Monitor credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

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

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

오프라인 스토리지 및 자동 다시 시도

안정성과 복원력을 개선하기 위해 Azure Monitor OpenTelemetry 기반 제품은 애플리케이션이 Application Insights와의 연결이 끊어지면 기본적으로 오프라인/로컬 스토리지에 쓰게 됩니다. 애플리케이션 원격 분석을 디스크에 저장하고 최대 48시간 동안 주기적으로 다시 보내려고 시도합니다. 부하가 높은 애플리케이션에서는 두 가지 이유로 원격 분석이 삭제되는 경우도 있습니다. 첫째, 허용 시간을 초과한 경우, 둘째, 최대 파일 크기를 초과했거나 SDK가 파일을 지울 기회가 없는 경우. 선택해야 하는 경우, 제품은 이전 이벤트보다 최근 이벤트를 더 많이 저장합니다. 자세한 정보

배포판 패키지에는 기본적으로 오프라인 스토리지에 다음 위치 중 하나를 사용하는 AzureMonitorExporter가 포함되어 있습니다(우선순위에 따라 나열됨).

  • Windows
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • 비 Windows
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

기본 디렉터리를 재정의하려면 AzureMonitorOptions.StorageDirectory를 설정해야 합니다.

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that cannot be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

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

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

이 기능을 사용하지 않도록 설정하려면 AzureMonitorOptions.DisableOfflineStorage = true를 설정해야 합니다.

OTLP Exporter 사용

Azure Monitor Exporter와 함께 OTLP(OpenTelemetry Protocol) Exporter를 사용하여 원격 분석을 두 위치로 보낼 수 있습니다.

참고 항목

OTLP Exporter는 편의를 위해서만 표시됩니다. Microsoft는 공식적으로 OTLP Exporter 또는 그 다운스트림의 구성 요소 또는 타사 환경을 지원하지 않습니다.

  1. 프로젝트에 OpenTelemetry.Exporter.OpenTelemetryProtocol 패키지를 설치합니다.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. 다음 코드 조각을 추가합니다. 이 예에서는 OTLP 수신기가 실행 중인 OpenTelemetry Collector가 있다고 가정합니다. 자세한 내용은 GitHub의 예를 참조하세요.

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

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

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

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

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

OpenTelemetry 구성

Azure Monitor OpenTelemetry 배포판을 사용하는 동안 환경 변수를 통해 다음 OpenTelemetry 구성에 액세스할 수 있습니다.

환경 변수 설명
APPLICATIONINSIGHTS_CONNECTION_STRING Application Insights 리소스에 대한 연결 문자열로 설정합니다.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED true(으)로 설정하여 내부 메트릭 컬렉션을 옵트아웃하도록 설정하세요.
OTEL_RESOURCE_ATTRIBUTES 리소스 특성으로 사용할 키-값 쌍입니다. 리소스 특성에 대한 자세한 내용은 리소스 SDK 사양을 참조하세요.
OTEL_SERVICE_NAME service.name 리소스 특성의 값을 설정합니다. service.name도 OTEL_RESOURCE_ATTRIBUTES에 제공된 경우 OTEL_SERVICE_NAME이 우선적으로 적용됩니다.

URL 쿼리 문자열 수정

URL 쿼리 문자열을 수정하려면 쿼리 문자열 컬렉션을 해제합니다. SAS 토큰을 사용하여 Azure Storage를 호출하는 경우 이 설정을 사용하는 것이 좋습니다.

Azure.Monitor.OpenTelemetry.AspNetCore 배포판 패키지를 사용하는 경우 ASP.NET Core 및 HttpClient Instrumentation 라이브러리가 모두 포함됩니다. 배포판 패키지는 기본적으로 쿼리 문자열 편집을 해제합니다.

이 동작을 변경하려면 환경 변수를 "true" 또는 "false"로 설정해야 합니다.

  • ASP.NET 핵심 계측: OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION 쿼리 문자열 편집은 기본적으로 사용하지 않도록 설정됩니다. 사용하도록 설정하려면 이 환경 변수를 "false"로 설정합니다.
  • Http 클라이언트 계측: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION 쿼리 문자열 편집은 기본적으로 사용하지 않도록 설정됩니다. 사용하도록 설정하려면 이 환경 변수를 "false"로 설정합니다.