Condividi tramite

Configurare OpenTelemetry di Monitoraggio di Azure

  • Articolo

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

Stringa di connessione

Una stringa di connessione in Application Insights definisce il percorso di destinazione dei dati di telemetria, in modo da avere la certezza che raggiungano la risorsa appropriata per le attività di monitoraggio e analisi.

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

  • Aggiungere UseAzureMonitor() all'avvio dell'applicazione nella classe 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();

  • 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 della risorsa e fornisce i valori predefiniti per le proprietà Nome del 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.

Impostare il nome e l'istanza del ruolo cloud tramite gli attributi dell'opzione Risorsa. Il nome del ruolo cloud usa gli attributi service.namespace e service.name ma, se service.namespace non è impostato, esegue il fallback a service.name. L'istanza del ruolo cloud usa il valore di attributo service.instance.id. Per informazioni sugli attributi standard per le risorse, vedere Convenzioni semantiche di 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

Per ridurre il volume di inserimento dati, limitando quindi i costi, è possibile abilitare il campionamento. Monitoraggio di Azure offre un campionatore a frequenza fissa personalizzato che popola gli eventi con un rapporto di campionamento, convertito da Application Insights in ItemCount. Il campionatore a frequenza fissa garantisce esperienze accurate e conteggi degli 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.

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

Se si usa il campionamento a velocità fissa/percentuale e non si è certi del valore su cui impostare la frequenza di campionamento, iniziare con 5% (impostando il rapporto di campionamento su 0,05) e regolare la frequenza in base all'accuratezza delle operazioni deducibile dai pannelli degli errori e delle prestazioni. Una frequenza più elevata comporta in genere un'accuratezza maggiore. Tuttavia, poiché il grado di accuratezza viene determinato da QUALSIASI tipo di campionamento, è consigliabile anche inviare avvisi sulle metriche di OpenTelemetry escluse dal campionamento.

Metriche attive

Metriche in tempo reale: fornisce un dashboard di analisi in tempo reale per ottenere informazioni dettagliate sull'attività e sulle prestazioni dell'applicazione.

Importante

Vedere le condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, in anteprima o in altro modo non ancora disponibili a livello 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.

Sono supportate le classi di credenziali fornite da Azure Identity.

  • Usare DefaultAzureCredential per lo sviluppo locale.
  • Usare ManagedIdentityCredential per le identità gestite assegnate dal sistema o assegnate dall'utente.
    • In caso di assegnazione dal sistema, usare il costruttore predefinito senza parametri.
    • In caso di assegnazione dall'utente, fornire l'ID client al costruttore.
  • Usare ClientSecretCredential per le entità servizio.
    • Fornire all'istruttore l'ID tenant, l'ID client e il segreto client.

  1. Installare la versione più recente del pacchetto Azure.Identity.

    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 retry automatici

Per migliorare l'affidabilità e la resilienza, per impostazione predefinita le offerte basate su OpenTelemetry di Monitoraggio di Azure scrivono su risorse di archiviazione offline/locali nel caso in cui un'applicazione perda la connessione con Application Insights. Salva i dati di telemetria dell'applicazione su disco ed esegue periodicamente nuovi tentativi di invio per un massimo di 48 ore. Nelle applicazioni a carico elevato, i dati di telemetria vengono talvolta eliminati per due motivi, ovvero quando viene superato il tempo consentito oppure quando viene superata la dimensione massima del file o l'SDK non ha la possibilità di cancellare il file. Se è necessario effettuare una scelta, il prodotto salva prima gli eventi più recenti, quindi quelli meno recenti. Altre informazioni

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 su 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 di risorsa, vedere Specifiche dell'SDK della risorsa.
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.

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 Azure Microsoft investe in OpenTelemetry?

Microsoft è tra i maggiori collaboratori di OpenTelemetry.

Le principali proposte di valore di OpenTelemetry sono il fatto che sia indipendente dal fornitore e che offra API/SDK coerenti in tutti i linguaggi.

Riteniamo che nel tempo OpenTelemetry consentirà ai clienti di Monitoraggio di Azure di osservare le applicazioni scritte in altri linguaggi oltre ai linguaggi supportati. Espande anche i tipi di dati che è possibile raccogliere tramite un set completo di librerie di strumentazione. Inoltre, OpenTelemetry Software Development Kit (SDK) tende a essere più efficiente su larga scala rispetto ai predecessori, gli SDK di Application Insights.

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

