Condividi tramite

Configurare OpenTelemetry di Monitoraggio di Azure

  • Articolo

Questa guida illustra come configurare OpenTelemetry (OTel) nel Monitoraggio di Azure Application Insights usando la distribuzione di OpenTelemetry di Monitoraggio di Azure. La configurazione corretta garantisce una raccolta coerente dei dati di telemetria tra applicazioni .NET, Java, Node.jse Python, consentendo un monitoraggio e una diagnostica più affidabili.

Nota

Per le app per le funzioni di Azure, vedere Usare OpenTelemetry con Funzioni di Azure.

Stringa di connessione

Una stringa di connessione in Application Insights definisce la posizione di destinazione per l'invio dei dati di telemetria.

Adottare uno dei tre modi seguenti per configurare la stringa di connessione:

  • Aggiungere UseAzureMonitor() al file program.cs:

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

  • Impostare una variabile di ambiente.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • Aggiungere la sezione seguente al file di configurazione appsettings.json.

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

Nota

Se si imposta la stringa di connessione in più posizioni, viene osservato l'ordine di precedenza seguente:

  1. Codice
  2. Variabile di ambiente
  3. File di configurazione

Impostare il nome e l'istanza del ruolo cloud

Per le lingue supportate, la distribuzione OpenTelemetry di Monitoraggio di Azure rileva automaticamente il contesto delle risorse e fornisce i valori predefiniti per le proprietà Nome ruolo cloud e Istanza del ruolo cloud del componente. È tuttavia possibile sostituire i valori predefiniti con altri più pertinenti per il proprio team. Nella mappa delle applicazioni, il valore del nome del ruolo cloud corrisponde al nome visualizzato sotto un nodo.

Imposta il Cloud Role Name e il Cloud Role Instance tramite gli attributi Resource. Il nome del ruolo cloud usa gli attributi service.namespace e service.name ma, se service.name non è impostato, esegue il fallback a service.namespace. L'istanza del ruolo cloud usa il valore di attributo service.instance.id. Per informazioni sugli attributi standard per le risorse, vedere Convenzioni semantiche 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();

Abilitare il campionamento

Per ridurre il volume di inserimento dati, limitando quindi i costi, è possibile abilitare il campionamento. Azure Monitor fornisce un campionatore personalizzato a frequenza fissa che assegna un rapporto di campionamento agli eventi, che Application Insights converte in ItemCount. Il campionatore a frequenza fissa garantisce esperienze accurate e conteggi di eventi. Il campionatore è progettato per mantenere le tracce sui servizi ed è interoperabile con i precedenti SDK (Software Development Kit) di Application Insights. Per altre informazioni, vedere Altre informazioni sul campionamento.

Nota

Le metriche e i log sono esclusi dal campionamento. Se vengono visualizzati addebiti imprevisti o costi elevati in Application Insights, questa guida può essere utile. Vengono illustrate le cause comuni, ad esempio volumi di telemetria elevati, picchi di inserimento dati e campionamento non configurato correttamente. È particolarmente utile se si stanno risolvendo problemi relativi a picchi di costo, volume di telemetria, campionamento non funzionante, limiti di dati, inserimento elevato o fatturazione imprevista. Per iniziare, vedere Risolvere i problemi relativi all'inserimento dati elevato in Application Insights.

Il campionatore prevede una frequenza di campionamento compresa tra 0 e 1 (inclusi). Un tasso pari a 0,1 indica che viene inviato circa il 10% delle tracce.

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

Suggerimento

Quando si usa il campionamento a velocità fissa/percentuale e non si è certi di cosa impostare la frequenza di campionamento, iniziare al 5%. (rapporto di campionamento 0,05) Modificare la frequenza in base all'accuratezza delle operazioni visualizzate nei riquadri errori e prestazioni. Una frequenza più elevata comporta in genere un'accuratezza maggiore. Tuttavia, il campionamento ANY influisce sull'accuratezza, pertanto è consigliabile inviare avvisi sulle metriche OpenTelemetry, che non sono interessate dal campionamento.

Metriche attive

Le metriche in tempo reale forniscono un dashboard di analisi in tempo reale per informazioni dettagliate sulle attività e sulle prestazioni dell'applicazione.

Importante

Vedere le Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per le condizioni legali applicabili alle funzionalità di Azure in versione beta, in anteprima o non ancora rilasciate nella disponibilità generale.

Questa funzionalità è abilitata per impostazione predefinita.

Gli utenti possono disabilitare le metriche in tempo reale durante la configurazione della distribuzione.

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

Abilitare l'autenticazione di Microsoft Entra ID (in precedenza Azure AD)

Per una connessione più sicura ad Azure è possibile abilitare l'autenticazione di Microsoft Entra, che impedisce l'inserimento di dati di telemetria non autorizzati nella sottoscrizione.

Per altre informazioni, vedere la pagina dedicata relativa all'autenticazione di Microsoft Entra collegata per ogni lingua supportata.

Per informazioni sulla configurazione dell'autenticazione di Entra ID, vedere Autenticazione di Microsoft Entra per Application Insights

Archiviazione offline e retry automatici

Le offerte basate su OpenTelemetry di Monitor di Azure memorizzano nella cache i dati di telemetria per un massimo di 48 ore, quando un'applicazione si disconnette da Application Insights e ritenta l'invio. Per le raccomandazioni sulla gestione dei dati, vedere Esportare ed eliminare dati privati. Le applicazioni ad alto carico rilasciano occasionalmente i dati di telemetria per due motivi: il superamento del tempo consentito o il superamento delle dimensioni massime del file. Quando necessario, il prodotto assegna priorità agli eventi recenti rispetto a quelli precedenti.

Il pacchetto di distribuzione include AzureMonitorExporter, che per impostazione predefinita usa uno dei percorsi seguenti per la risorsa di archiviazione offline (elencati in ordine di precedenza):

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

Per eseguire l'override della directory predefinita, impostare 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();

Per disabilitare questa funzionalità, impostare AzureMonitorOptions.DisableOfflineStorage = true.

Abilitare l'utilità di esportazione di OTLP

Per salvare i dati di telemetria su due percorsi diversi, è possibile abilitare l'utilità di esportazione OTLP (OpenTelemetry Protocol) contestualmente all'utilità di esportazione di Monitoraggio di Azure.

Nota

L'utilità di esportazione OTLP viene mostrata qui solo per praticità. Non viene infatti fornito il supporto ufficiale dell'utilità di esportazione OTLP, né di alcun componente o esperienza di terze parti a valle.

  1. Installare il pacchetto OpenTelemetry.Exporter.OpenTelemetryProtocol nel progetto.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. Aggiungere il frammento di codice seguente. In questo esempio si presuppone che sia presente un agente di raccolta OpenTelemetry con un ricevitore OTLP in esecuzione. Per informazioni dettagliate, vedere l'esempio in 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();

Configurazioni di OpenTelemetry

Per accedere alle configurazioni di OpenTelemetry seguenti, è necessario applicare specifiche variabili di ambiente durante l'uso delle distribuzioni OpenTelemetry di Monitoraggio di Azure.

Variabile di ambiente Descrizione
APPLICATIONINSIGHTS_CONNECTION_STRING Impostarla sulla stringa di connessione per la risorsa di Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Impostarla su true per rifiutare esplicitamente la raccolta di metriche interne.
OTEL_RESOURCE_ATTRIBUTES Coppie chiave-valore da usare come attributi di risorsa. Per altre informazioni sugli attributi delle risorse, vedere la specifica di Resource SDK.
OTEL_SERVICE_NAME Impostare il valore dell'attributo di risorsa service.name. Se service.name viene specificato anche in OTEL_RESOURCE_ATTRIBUTES, viene assegnata la precedenza a OTEL_SERVICE_NAME.

Redigere stringhe di query URL

Per ridistribuire le stringhe di query URL, disattivare la raccolta di stringhe di query. È consigliabile usare questa impostazione se si chiama Archiviazione di Azure usando un token di firma di accesso condiviso.

Quando si usa il pacchetto di distribuzione Azure.Monitor.OpenTelemetry.AspNetCore , sono incluse entrambe le librerie di strumentazione Core e HttpClient ASP.NET. Il pacchetto di distribuzione imposta la ridistribuzione della stringa di query disattivata per impostazione predefinita.

Per modificare questo comportamento, è necessario impostare una variabile di ambiente su true o false.

  • ASP.NET Strumentazione principale: OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION la ridistribuzione della stringa di query è disabilitata per impostazione predefinita. Per abilitare, impostare questa variabile di ambiente su false.
  • Strumentazione client HTTP: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION la ridistribuzione della stringa di query è disabilitata per impostazione predefinita. Per abilitare, impostare questa variabile di ambiente su false.