Azure Monitor OpenTelemetry 구성

아티클
04/13/2024

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

Connection string

Application Insights의 연결 문자열은 원격 분석 데이터를 전송하기 위한 대상 위치를 정의하여 모니터링 및 분석에 적합한 리소스에 도달하도록 합니다.

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

program.cs 클래스에서 애플리케이션 시작에 UseAzureMonitor()을(를) 추가합니다.

// 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 => {
    options.ConnectionString = "<Your Connection String>";
});

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

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

환경 변수를 설정합니다.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

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

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

참고 항목

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

코드
환경 변수
구성 파일

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

애플리케이션 시작 시 각 OpenTelemetry 신호에 Azure Monitor 내보내기를 추가합니다.

// Create a new OpenTelemetry tracer provider.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddAzureMonitorTraceExporter(options =>
{
    options.ConnectionString = "<Your Connection String>";
});

// Create a new OpenTelemetry meter provider.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        options.ConnectionString = "<Your Connection String>";
    });

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(options =>
        {
            options.ConnectionString = "<Your Connection String>";
        });
    });
});

환경 변수를 설정합니다.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

참고 항목

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

코드
환경 변수

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

환경 변수를 설정합니다.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

구성 개체를 사용합니다.

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object.
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: "<your connection string>"
  }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

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

환경 변수를 설정합니다.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

configure_azure_monitor 함수를 사용합니다.

# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with the specified connection string.
# Replace `<your-connection-string>` with the connection string of your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<your-connection-string>",
)

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

지원되는 언어의 경우 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 OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.ConfigureResource(resourceBuilder => 
        resourceBuilder.AddAttributes(resourceAttributes)));

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

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

// 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 resource builder.
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

// Create a new OpenTelemetry tracer provider and set the resource builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // Set ResourceBuilder on the TracerProvider.
    .SetResourceBuilder(resourceBuilder)
    .AddAzureMonitorTraceExporter();

// Create a new OpenTelemetry meter provider and set the resource builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    // Set ResourceBuilder on the MeterProvider.
    .SetResourceBuilder(resourceBuilder)
    .AddAzureMonitorMetricExporter();

// Create a new logger factory and add the OpenTelemetry logger provider with the resource builder.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        // Set ResourceBuilder on the Logging config.
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter();
    });
});

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, the Resource class, and the SemanticResourceAttributes class from the @azure/monitor-opentelemetry, @opentelemetry/resources, and @opentelemetry/semantic-conventions packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { Resource } = require("@opentelemetry/resources");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");

// Create a new Resource object with the following custom resource attributes:
//
// * service_name: my-service
// * service_namespace: my-namespace
// * service_instance_id: my-instance
const customResource = new Resource({
  [SemanticResourceAttributes.SERVICE_NAME]: "my-service",
  [SemanticResourceAttributes.SERVICE_NAMESPACE]: "my-namespace",
  [SemanticResourceAttributes.SERVICE_INSTANCE_ID]: "my-instance",
});

// Create a new AzureMonitorOpenTelemetryOptions object and set the resource property to the customResource object.
const options: AzureMonitorOpenTelemetryOptions = {
  resource: customResource
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

OTEL_RESOURCE_ATTRIBUTES 및/또는 OTEL_SERVICE_NAME 환경 변수를 사용하여 리소스 특성을 설정합니다. OTEL_RESOURCE_ATTRIBUTES는 쉼표로 구분된 일련의 키-값 쌍을 사용합니다. 예를 들어 클라우드 역할 이름을 my-namespace.my-helloworld-service로 설정하고 클라우드 역할 인스턴스를 my-instance로 설정하려면 다음과 같이 OTEL_RESOURCE_ATTRIBUTES 및 OTEL_SERVICE_NAME을 설정할 수 있습니다.

export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace,service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

service.namespace 리소스 특성을 설정하지 않으면 OTEL_SERVICE_NAME 환경 변수 또는 service.name 리소스 특성만 사용하여 클라우드 역할 이름을 설정할 수 있습니다. 예를 들어 클라우드 역할 이름을 my-helloworld-service로 설정하고 클라우드 역할 인스턴스를 my-instance로 설정하려면 다음과 같이 OTEL_RESOURCE_ATTRIBUTES 및 OTEL_SERVICE_NAME을 설정할 수 있습니다.

export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

샘플링 사용

샘플링을 사용하도록 설정하고 데이터 수집 볼륨을 줄여서 비용을 절감할 수 있습니다. 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(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

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

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

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

// Create a new OpenTelemetry tracer provider.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(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;
    });

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

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object and set the samplingRatio property to 0.1.
const options: AzureMonitorOpenTelemetryOptions = {
  samplingRatio: 0.1
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

configure_azure_monitor() 함수는 Application Insights SDK와의 호환성을 위해 ApplicationInsightsSampler를 자동으로 활용하고 원격 분석을 샘플링합니다. OTEL_TRACES_SAMPLER_ARG 환경 변수를 사용하여 0에서 1까지의 유효한 범위로 샘플링 속도를 지정할 수 있습니다. 여기서 0은 0%이고 1은 100%입니다. 예를 들어 값이 0.1이면 추적의 10%가 전송됩니다.

export OTEL_TRACES_SAMPLER_ARG=0.1

팁

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

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

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

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

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

최신 Azure.Identity 패키지를 설치합니다.
```
dotnet add package Azure.Identity
```

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

// 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 ID에서 제공하는 자격 증명 클래스를 지원합니다.

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

최신 Azure.Identity 패키지를 설치합니다.
```
dotnet add package Azure.Identity
```

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

// Create a DefaultAzureCredential.
var credential = new DefaultAzureCredential();

// Create a new OpenTelemetry tracer provider and set the credential.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options =>
    {
        options.Credential = credential;
    });

// Create a new OpenTelemetry meter provider and set the credential.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        options.Credential = credential;
    });

// Create a new logger factory and add the OpenTelemetry logger provider with the credential.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(options =>
        {
            options.Credential = credential;
        });
    });
});

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

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, and the ManagedIdentityCredential class from the @azure/monitor-opentelemetry and @azure/identity packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { ManagedIdentityCredential } = require("@azure/identity");

// Create a new ManagedIdentityCredential object.
const credential = new ManagedIdentityCredential();

// Create a new AzureMonitorOpenTelemetryOptions object and set the credential property to the credential object.
const options: AzureMonitorOpenTelemetryOptions = {
    azureMonitorExporterOptions: {
        credential: credential
    }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

# Import the `ManagedIdentityCredential` class from the `azure.identity` package.
from azure.identity import ManagedIdentityCredential
# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with a managed identity credential.
# This will allow OpenTelemetry to authenticate to Azure Monitor without requiring you to provide a connection string.
configure_azure_monitor(
    credential=ManagedIdentityCredential(),
)

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

안정성과 복원력을 개선하기 위해 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를 설정해야 합니다.

기본적으로 AzureMonitorExporter는 오프라인 스토리지에 대해 다음 위치 중 하나를 사용합니다(우선 순위에 따라 나열됨).

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

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

// Create a new OpenTelemetry tracer provider and set the storage directory.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options =>
    {
        // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
        // This is the directory where the OpenTelemetry SDK will store any trace data that cannot be sent to Azure Monitor immediately.
        options.StorageDirectory = "C:\\SomeDirectory";
    });

// Create a new OpenTelemetry meter provider and set the storage directory.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
        // This is the directory where the OpenTelemetry SDK will store any metric data that cannot be sent to Azure Monitor immediately.
        options.StorageDirectory = "C:\\SomeDirectory";
    });

// Create a new logger factory and add the OpenTelemetry logger provider with the storage directory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(options =>
        {
            // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
            // This is the directory where the OpenTelemetry SDK will store any log data that cannot be sent to Azure Monitor immediately.
            options.StorageDirectory = "C:\\SomeDirectory";
        });
    });
});

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

기본적으로 AzureMonitorExporter는 오프라인 스토리지에 대해 다음 위치 중 하나를 사용합니다.

Windows
- %TEMP%\Microsoft\AzureMonitor
비 Windows
- %TMPDIR%/Microsoft/AzureMonitor
- /var/tmp/Microsoft/AzureMonitor

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

예시:

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object and set the azureMonitorExporterOptions property to an object with the following properties:
//
// * connectionString: The connection string for your Azure Monitor Application Insights resource.
// * storageDirectory: The directory where the Azure Monitor OpenTelemetry exporter will store telemetry data when it is offline.
// * disableOfflineStorage: A boolean value that specifies whether to disable offline storage.
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: "<Your Connection String>",
    storageDirectory: "C:\\SomeDirectory",
    disableOfflineStorage: false
  }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

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

기본적으로 Azure Monitor 내보내기는 다음 경로를 사용합니다.

<tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>

기본 디렉터리를 재정의하려면 storage_directory를 원하는 디렉터리로 설정해야 합니다.

예시:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and storage directory.
# Replace `your-connection-string` with the connection string to your Azure Monitor Application Insights resource.
# Replace `C:\\SomeDirectory` with the directory where you want to store the telemetry data before it is sent to Azure Monitor.
configure_azure_monitor(
    connection_string="your-connection-string",
    storage_directory="C:\\SomeDirectory",
)
...

이 기능을 사용하지 않도록 설정하려면 disable_offline_storage를 True로 설정해야 합니다. 기본값은 False입니다.

예시:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and disable offline storage.
# Replace `your-connection-string` with the connection string to your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="your-connection-string",
    disable_offline_storage=True,
)
...

OTLP Exporter 사용

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

참고 항목

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

프로젝트에 OpenTelemetry.Exporter.OpenTelemetryProtocol 패키지를 설치합니다.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

다음 코드 조각을 추가합니다. 이 예에서는 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.Exporter.OpenTelemetryProtocol 패키지를 설치합니다.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

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

// Create a new OpenTelemetry tracer provider and add the Azure Monitor trace exporter and the OTLP trace exporter.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter()
    .AddOtlpExporter();

// Create a new OpenTelemetry meter provider and add the Azure Monitor metric exporter and the OTLP metric exporter.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter()
    .AddOtlpExporter();

프로젝트에 OpenTelemetry 수집기 추적 내보내기 및 기타 OpenTelemetry 패키지를 설치합니다.

    npm install @opentelemetry/api
    npm install @opentelemetry/exporter-trace-otlp-http
    npm install @opentelemetry/sdk-trace-base
    npm install @opentelemetry/sdk-trace-node

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

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, the trace module, the ProxyTracerProvider class, the BatchSpanProcessor class, the NodeTracerProvider class, and the OTLPTraceExporter class from the @azure/monitor-opentelemetry, @opentelemetry/api, @opentelemetry/sdk-trace-base, @opentelemetry/sdk-trace-node, and @opentelemetry/exporter-trace-otlp-http packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

// Create a new OTLPTraceExporter object.
const otlpExporter = new OTLPTraceExporter();

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
    // Add the SpanEnrichingProcessor
    spanProcessors: [new BatchSpanProcessor(otlpExporter)] 
}
useAzureMonitor(options);

opentelemetry-exporter-otlp 패키지를 설치합니다.

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

# Import the `configure_azure_monitor()`, `trace`, `OTLPSpanExporter`, and `BatchSpanProcessor` classes from the appropriate packages.    
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure OpenTelemetry to use Azure Monitor with the specified connection string.
# Replace `<your-connection-string>` with the connection string to your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<your-connection-string>",
)

# Get the tracer for the current module.
tracer = trace.get_tracer(__name__) 

# Create an OTLP span exporter that sends spans to the specified endpoint.
# Replace `http://localhost:4317` with the endpoint of your OTLP collector.
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")

# Create a batch span processor that uses the OTLP span exporter.
span_processor = BatchSpanProcessor(otlp_exporter)

# Add the batch span processor to the tracer provider.
trace.get_tracer_provider().add_span_processor(span_processor)

# Start a new span with the name "test".
with tracer.start_as_current_span("test"):
    print("Hello world!")

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`이 우선적으로 적용됩니다.

환경 변수	설명
`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`이 우선적으로 적용됩니다.

자주 묻는 질문

이 섹션에서는 일반적인 질문에 대한 답변을 제공합니다.

OpenTelemetry란?

가시성에 대한 새로운 오픈 소스 표준입니다. OpenTelemetry에서 자세히 알아보세요.

Microsoft Azure Monitor에서 OpenTelemetry에 투자하는 이유는 무엇인가요?

Microsoft는 OpenTelemetry에 가장 많이 기여하는 회사 중 하나입니다.

OpenTelemetry의 핵심 가치 제안은 공급업체의 제약을 받지 않으며 모든 언어에서 일관적인 API/SDK를 제공한다는 것입니다.

시간이 지나면서 OpenTelemetry를 통해 Azure Monitor 고객은 지원되는 언어 이외의 언어로 작성된 애플리케이션을 관찰할 수 있게 될 것입니다. 또한 다양한 계측 라이브러리 집합을 통해 수집할 수 있는 데이터 형식을 확장합니다. 또한 OpenTelemetry SDK는 이전 버전인 Application Insights SDK보다 대규모 성능이 더 뛰어난 경향이 있습니다.

마지막으로, OpenTelemetry는 오픈 소스를 수용하는 Microsoft의 전략에 부합합니다.

OpenTelemetry는 현재 어떤 상태인가요?

OpenTelemetry 상태를 참조하세요.

"Azure Monitor OpenTelemetry Distro"란?

이는 Azure에서 최고 수준의 환경을 제공하기 위해 모든 OpenTelemetry 구성 요소를 함께 묶는 얇은 래퍼라고 생각할 수 있습니다. 이 래퍼를 OpenTelemetry의 배포라고도합니다.

"Azure Monitor OpenTelemetry Distro"를 사용해야 하는 이유는 무엇인가요?

커뮤니티의 네이티브 OpenTelemetry에 비해 Azure Monitor OpenTelemetry Distro를 사용하면 다음과 같은 몇 가지 이점이 있습니다.

사용 설정 작업 감소
Microsoft에서 지원
다음과 같은 Azure 관련 기능을 제공합니다.
- 클래식 Application Insights SDK와 호환되는 샘플링
- Microsoft Entra 인증
- 오프라인 스토리지 및 자동 다시 시도
- Statsbeat
- Azure Application Insights 표준 메트릭
- 리소스 메타데이터를 검색하여 다양한 Azure 환경에서 클라우드 역할 이름과 클라우드 역할 인스턴스를 자동으로 채웁니다.
- 라이브 메트릭

OpenTelemetry의 설계 방향에 따라 개방적이고 확장 가능하도록 Distro를 설계했습니다. 예를 들어, 다음을 추가할 수 있습니다.

OTLP(OpenTelemetry Protocol) 내보내기 도구 및 두 번째 대상으로 동시에 보내기
Distro에 포함되지 않은 기타 계측 라이브러리

Distro는 OpenTelemetry 배포를 제공하므로 Distro는 OpenTelemetry에서 지원하는 모든 항목을 지원합니다. 예를 들어 OpenTelemetry가 지원하는 경우 원격 분석 프로세서, 내보내기 도구 또는 계측 라이브러리를 더 추가할 수 있습니다.

참고 항목

Distro는 Application Insights에 대한 사용자 지정 고정 속도 샘플러로 샘플러를 설정합니다. 이를 다른 샘플러로 변경할 수 있지만 이렇게 하면 Distro의 포함된 기능 중 일부를 사용하지 않도록 설정할 수 있습니다. 지원되는 샘플러에 관한 자세한 내용은 Azure Monitor OpenTelemetry 구성의 샘플링 사용 섹션을 참조하세요.

지원되는 독립 실행형 OpenTelemetry 내보내기 도구가 없는 언어의 경우 Azure Monitor OpenTelemetry Distro는 현재 Azure Monitor에서 OpenTelemetry를 사용할 수 있는 유일한 방법입니다. 지원되는 독립 실행형 OpenTelemetry 내보내기 도구가 있는 언어의 경우 원격 분석 시나리오에 따라 Azure Monitor OpenTelemetry Distro 또는 적절한 독립 실행형 OpenTelemetry 내보내기 도구를 사용할 수 있습니다. 자세한 내용은 언제 Azure Monitor OpenTelemetry 내보내기 도구를 사용해야 하나요?를 참조하세요.

Azure Monitor OpenTelemetry Distro를 테스트하려면 어떻게 해야 하나요?

.NET, Java, JavaScript(Node.js) 및 Python에 대한 사용 설정 문서를 확인하세요.

OpenTelemetry 또는 Application Insights SDK를 사용해야 하나요?

Application Insights SDK의 공식적인 지원으로만 사용할 수 있는 기능이 필요한 경우 외에는 OpenTelemetry Distro를 사용하는 것이 좋습니다.

지금 OpenTelemetry를 채택하면 나중에 마이그레이션할 필요가 없습니다.

Azure Monitor OpenTelemetry 내보내기 도구를 사용해야 하는 이유는 무엇인가요?

ASP.NET Core, Java, Node.js 및 Python의 경우 Azure Monitor OpenTelemetry Distro를 사용하는 것이 좋습니다. 시작하는 한 줄의 코드입니다.

클래식 ASP.NET, 콘솔 앱 등을 비롯한 다른 모든 .NET 시나리오의 경우 .NET Azure Monitor OpenTelemetry 내보내기 도구(Azure.Monitor.OpenTelemetry.Exporter)를 사용하는 것이 좋습니다.

고급 구성이 필요한 더 복잡한 Python 원격 분석 시나리오의 경우 Python Azure Monitor OpenTelemetry Exporter를 사용하는 것이 좋습니다.

Azure Monitor OpenTelemetry Distro 내 기능의 현재 릴리스 상태는 무엇인가요?

다음 차트는 각 언어에 대한 OpenTelemetry 기능 지원을 분석한 것입니다.

기능	.NET	Node.JS	Python	Java
분산 추적	✅	✅	✅	✅
사용자 지정 메트릭	✅	✅	✅	✅
표준 메트릭(현재 정확도가 샘플링의 영향을 받음)	✅	✅	✅	✅
고정 비율 샘플링	✅	✅	✅	✅
오프라인 스토리지 및 자동 다시 시도	✅	✅	✅	✅
예외 보고	✅	✅	✅	✅
로그 컬렉션	✅	⚠️	✅	✅
사용자 지정 이벤트	⚠️	⚠️	⚠️	✅
Microsoft Entra 인증	✅	✅	✅	✅
라이브 메트릭	❌	❌	❌	✅
VM/VMSS 및 App Service에 대한 리소스 컨텍스트 검색	✅	❌	✅	✅
AKS 및 함수에 대한 리소스 컨텍스트 검색	❌	❌	❌	✅
가용성 테스트 범위 필터링	❌	❌	❌	✅
사용자 ID, 인증된 사용자 ID 및 사용자 IP 자동 채우기	❌	❌	❌	✅
수동으로 작업 이름, 사용자 ID 또는 인증된 사용자 ID 재정의/설정	❌	❌	❌	✅
적응 샘플링	❌	❌	❌	✅
프로파일러	❌	❌	❌	⚠️
스냅샷 디버거	❌	❌	❌	❌

Key

✅ 이 기능은 공식적인 지원을 통해 모든 고객이 사용할 수 있습니다.
⚠ 이 기능은 퍼블릭 미리 보기 상태로 지원됩니다. Microsoft Azure 미리 보기에 대한 보충 사용 약관을 참조하세요.
❌ 이 기능은 사용할 수 없거나 적용할 수 없습니다.

웹 브라우저에 OpenTelemetry를 사용할 수 있나요?

예, 하지만 권장하지 않으며 Azure에서 지원하지 않습니다. OpenTelemetry JavaScript는 Node.js에 맞게 과도하게 최적화되어 있습니다. 대신 Application Insights JavaScript SDK를 사용하는 것이 좋습니다.

언제쯤이면 웹 브라우저에서 OpenTelemetry SDK를 사용할 수 있게 될까요?

OpenTelemetry 웹 SDK에는 결정된 가용성 타임라인이 없습니다. Application Insights JavaScript SDK에 대한 실행 가능한 대안인 브라우저 SDK가 제공되려면 몇 년이 걸릴 수 있습니다.

현재, 웹 브라우저에서 OpenTelemetry를 테스트할 수 있나요?

OpenTelemetry 웹 샌드박스는 OpenTelemetry가 브라우저에서 작동하도록 디자인된 포크입니다. 아직 Application Insights에 원격 분석을 보낼 수 없습니다. SDK는 일반 클라이언트 이벤트를 정의하지 않습니다.

AppDynamics, DataDog 및 NewRelic과 같은 경쟁 에이전트와 함께 Application Insights를 실행하고 있나요?

아니요. Distro를 사용하면 Azure Monitor와 동시에 OTLP 엔드포인트로 내보낼 수 있지만 이 방식은 테스트하거나 지원할 계획이 없습니다.

프로덕션 환경에서 미리 보기 기능을 사용할 수 있나요?

이는 권장되지 않습니다. Microsoft Azure 미리 보기에 대한 보충 사용 약관을 참조하세요.

수동 계측과 자동 계측의 차이점은 무엇인가요?

OpenTelemetry 개요를 참조하세요.

OpenTelemetry 수집기를 사용할 수 있나요?

Microsoft에서 아직 애플리케이션 모니터링에 대한 에이전트 기반 접근 방법을 공식적으로 지원하지 않지만, 일부 고객은 OpenTelemetry 수집기를 에이전트 대안으로 사용합니다. 그동안 오픈 소스 커뮤니티에서는 일부 고객이 Azure Monitor Application Insights에 데이터를 보내는 데 사용하는 OpenTelemetry 수집기 Azure Monitor 내보내기 도구에 기여했습니다. Microsoft에서는 지원되지 않습니다.

OpenCensus와 OpenTelemetry의 차이점은 무엇인가요?

OpenCensus는 OpenTelemetry의 이전 버전입니다. Microsoft에서는 OpenTracing과 OpenCensus를 통합하여 전 세계 단일 가시성 표준으로 OpenTelemetry를 만듭니다. Azure Monitor의 현재 프로덕션 권장 Python SDK는 OpenCensus를 기준으로 합니다. Microsoft는 OpenTelemetry를 기반으로 Azure Monitor를 만들기 위해 최선을 다하고 있습니다.

문제 해결

작동하지 않나요? ASP.NET Core에 대한 문제 해결 페이지를 확인합니다.

지원

지원 옵션을 찾으려면 원하는 언어 탭을 선택합니다.

Azure 지원 문제의 경우 Azure 지원 티켓을 엽니다.
OpenTelemetry 문제의 경우 OpenTelemetry .NET 커뮤니티에 직접 문의합니다.
Azure Monitor Exporter와 관련된 미해결 문제 목록은 GitHub 문제 페이지를 참조하세요.

OpenTelemetry 피드백

피드백을 제공하려면:

OpenTelemetry 커뮤니티의 고객 피드백 설문 조사를 작성합니다.
OpenTelemetry Early Adopter Community에 조인하여 Microsoft에 자기 소개를 합니다.
Microsoft Tech Community에서 다른 Azure Monitor 사용자와 소통합니다.
Azure 피드백 포럼에서 기능 요청을 보냅니다.

Azure Monitor OpenTelemetry 구성

Connection string

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

샘플링 사용

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

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

OTLP Exporter 사용

OpenTelemetry 구성

자주 묻는 질문

OpenTelemetry란?

Microsoft Azure Monitor에서 OpenTelemetry에 투자하는 이유는 무엇인가요?

OpenTelemetry는 현재 어떤 상태인가요?

"Azure Monitor OpenTelemetry Distro"란?

"Azure Monitor OpenTelemetry Distro"를 사용해야 하는 이유는 무엇인가요?

Azure Monitor OpenTelemetry Distro를 테스트하려면 어떻게 해야 하나요?

OpenTelemetry 또는 Application Insights SDK를 사용해야 하나요?

Azure Monitor OpenTelemetry 내보내기 도구를 사용해야 하는 이유는 무엇인가요?

Azure Monitor OpenTelemetry Distro 내 기능의 현재 릴리스 상태는 무엇인가요?

웹 브라우저에 OpenTelemetry를 사용할 수 있나요?

언제쯤이면 웹 브라우저에서 OpenTelemetry SDK를 사용할 수 있게 될까요?

현재, 웹 브라우저에서 OpenTelemetry를 테스트할 수 있나요?

AppDynamics, DataDog 및 NewRelic과 같은 경쟁 에이전트와 함께 Application Insights를 실행하고 있나요?

프로덕션 환경에서 미리 보기 기능을 사용할 수 있나요?

수동 계측과 자동 계측의 차이점은 무엇인가요?

OpenTelemetry 수집기를 사용할 수 있나요?

OpenCensus와 OpenTelemetry의 차이점은 무엇인가요?

문제 해결

지원

OpenTelemetry 피드백

추가 리소스