Qual è lo stato di OpenTelemetry?

Vedere Stato di OpenTelemetry.

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

Può essere considerata un wrapper sottile che aggrega tutti i componenti OpenTelemetry per un'esperienza di prima classe in Azure. In OpenTelemetry questo wrapper è detto anche distribuzione.

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

L'uso della distribuzione OpenTelemetry di Azure Monitor presenta diversi vantaggi rispetto a OpenTelemetry nativo della community:

Nello spirito di OpenTelemetry, abbiamo progettato la distribuzione in modo che sia aperta ed estendibile. Ad esempio, è possibile aggiungere:

  • Esportazione del protocollo OTLP (OpenTelemetry Protocol) e invio simultaneo 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 ciò potrebbe disabilitare alcune delle funzionalità incluse della distribuzione. Per altre informazioni sul campionatore supportato, vedere la sezione Abilitare il campionamento di Configurare OpenTelemetry di Monitoraggio di Azure.

Per i linguaggi privi di 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 i linguaggi 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 OpenTelemetry di Monitoraggio di Azure?

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

È consigliabile usare OpenTelemetry o l’SDK Application Insights?

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

L'adozione di OpenTelemetry ora consente di non dover effettuare 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 con cui iniziare.

Per tutti gli altri scenari .NET, inclusi ASP.NET classico, app console, Windows Forms (WinForms) 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 l’utilità di esportazione OpenTelemetry di Monitoraggio di Azure Python.

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

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

Funzionalità .NET Node.js Python Java
Traccia distribuita ✅ ✅ ✅ ✅
Metriche personalizzate ✅ ✅ ✅ ✅
Metriche standard (accuratezza attualmente interessata dal campionamento) ✅ ✅ ✅ ✅
Campionamento a frequenza fissa ✅ ✅ ✅ ✅
Archiviazione offline e retry automatici ✅ ✅ ✅ ✅
Segnalazione eccezioni ✅ ✅ ✅ ✅
Raccolta di log ✅ ⚠️ ✅ ✅
Eventi personalizzati ⚠️ ⚠️ ⚠️ ✅
Autenticazione Microsoft Entra ✅ ✅ ✅ ✅
Metriche attive ✅ ✅ ✅ ✅
Filtro delle metriche attive ❌ ❌ ❌ ❌
Rilevare il contesto delle risorse per macchine virtuali/set di scalabilità di macchine virtuali e servizio app ✅ ❌ ✅ ✅
Rilevare il contesto delle risorse per servizio Azure Kubernetes e Funzioni ❌ ❌ ❌ ✅
Eventi di test della disponibilità generati tramite l'API Traccia disponibilità ❌ ❌ ❌ ✅
Filtrare le richieste, le dipendenze, i log e le eccezioni in base all'ID utente anonimo e all'origine sintetica ❌ ❌ ❌ ✅
Filtrare dipendenze, log ed eccezioni in base al nome dell'operazione ❌ ❌ ❌ ✅
Campionamento adattivo ❌ ❌ ❌ ✅
Profiler ✅ ❌ ❌ ⚠️
Debugger di snapshot ✅ ❌ ❌ ❌

Chiave

È 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 l’SDK JavaScript Application Insights.

Per quando è prevista la disponibilità dell’SDK OpenTelemetry per l'uso nei Web browser?

L’SDK Web OpenTelemetry non ha una timeline di disponibilità determinata. Probabilmente serviranno diversi anni perché un SDK browser sia una valida alternativa all'SDK JavaScript di Application Insights.

Oggi è 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 è supportata?

Non sono previsti il supporto e il test di questa pratica, anche se le distribuzioni consentono di esportare simultaneamente verso un endpoint OTLP e Monitoraggio di Azure.

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

Non è una scelta consigliata. 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.

Che cos'è l'agente di raccolta OpenTelemetry?

Alcuni clienti usano l’agente di raccolta OpenTelemetry come alternativa agente, anche se al momento 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 di ASP.NET Core.

Supporto tecnico

Selezionare la scheda del linguaggio scelto per scoprire le opzioni di supporto.

Feedback su OpenTelemetry

Per inviare un feedback: