Mengonfigurasi OpenTelemetry Azure Monitor

Artikel
04/07/2024

Artikel ini membahas pengaturan konfigurasi untuk distro OpenTelemetry Azure Monitor.

String koneksi

String koneksi di Application Insights menentukan lokasi target untuk mengirim data telemetri, memastikannya mencapai sumber daya yang sesuai untuk pemantauan dan analisis.

Gunakan salah satu dari tiga cara berikut untuk mengonfigurasi string koneksi:

Tambahkan UseAzureMonitor() ke startup aplikasi Anda, di kelas Anda program.cs .

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

Atur variabel lingkungan.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Tambahkan bagian berikut ke file konfigurasi Anda appsettings.json .

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

Catatan

Jika Anda mengatur string koneksi di lebih dari satu tempat, kami mematuhi prioritas berikut:

Kode
Variabel lingkungan
File konfigurasi

Gunakan salah satu dari dua cara berikut untuk mengonfigurasi string koneksi:

Tambahkan Pengekspor Azure Monitor ke setiap sinyal OpenTelemetry dalam startup aplikasi.

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

Atur variabel lingkungan.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Catatan

Jika Anda mengatur string koneksi di lebih dari satu tempat, kami mematuhi prioritas berikut:

Kode
Variabel lingkungan

Gunakan salah satu dari dua cara berikut untuk mengonfigurasi string koneksi:

Atur variabel lingkungan.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Gunakan objek konfigurasi.

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

Gunakan salah satu dari dua cara berikut untuk mengonfigurasi string koneksi:

Atur variabel lingkungan.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Gunakan fungsi 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>",
)

Mengatur Nama Peran Cloud dan Instans Peran Cloud

Untuk bahasa yang didukung, Distro OpenTelemetry Azure Monitor secara otomatis mendeteksi konteks sumber daya dan menyediakan nilai default untuk Nama Peran Cloud dan properti Instans Peran Cloud komponen Anda. Namun, Anda mungkin ingin mengambil alih nilai default ke sesuatu yang masuk akal untuk tim Anda. Nilai nama peran cloud muncul di Peta Aplikasi sebagai nama di bawah simpul.

Atur Nama Peran Cloud dan Instans Peran Cloud melalui atribut Sumber Daya . Nama Peran Cloud menggunakan atribut service.namespace dan service.name walaupun akan kembali lagi ke service.name jika service.namespace tidak diatur. Instans Peran Cloud menggunakan nilai atribut service.instance.id. Untuk informasi tentang atribut standar untuk sumber daya, lihat Konvensi Semantik 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);

Atur OTEL_RESOURCE_ATTRIBUTES Atribut sumber daya menggunakan variabel lingkungan dan/atau OTEL_SERVICE_NAME . OTEL_RESOURCE_ATTRIBUTES mengambil serangkaian pasangan kunci-nilai yang dipisahkan koma. Misalnya, untuk mengatur Nama Peran Cloud ke my-namespace.my-helloworld-service dan mengatur Instans Peran Cloud ke my-instance, Anda dapat mengatur OTEL_RESOURCE_ATTRIBUTES dan OTEL_SERVICE_NAME dengan demikian:

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

Jika Anda tidak mengatur service.namespace atribut Sumber Daya, Anda dapat mengatur Nama Peran Cloud dengan hanya variabel lingkungan OTEL_SERVICE_NAME atau service.name atribut Sumber Daya. Misalnya, untuk mengatur Nama Peran Cloud ke my-helloworld-service dan mengatur Instans Peran Cloud ke my-instance, Anda dapat mengatur OTEL_RESOURCE_ATTRIBUTES dan OTEL_SERVICE_NAME dengan demikian:

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

Aktifkan Pengambilan Sampel

Anda mungkin ingin mengaktifkan pengambilan sampel untuk mengurangi volume penyerapan data Anda, yang mengurangi biaya Anda. Azure Monitor menyediakan sampler laju tetap kustom yang mengisi peristiwa dengan rasio pengambilan sampel, yang dikonversi Application Insights ke ItemCount. Sampler laju tetap memastikan pengalaman dan jumlah peristiwa yang akurat. Sampler dirancang untuk mempertahankan jejak Anda di seluruh layanan, dan dapat dioperasikan dengan SDK Application Insights yang lebih lama. Untuk informasi selengkapnya, lihat Pelajari selengkapnya tentang pengambilan sampel.

Catatan

Metrik dan Log tidak terpengaruh oleh pengambilan sampel.

Sampler mengharapkan laju sampel antara 0 dan 1 inklusif. Tingkat 0,1 berarti sekitar 10% jejak Anda dikirim.

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

Sampler mengharapkan laju sampel antara 0 dan 1 inklusif. Tingkat 0,1 berarti sekitar 10% jejak Anda dikirim.

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

Sampler mengharapkan laju sampel antara 0 dan 1 inklusif. Tingkat 0,1 berarti sekitar 10% jejak Anda dikirim.

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

Fungsi ini configure_azure_monitor() secara otomatis menggunakan ApplicationInsightsSampler untuk kompatibilitas dengan SDK Application Insights dan untuk mengambil sampel telemetri Anda. Variabel OTEL_TRACES_SAMPLER_ARG lingkungan dapat digunakan untuk menentukan laju pengambilan sampel, dengan rentang 0 hingga 1 yang valid, di mana 0 adalah 0% dan 1 adalah 100%. Misalnya, nilai 0,1 berarti 10% jejak Anda dikirim.

export OTEL_TRACES_SAMPLER_ARG=0.1

Tip

Saat menggunakan pengambilan sampel laju/persentase tetap dan Anda tidak yakin apa yang harus ditetapkan tingkat pengambilan sampel sebagai, mulai dari 5% (yaitu, rasio pengambilan sampel 0,05) dan sesuaikan laju berdasarkan akurasi operasi yang ditunjukkan pada kegagalan dan bilah performa. Tingkat yang lebih tinggi umumnya menghasilkan akurasi yang lebih tinggi. Namun, pengambilan sampel APA PUN akan memengaruhi akurasi sehingga kami menyarankan pemberitahuan tentang metrik OpenTelemetry, yang tidak terpengaruh oleh pengambilan sampel.

Mengaktifkan autentikasi MICROSOFT Entra ID (sebelumnya Azure AD)

Anda mungkin ingin mengaktifkan autentikasi Microsoft Entra untuk koneksi yang lebih aman ke Azure, yang mencegah telemetri yang tidak sah diserap ke dalam langganan Anda.

Kami mendukung kelas kredensial yang disediakan oleh Azure Identity.

Kami merekomendasikan DefaultAzureCredential untuk pengembangan lokal.
Kami merekomendasikan ManagedIdentityCredential untuk identitas terkelola yang ditetapkan sistem dan ditetapkan pengguna.
- Untuk sistem yang ditetapkan, gunakan konstruktor default tanpa parameter.
- Untuk pengguna yang ditetapkan, berikan ID klien ke konstruktor.
Kami merekomendasikan ClientSecretCredential untuk perwakilan layanan.
- Berikan ID penyewa, ID klien, dan rahasia klien ke konstruktor.

Instal paket Azure.Identity terbaru:
```
dotnet add package Azure.Identity
```

Berikan kelas kredensial yang diinginkan:

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

Kami mendukung kelas kredensial yang disediakan oleh Azure Identity.

Kami merekomendasikan DefaultAzureCredential untuk pengembangan lokal.
Kami merekomendasikan ManagedIdentityCredential untuk identitas terkelola yang ditetapkan sistem dan ditetapkan pengguna.
- Untuk sistem yang ditetapkan, gunakan konstruktor default tanpa parameter.
- Untuk pengguna yang ditetapkan, berikan ID klien ke konstruktor.
Kami merekomendasikan ClientSecretCredential untuk perwakilan layanan.
- Berikan ID penyewa, ID klien, dan rahasia klien ke konstruktor.

Instal paket Azure.Identity terbaru:
```
dotnet add package Azure.Identity
```

Berikan kelas kredensial yang diinginkan:

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

Kami mendukung kelas kredensial yang disediakan oleh Azure Identity.

// 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(),
)

Penyimpanan Offline dan Coba Lagi Otomatis

Untuk meningkatkan keandalan dan ketahanan, penawaran berbasis OpenTelemetry Azure Monitor menulis ke penyimpanan offline/lokal secara default ketika aplikasi kehilangan koneksinya dengan Application Insights. Ini menyimpan telemetri aplikasi ke disk dan secara berkala mencoba mengirimnya lagi hingga 48 jam. Dalam aplikasi beban tinggi, telemetri kadang-kadang dihilangkan karena dua alasan. Pertama, ketika waktu yang diizinkan terlampaui, dan kedua, ketika ukuran file maksimum terlampaui atau SDK tidak memiliki kesempatan untuk menghapus file. Jika kita perlu memilih, produk menyimpan peristiwa yang lebih baru daripada yang lama. Pelajari Selengkapnya

Paket Distro mencakup AzureMonitorExporter, yang secara default menggunakan salah satu lokasi berikut untuk penyimpanan offline (tercantum dalam urutan prioritas):

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

Untuk mengambil alih direktori default, Anda harus mengatur 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();

Untuk menonaktifkan fitur ini, Anda harus mengatur AzureMonitorOptions.DisableOfflineStorage = true.

Secara default, AzureMonitorExporter menggunakan salah satu lokasi berikut untuk penyimpanan offline (tercantum dalam urutan prioritas):

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

Untuk mengambil alih direktori default, Anda harus mengatur 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";
        });
    });
});

Untuk menonaktifkan fitur ini, Anda harus mengatur AzureMonitorExporterOptions.DisableOfflineStorage = true.

Secara default, AzureMonitorExporter menggunakan salah satu lokasi berikut untuk penyimpanan offline.

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

Untuk mengambil alih direktori default, Anda harus mengatur storageDirectory.

Contohnya:

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

Untuk menonaktifkan fitur ini, Anda harus mengatur disableOfflineStorage = true.

Secara default, eksportir Azure Monitor menggunakan jalur berikut:

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

Untuk mengambil alih direktori default, Anda harus mengatur storage_directory ke direktori yang Anda inginkan.

Contohnya:

...
# 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",
)
...

Untuk menonaktifkan fitur ini, Anda harus mengatur disable_offline_storage ke True. Default ke False.

Contohnya:

...
# 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,
)
...

Mengaktifkan Pengekspor OTLP

Anda mungkin ingin mengaktifkan Pengekspor Protokol OpenTelemetry (OTLP) bersama Pengekspor Azure Monitor untuk mengirim telemetri Anda ke dua lokasi.

Catatan

Pengekspor OTLP hanya ditampilkan untuk kenyamanan. Kami tidak mendukung secara resmi Pengekspor OTLP atau komponen apa pun atau pengalaman pihak ketiga di bagian hilirnya.

Instal paket OpenTelemetry.Exporter.OpenTelemetryProtocol di proyek Anda.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

Tambahkan cuplikan kode berikut ini. Contoh ini mengasumsikan bahwa Anda memiliki Pengumpul OpenTelemetry dengan penerima OTLP yang sedang berjalan. Untuk detailnya, lihat contoh pada 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();

Instal paket OpenTelemetry.Exporter.OpenTelemetryProtocol di proyek Anda.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

Tambahkan cuplikan kode berikut ini. Contoh ini mengasumsikan bahwa Anda memiliki Pengumpul OpenTelemetry dengan penerima OTLP yang sedang berjalan. Untuk detailnya, lihat contoh pada 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();

Instal OpenTelemetry Collector Trace Exporter dan paket OpenTelemetry lainnya di proyek Anda.

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

Tambahkan cuplikan kode berikut ini. Contoh ini mengasumsikan bahwa Anda memiliki Pengumpul OpenTelemetry dengan penerima OTLP yang sedang berjalan. Untuk detailnya, lihat contoh pada 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);

Instal paket opentelemetry-exporter-otlp.

Tambahkan cuplikan kode berikut ini. Contoh ini mengasumsikan bahwa Anda memiliki Pengumpul OpenTelemetry dengan penerima OTLP yang sedang berjalan. Untuk detailnya, lihat 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!")

Konfigurasi OpenTelemetry

Konfigurasi OpenTelemetry berikut dapat diakses melalui variabel lingkungan saat menggunakan Distro OpenTelemetry Azure Monitor.

Variabel lingkungan	Deskripsi
`APPLICATIONINSIGHTS_CONNECTION_STRING`	Atur ke string koneksi untuk sumber daya Application Insights Anda.
`APPLICATIONINSIGHTS_STATSBEAT_DISABLED`	Atur ke `true` untuk menolak pengumpulan metrik internal.
`OTEL_RESOURCE_ATTRIBUTES`	Pasangan kunci-nilai yang akan digunakan sebagai atribut sumber daya. Untuk informasi selengkapnya tentang atribut sumber daya, lihat spesifikasi Resource SDK.
`OTEL_SERVICE_NAME`	Mengatur nilai `service.name` atribut sumber daya. Jika `service.name` juga disediakan dalam `OTEL_RESOURCE_ATTRIBUTES`, maka `OTEL_SERVICE_NAME` diutamakan.

Variabel lingkungan	Deskripsi
`APPLICATIONINSIGHTS_CONNECTION_STRING`	Atur ke string koneksi untuk sumber daya Application Insights Anda.
`APPLICATIONINSIGHTS_STATSBEAT_DISABLED`	Atur ke `true` untuk menolak pengumpulan metrik internal.
`OTEL_RESOURCE_ATTRIBUTES`	Pasangan kunci-nilai yang akan digunakan sebagai atribut sumber daya. Untuk informasi selengkapnya tentang atribut sumber daya, lihat spesifikasi Resource SDK.
`OTEL_SERVICE_NAME`	Mengatur nilai `service.name` atribut sumber daya. Jika `service.name` juga disediakan dalam `OTEL_RESOURCE_ATTRIBUTES`, maka `OTEL_SERVICE_NAME` diutamakan.

Tanya jawab umum

Bagian ini menyediakan jawaban atas pertanyaan umum.

Apa itu OpenTelemetry?

Ini adalah standar sumber terbuka baru untuk pengamatan. Pelajari lebih lanjut di OpenTelemetry.

Mengapa Microsoft Azure Monitor berinvestasi di OpenTelemetry?

Microsoft adalah salah satu kontributor terbesar untuk OpenTelemetry.

Proposisi nilai utama dari OpenTelemetry termasuk bersifat netral terhadap vendor dan menyediakan API/SDK yang konsisten di seluruh bahasa.

Seiring waktu, kami percaya OpenTelemetry akan memungkinkan pelanggan Azure Monitor untuk mengamati aplikasi yang ditulis dalam bahasa di luar bahasa yang didukung. Ini juga memperluas jenis data yang dapat Anda kumpulkan melalui serangkaian pustaka instrumentasi yang kaya. Selain itu, SDK OpenTelemetry cenderung lebih berkinerja dalam skala besar daripada pendahulunya, SDK Application Insights.

Terakhir, OpenTelemetry juga selaras dengan strategi Microsoft untuk merangkul sumber terbuka.

Bagaimana status OpenTelemetry?

Lihat Status OpenTelemetry.

Apa itu "Distro OpenTelemetry Azure Monitor"?

Anda dapat menganggapnya sebagai pembungkus tipis yang menggabungkan semua komponen OpenTelemetry untuk pengalaman kelas satu di Azure. Pembungkus ini juga disebut distribusi di OpenTelemetry.

Mengapa saya harus menggunakan "Distro OpenTelemetry Azure Monitor"?

Ada beberapa keuntungan menggunakan Distro OpenTelemetry Azure Monitor daripada OpenTelemetry asli dari komunitas:

Mengurangi upaya pengaktifan
Didukung oleh Microsoft
Membawa fitur khusus Azure seperti:
- Pengambilan sampel yang kompatibel dengan SDK Application Insights klasik
- Autentikasi Microsoft Entra
- Penyimpanan Offline dan Coba Lagi Otomatis
- Statsbeat
- Metrik Standar Application Insights
- Mendeteksi metadata sumber daya untuk mengisi otomatis Nama Peran Cloud dan Instans Peran Cloud di berbagai lingkungan Azure
- Metrik Langsung

Dalam semangat OpenTelemetry, kami merancang distro agar terbuka dan dapat diperluas. Misalnya, Anda dapat menambahkan:

Pengekspor OpenTelemetry Protocol (OTLP) dan mengirim ke tujuan kedua secara bersamaan
Pustaka instrumentasi lain yang tidak termasuk dalam distro

Karena Distro menyediakan distribusi OpenTelemetry, Distro mendukung apa pun yang didukung oleh OpenTelemetry. Misalnya, Anda dapat menambahkan lebih banyak prosesor telemetri, pengekspor, atau pustaka instrumentasi, jika OpenTelemetry mendukungnya.

Catatan

Distro mengatur sampler ke sampler laju tetap kustom untuk Application Insights. Anda dapat mengubah ini ke sampler yang berbeda, tetapi melakukannya mungkin menonaktifkan beberapa kemampuan yang disertakan Distro. Untuk informasi selengkapnya tentang sampler yang didukung, lihat bagian Aktifkan Pengambilan Sampel di Mengonfigurasi Azure Monitor OpenTelemetry.

Untuk bahasa tanpa pengekspor OpenTelemetry mandiri yang didukung, Distro OpenTelemetry Azure Monitor adalah satu-satunya cara yang saat ini didukung untuk menggunakan OpenTelemetry dengan Azure Monitor. Untuk bahasa dengan pengekspor OpenTelemetry mandiri yang didukung, Anda memiliki opsi untuk menggunakan Distro OpenTelemetry Azure Monitor atau pengekspor OpenTelemetry mandiri yang sesuai tergantung pada skenario telemetri Anda. Untuk informasi selengkapnya, lihat Kapan saya harus menggunakan pengekspor OpenTelemetry Azure Monitor?.

Bagaimana cara menguji Distro OpenTelemetry Azure Monitor?

Lihat dokumen pengaktifan kami untuk .NET, Java, JavaScript (Node.js), dan Python.

Haruskah saya menggunakan OpenTelemetry atau Application Insights SDK?

Sebaiknya gunakan Distro OpenTelemetry kecuali Anda memerlukan fitur yang hanya tersedia dengan dukungan formal di Application Insights SDK.

Mengadopsi OpenTelemetry sekarang mencegah harus bermigrasi di kemudian hari.

Kapan saya harus menggunakan pengekspor OpenTelemetry Azure Monitor?

Untuk ASP.NET Core, Java, Node.js, dan Python, sebaiknya gunakan Distro OpenTelemetry Azure Monitor. Ini adalah satu baris kode untuk memulai.

Untuk semua skenario .NET lainnya, termasuk ASP.NET klasik, aplikasi konsol, dll., sebaiknya gunakan pengekspor OpenTelemetry .NET Azure Monitor: Azure.Monitor.OpenTelemetry.Exporter.

Untuk skenario telemetri Python yang lebih kompleks yang memerlukan konfigurasi tingkat lanjut, sebaiknya gunakan Python Azure Monitor OpenTelemetry Exporter.

Apa status rilis fitur saat ini dalam Distro OpenTelemetry Azure Monitor?

Bagan berikut memecah dukungan fitur OpenTelemetry untuk setiap bahasa.

Fitur	.NET	Node.js	Python	Java
Pelacakan terdistribusi	✅	✅	✅	✅
Metrik kustom	✅	✅	✅	✅
Metrik standar (akurasi saat ini dipengaruhi oleh pengambilan sampel)	✅	✅	✅	✅
Pengambilan sampel laju tetap	✅	✅	✅	✅
Penyimpanan offline dan percobaan ulang otomatis	✅	✅	✅	✅
Pelaporan pengecualian	✅	✅	✅	✅
Koleksi log	✅	⚠️	✅	✅
Kejadian Kustom	⚠️	⚠️	⚠️	✅
Autentikasi Microsoft Entra	✅	✅	✅	✅
Metrik langsung	❌	❌	❌	✅
Mendeteksi Konteks Sumber Daya untuk VM/VMSS dan App Service	✅	❌	✅	✅
Mendeteksi Konteks Sumber Daya untuk AKS dan Fungsi	❌	❌	❌	✅
Pemfilteran Rentang Pengujian Ketersediaan	❌	❌	❌	✅
Pengisian otomatis ID pengguna, ID pengguna yang diautentikasi, dan IP pengguna	❌	❌	❌	✅
Mengesampingkan/mengatur nama operasi, ID pengguna, atau ID pengguna yang diautentikasi secara manual	❌	❌	❌	✅
Pengambilan sampel adaptif	❌	❌	❌	✅
Profiler	❌	❌	❌	⚠️
Snapshot Debugger	❌	❌	❌	❌

Kunci

✅ Fitur ini tersedia untuk semua pelanggan dengan dukungan formal.
⚠️ Fitur ini tersedia sebagai pratinjau publik. Lihat Ketentuan penggunaan tambahan untuk pratinjau Microsoft Azure.
❌ Fitur ini tidak tersedia atau tidak berlaku.

Dapatkah OpenTelemetry digunakan untuk browser web?

Ya, tetapi kami tidak merekomendasikannya dan Azure tidak mendukungnya. OpenTelemetry JavaScript sangat dioptimalkan untuk Node.js. Sebagai gantinya, sebaiknya gunakan Application Insights JavaScript SDK.

Kapan kita dapat mengharapkan OpenTelemetry SDK tersedia untuk digunakan di browser web?

SDK web OpenTelemetry tidak memiliki garis waktu ketersediaan yang ditentukan. Kami kemungkinan beberapa tahun lagi dari SDK browser yang merupakan alternatif yang layak untuk Application Insights JavaScript SDK.

Dapatkah saya menguji OpenTelemetry di browser web hari ini?

Kotak pasir web OpenTelemetry adalah fork yang dirancang untuk membuat OpenTelemetry berfungsi di browser. Belum dimungkinkan untuk mengirim telemetri ke Application Insights. SDK tidak menentukan peristiwa klien umum.

Apakah menjalankan Application Insights bersama agen pesaing seperti AppDynamics, DataDog, dan NewRelic didukung?

Tidak. Praktik ini bukan sesuatu yang kami rencanakan untuk diuji atau didukung, meskipun Distro kami memungkinkan Anda mengekspor ke titik akhir OTLP bersama Azure Monitor secara bersamaan.

Dapatkah saya menggunakan fitur pratinjau di lingkungan produksi?

Kami tidak merekomendasikannya. Lihat Ketentuan penggunaan tambahan untuk pratinjau Microsoft Azure.

Apa perbedaan antara instrumentasi manual dan otomatis?

Lihat Gambaran Umum OpenTelemetry.

Dapatkah saya menggunakan OpenTelemetry Collector?

Beberapa pelanggan menggunakan OpenTelemetry Collector sebagai alternatif agen, meskipun Microsoft belum secara resmi mendukung pendekatan berbasis agen untuk pemantauan aplikasi. Sementara itu, komunitas sumber terbuka berkontribusi pada Pengumpul OpenTelemetry Azure Monitor Exporter yang digunakan beberapa pelanggan untuk mengirim data ke Azure Monitor Application Insights. Ini tidak didukung oleh Microsoft.

Apa perbedaan antara OpenCensus dan OpenTelemetry?

OpenCensus adalah pendahulu OpenTelemetry. Microsoft membantu menyatukan OpenTracing dan OpenCensus untuk membuat OpenTelemetry, satu standar pengamatan untuk dunia. Python SDK yang direkomendasikan produksi saat ini untuk Azure Monitor didasarkan pada OpenCensus. Microsoft berkomitmen untuk membuat Azure Monitor berdasarkan OpenTelemetry.

Pemecahan Masalah

Tidak bekerja? Lihat halaman pemecahan masalah untuk ASP.NET Core.

Dukungan

Pilih tab untuk bahasa pilihan Anda untuk menemukan opsi dukungan.

Untuk masalah dukungan Azure, buka tiket dukungan Azure.
Untuk masalah OpenTelemetry, hubungi komunitas OpenTelemetry .NET secara langsung.
Untuk daftar masalah terbuka yang terkait dengan Pengekspor Azure Monitor, lihat Halaman Masalah GitHub.

Umpan balik OpenTelemetry

Untuk memberikan umpan balik:

Isi survei umpan balik pelanggan komunitas OpenTelemetry.
Ceritakan kepada Microsoft tentang diri Anda saat bergabung dengan Komunitas Adopter Awal OpenTelemetry.
Terlibat dengan pengguna Azure Monitor lainnya di Komunitas Microsoft Tech.
Buat permintaan fitur di Forum Umpan Balik Azure.

Mengonfigurasi OpenTelemetry Azure Monitor

String koneksi

Mengatur Nama Peran Cloud dan Instans Peran Cloud

Aktifkan Pengambilan Sampel

Mengaktifkan autentikasi MICROSOFT Entra ID (sebelumnya Azure AD)

Penyimpanan Offline dan Coba Lagi Otomatis

Mengaktifkan Pengekspor OTLP

Konfigurasi OpenTelemetry

Tanya jawab umum

Apa itu OpenTelemetry?

Mengapa Microsoft Azure Monitor berinvestasi di OpenTelemetry?

Bagaimana status OpenTelemetry?

Apa itu "Distro OpenTelemetry Azure Monitor"?

Mengapa saya harus menggunakan "Distro OpenTelemetry Azure Monitor"?

Bagaimana cara menguji Distro OpenTelemetry Azure Monitor?

Haruskah saya menggunakan OpenTelemetry atau Application Insights SDK?

Kapan saya harus menggunakan pengekspor OpenTelemetry Azure Monitor?

Apa status rilis fitur saat ini dalam Distro OpenTelemetry Azure Monitor?

Dapatkah OpenTelemetry digunakan untuk browser web?

Kapan kita dapat mengharapkan OpenTelemetry SDK tersedia untuk digunakan di browser web?

Dapatkah saya menguji OpenTelemetry di browser web hari ini?

Apakah menjalankan Application Insights bersama agen pesaing seperti AppDynamics, DataDog, dan NewRelic didukung?

Dapatkah saya menggunakan fitur pratinjau di lingkungan produksi?

Apa perbedaan antara instrumentasi manual dan otomatis?

Dapatkah saya menggunakan OpenTelemetry Collector?

Apa perbedaan antara OpenCensus dan OpenTelemetry?

Pemecahan Masalah

Dukungan

Umpan balik OpenTelemetry

Sumber Daya Tambahan: