Configurare OpenTelemetry di Monitoraggio di Azure

  • Articolo

Questo articolo illustra le impostazioni di configurazione per la distribuzione di OpenTelemetry di Monitoraggio di Azure.

Connection string

Un stringa di connessione in Application Insights definisce la posizione di destinazione per l'invio di dati di telemetria, assicurandosi che raggiunga la risorsa appropriata per il monitoraggio e l'analisi.

Usare uno dei tre modi seguenti per configurare il stringa di connessione:

  • Aggiungere UseAzureMonitor() all'avvio dell'applicazione nella program.cs classe .

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

  • Impostare una variabile di ambiente.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

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

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

Nota

Se si imposta il stringa di connessione in più posizioni, si rispetta la precedenza seguente:

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

Impostare il nome del ruolo cloud 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 eseguire l'override dei valori predefiniti in un elemento che abbia senso per il team. Il valore del nome del ruolo cloud viene visualizzato nella mappa delle applicazioni come nome sotto un nodo.

Impostare il nome del ruolo cloud e l'istanza del ruolo cloud tramite gli attributi delle risorse . Il nome del ruolo cloud usa service.namespace gli attributi e service.name , anche se service.nameservice.namespace non è impostato. L'istanza del ruolo cloud usa il valore dell'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 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();

Abilitare il campionamento

È possibile abilitare il campionamento per ridurre il volume di inserimento dati, riducendo così i costi. Monitoraggio di Azure fornisce un campionatore a frequenza fissa personalizzata che popola gli eventi con un rapporto di campionamento, che Application Insights converte in ItemCount. Il campionatore a frequenza fissa garantisce esperienze accurate e conteggi di eventi. L'sampler è progettato per mantenere le tracce tra i servizi ed è interoperabile con gli SDK di Application Insights meno recenti. Per altre informazioni, vedere Altre informazioni sul campionamento.

Nota

Le metriche e i log non sono interessati dal campionamento.

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

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

Suggerimento

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

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

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

Sono supportate le classi di credenziali fornite da Azure Identity.

  • È consigliabile DefaultAzureCredential per lo sviluppo locale.
  • È consigliabile ManagedIdentityCredential usare le identità gestite assegnate dal sistema e assegnate dall'utente.
    • Per l'assegnazione del sistema, usare il costruttore predefinito senza parametri.
    • Per l'assegnazione dell'utente, specificare l'ID client al costruttore.
  • È consigliabile ClientSecretCredential usare le entità servizio.
    • Specificare l'ID tenant, l'ID client e il segreto client al costruttore.

  1. Installare il pacchetto Azure.Identity più recente:

    dotnet add package Azure.Identity

  2. Specificare la classe di credenziali desiderata:

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

Archiviazione offline e tentativi automatici

Per migliorare l'affidabilità e la resilienza, le offerte basate su OpenTelemetry di Monitoraggio di Azure scrivono nell'archiviazione offline/locale per impostazione predefinita quando un'applicazione perde la connessione con Application Insights. Salva i dati di telemetria dell'applicazione su disco e tenta periodicamente di inviarli di nuovo per un massimo di 48 ore. Nelle applicazioni a carico elevato, i dati di telemetria vengono occasionalmente eliminati per due motivi. In primo luogo, quando viene superato il tempo consentito e secondo, quando viene superata la dimensione massima del file o l'SDK non ha la possibilità di cancellare il file. Se è necessario scegliere, il prodotto salva eventi più recenti rispetto a quelli precedenti. Altre informazioni

Il pacchetto di distribuzione include AzureMonitorExporter, che per impostazione predefinita usa uno dei percorsi seguenti per l'archiviazione offline (elencato 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, è necessario 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à, è necessario impostare AzureMonitorOptions.DisableOfflineStorage = true.

Abilitare l'utilità di esportazione OTLP

È possibile abilitare OpenTelemetry Protocol (OTLP) Exporter insieme all'utilità di esportazione di Monitoraggio di Azure per inviare i dati di telemetria a due posizioni.

Nota

L'utilità di esportazione OTLP viene visualizzata solo per praticità. Non supportiamo ufficialmente l'esportatore OTLP o nessun componente o esperienze 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 l'agente di raccolta OpenTelemetry sia in esecuzione con un ricevitore OTLP. 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

È possibile accedere alle configurazioni OpenTelemetry seguenti tramite variabili di ambiente durante l'uso delle distribuzioni OpenTelemetry di Monitoraggio di Azure.

Variabile di ambiente Descrizione
APPLICATIONINSIGHTS_CONNECTION_STRING Impostarlo sul stringa di connessione per la risorsa di Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Impostarlo su per true 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 Imposta il valore dell'attributo service.name della risorsa. Se service.name viene fornito anche in OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME ha la precedenza.

Domande frequenti

Questa sezione fornisce le risposte alle domande comuni.

Che cos'è OpenTelemetry?

Si tratta di un nuovo standard open source per l'osservabilità. Per altre informazioni, vedere OpenTelemetry.

Perché Monitoraggio di Microsoft Azure investe in OpenTelemetry?

Microsoft è tra i maggiori collaboratori a OpenTelemetry.

Le proposte chiave di valore di OpenTelemetry sono che sono indipendenti dal fornitore e forniscono API/SDK coerenti in tutte le lingue.

Nel corso del tempo, Si ritiene che OpenTelemetry consentirà ai clienti di Monitoraggio di Azure di osservare le applicazioni scritte in lingue diverse dalle lingue supportate. Espande anche i tipi di dati che è possibile raccogliere tramite un set completo di librerie di strumentazione. Inoltre, gli SDK OpenTelemetry tendono ad essere più efficienti su larga scala rispetto ai predecessori, gli SDK di Application Insights.

Infine, OpenTelemetry si allinea alla strategia di Microsoft per adottare l'open source.

Qual è lo stato di OpenTelemetry?

Vedere Stato OpenTelemetry.

Che cos'è la distribuzione di OpenTelemetry di Monitoraggio di Azure?

È possibile considerarlo come un wrapper sottile che aggrega tutti i componenti OpenTelemetry per un'esperienza di prima classe in Azure. Questo wrapper è detto anche distribuzione in OpenTelemetry.

Perché è consigliabile usare la distribuzione di OpenTelemetry di Monitoraggio di Azure?

L'uso della distribuzione OpenTelemetry di Monitoraggio di Azure tramite OpenTelemetry nativo dalla community offre diversi vantaggi:

Nello spirito di OpenTelemetry, abbiamo progettato la distribuzione per essere aperta ed estendibile. Ad esempio, è possibile aggiungere:

  • Esportazione del protocollo OTLP (OpenTelemetry Protocol) e invio simultaneamente a una seconda destinazione
  • Altre librerie di strumentazione non incluse nella distribuzione

Poiché la distribuzione fornisce una distribuzione OpenTelemetry, la distribuzione supporta qualsiasi elemento supportato da OpenTelemetry. Ad esempio, è possibile aggiungere altri processori di telemetria, utilità di esportazione o librerie di strumentazione, se OpenTelemetry li supporta.

Nota

La distribuzione imposta il campionatore su un campionatore personalizzato a frequenza fissa per Application Insights. È possibile passare a un campionatore diverso, ma in questo modo è possibile disabilitare alcune delle funzionalità incluse della distribuzione. Per altre informazioni sull'sampler supportato, vedere la sezione Abilitare il campionamento di Configurare OpenTelemetry di Monitoraggio di Azure.

Per le lingue senza un utilità di esportazione OpenTelemetry autonoma supportata, la distribuzione OpenTelemetry di Monitoraggio di Azure è l'unico modo attualmente supportato per usare OpenTelemetry con Monitoraggio di Azure. Per le lingue con un utilità di esportazione OpenTelemetry autonoma supportata, è possibile usare la distribuzione OpenTelemetry di Monitoraggio di Azure o l'utilità di esportazione OpenTelemetry autonoma appropriata a seconda dello scenario di telemetria. Per altre informazioni, vedere Quando usare l'utilità di esportazione OpenTelemetry di Monitoraggio di Azure?

Come è possibile testare la distribuzione di OpenTelemetry di Monitoraggio di Azure?

Vedere la documentazione di abilitazione per .NET, Java, JavaScript (Node.js) e Python.

È consigliabile usare OpenTelemetry o Application Insights SDK?

È consigliabile usare la distribuzione OpenTelemetry, a meno che non sia necessaria una funzionalità disponibile solo con il supporto formale in Application Insights SDK.

L'adozione di OpenTelemetry impedisce ora di eseguire la migrazione in un secondo momento.

Quando è consigliabile usare l'utilità di esportazione OpenTelemetry di Monitoraggio di Azure?

Per ASP.NET Core, Java, Node.js e Python, è consigliabile usare la distribuzione OpenTelemetry di Monitoraggio di Azure. Si tratta di una riga di codice da iniziare.

Per tutti gli altri scenari .NET, inclusi i ASP.NET classici, le app console e così via, è consigliabile usare l'utilità di esportazione OpenTelemetry di Monitoraggio di Azure .NET: Azure.Monitor.OpenTelemetry.Exporter.

Per scenari di telemetria Python più complessi che richiedono una configurazione avanzata, è consigliabile usare Python Monitoraggio di Azure OpenTelemetry Exporter.

Qual è lo stato di rilascio corrente delle funzionalità nella distribuzione OpenTelemetry di Monitoraggio di Azure?

Nel grafico seguente viene visualizzato il supporto delle funzionalità OpenTelemetry per ogni lingua.

Funzionalità .NET Node.js Python Java
Traccia distribuita ✅ ✅ ✅ ✅
Metriche personalizzate ✅ ✅ ✅ ✅
Metriche standard (accuratezza attualmente interessata dal campionamento) ✅ ✅ ✅ ✅
Campionamento a frequenza fissa ✅ ✅ ✅ ✅
Archiviazione offline e tentativi automatici ✅ ✅ ✅ ✅
Segnalazione eccezioni ✅ ✅ ✅ ✅
Raccolta logs ✅ ⚠️ ✅ ✅
Eventi personalizzati ⚠️ ⚠️ ⚠️ ✅
Autenticazione Microsoft Entra ✅ ✅ ✅ ✅
Metriche attive ❌ ❌ ❌ ✅
Rilevare il contesto delle risorse per vm/set di scalabilità di macchine virtuali e servizio app ✅ ❌ ✅ ✅
Rilevare il contesto delle risorse per il servizio Azure Kubernetes e le funzioni ❌ ❌ ❌ ✅
Filtro intervallo di test di disponibilità ❌ ❌ ❌ ✅
Popolamento automatico dell'ID utente, ID utente autenticato e IP utente ❌ ❌ ❌ ✅
Eseguire manualmente l'override/impostare il nome dell'operazione, l'ID utente o l'ID utente autenticato ❌ ❌ ❌ ✅
Campionamento adattivo ❌ ❌ ❌ ✅
Profiler ❌ ❌ ❌ ⚠️
Debugger di snapshot ❌ ❌ ❌ ❌

Chiave

  • ✅ Questa funzionalità è disponibile per tutti i clienti con supporto formale.
  • ⚠️ Questa funzionalità è disponibile come anteprima pubblica. Vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.
  • ❌ Questa funzionalità non è disponibile o non è applicabile.

È possibile usare OpenTelemetry per i Web browser?

Sì, ma non è consigliabile e Azure non lo supporta. OpenTelemetry JavaScript è fortemente ottimizzato per Node.js. È invece consigliabile usare Application Insights JavaScript SDK.

Quando è possibile prevedere che OpenTelemetry SDK sia disponibile per l'uso nei Web browser?

OpenTelemetry Web SDK non ha una sequenza temporale di disponibilità determinata. Probabilmente ci sono diversi anni di distanza da un SDK del browser che è un'alternativa praticabile all'SDK JavaScript di Application Insights.

È possibile testare OpenTelemetry in un Web browser?

La sandbox Web OpenTelemetry è un fork progettato per consentire il funzionamento di OpenTelemetry in un browser. Non è ancora possibile inviare dati di telemetria ad Application Insights. L'SDK non definisce eventi client generali.

L'esecuzione di Application Insights insieme a agenti concorrenti come AppDynamics, DataDog e NewRelic è supportato?

No. Questa procedura non è un elemento che si prevede di testare o supportare, anche se le distribuzioni consentono di esportare in un endpoint OTLP insieme a Monitoraggio di Azure contemporaneamente.

È possibile usare le funzionalità di anteprima negli ambienti di produzione?

Non è consigliabile. Vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.

Qual è la differenza tra strumentazione manuale e automatica?

Vedere La panoramica di OpenTelemetry.

È possibile usare OpenTelemetry Collector?

Alcuni clienti usano OpenTelemetry Collector come alternativa agente, anche se Microsoft non supporta ufficialmente un approccio basato su agente per il monitoraggio delle applicazioni. Nel frattempo, la community open source ha contribuito a un utilità di esportazione di Monitoraggio di Azure dell'agente di raccolta OpenTelemetry che alcuni clienti usano per inviare dati ad Application Insights di Monitoraggio di Azure. Questo non è supportato da Microsoft.

Qual è la differenza tra OpenCensus e OpenTelemetry?

OpenCensus è il precursore di OpenTelemetry. Microsoft ha contribuito a riunire OpenTracing e OpenCensus per creare OpenTelemetry, un unico standard di osservabilità a livello globale. L'SDK Python attualmente consigliato per la produzione per Monitoraggio di Azure si basa su OpenCensus. Microsoft si impegna a rendere Monitoraggio di Azure basato su OpenTelemetry.

Risoluzione dei problemi

Non funziona? Vedere la pagina relativa alla risoluzione dei problemi per ASP.NET Core.

Supporto tecnico

Selezionare una scheda per la lingua scelta per individuare le opzioni di supporto.

  • Per supporto tecnico di Azure problemi, aprire un ticket di supporto tecnico di Azure.
  • Per i problemi di OpenTelemetry, contattare direttamente la community .NET di OpenTelemetry.
  • Per un elenco dei problemi aperti relativi all'utilità di esportazione di Monitoraggio di Azure, vedere la pagina problemi di GitHub.

Commenti e suggerimenti su OpenTelemetry

Per fornire commenti e suggerimenti: