Abilitare Monitoraggio di Azure OpenTelemetry per applicazioni .NET, Node.js, Python e Java

Questo articolo descrive come abilitare e configurare la raccolta dati basata su OpenTelemetry all'interno di Monitoraggio di Azure Application Insights usando la distribuzione Monitoraggio di Azure OpenTelemetry. OpenTelemetry è lo standard open source di osservabilità della CNCF; Monitoraggio di Azure OpenTelemetry Distro è la distribuzione di Microsoft di questo standard, ottimizzata per Monitoraggio di Azure. La distribuzione:

• Fornisce una distribuzione OpenTelemetry, che include il supporto per le funzionalità specifiche di Monitoraggio di Azure.
• Abilita la raccolta automatica dei dati di telemetria includendo librerie di strumentazione OpenTelemetry per raccogliere tracce, metriche, log ed eccezioni.
• Consente di raccogliere dati di telemetria personalizzati.
• Supporta metriche attive per monitorare e raccogliere dati di telemetria da applicazioni Web in produzione attive.

Per altre informazioni sui vantaggi dell'uso della distribuzione Monitoraggio di Azure OpenTelemetry, vedere Why è consigliabile usare la distribuzione Monitoraggio di Azure OpenTelemetry.

Per altre informazioni sulla raccolta di dati con OpenTelemetry, vedere la panoramica di Application Insights o le domande frequenti su OpenTelemetry.

Seguire la procedura descritta in questo articolo per installare la distribuzione, connetterla alla risorsa di Application Insights e verificare che i dati di telemetria vengano trasmessi a Monitoraggio di Azure.

Suggerimento

Per una panoramica concettuale delle opzioni OpenTelemetry in Monitoraggio di Azure: inserimento OTLP nativo, distribuzione Microsoft OpenTelemetry e esperienze di osservabilità end-to-end, vedere OpenTelemetry con Monitoraggio di Azure.

Stato di rilascio di OpenTelemetry

Le offerte OpenTelemetry sono disponibili per le applicazioni .NET, Node.js, Python e Java. Per lo stato di rilascio di ciascuna funzionalità, consulta le FAQ.

Nota

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

Abilitare OpenTelemetry con Application Insights

Seguire la procedura descritta in questa sezione per instrumentare l'applicazione con OpenTelemetry. Selezionare una scheda per istruzioni specifiche della lingua.

La tabella seguente riepiloga i pacchetti e installa i comandi per ogni lingua supportata:

Lingua	Package	Installa comando
ASP.NET Core	Azure.Monitor.OpenTelemetry.AspNetCore	dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
.NET	Azure.Monitor.OpenTelemetry.Exporter	dotnet add package Azure.Monitor.OpenTelemetry.Exporter
Java	applicationinsights-agent-3.7.8.jar	Download da GitHub
Node.js	@azure/monitor-opentelemetry	npm install @azure/monitor-opentelemetry
Python	azure-monitor-opentelemetry	pip install azure-monitor-opentelemetry

Nota

.NET illustra più scenari, tra cui ASP.NET classici, app console, Windows Forms (WinForm) e altro ancora.

Prerequisiti

• sottoscrizione Azure: Creare gratuitamente una sottoscrizione Azure
• Risorsa di Application Insights: creare una risorsa di Application Insights

ASP.NET Core

• ASP.NET Core Application usando una versione ufficialmente supportata di .NET

Suggerimento

Se si esegue la migrazione da SDK di Application Insights meno recenti, vedere la documentazione sulla migrazione.

.NET

• Applicazione che usa una versione supportata di .NET o .NET Framework 4.6.2 e versioni successive.

Suggerimento

Se si esegue la migrazione da SDK di Application Insights meno recenti, vedere la documentazione sulla migrazione.

Java

• Un'applicazione Java che usa Java 8+

Java nativo

• Un'applicazione Java con GraalVM 17+

Node.js

• Applicazione che usa una versione ufficialmente supportata del runtime di Node.js:
  • Runtime supportati da OpenTelemetry
  • Runtime supportati dall'esportatore OpenTelemetry di Monitoraggio di Azure

Nota

Se non ci si basa su alcuna proprietà elencata nella tabella degli elementi non supportati, lo shim ApplicationInsights è il percorso più semplice da seguire una volta usciti dalla versione beta.

Se si fa affidamento su una di queste proprietà, procedere con la distribuzione OpenTelemetry di Monitoraggio di Azure.

Suggerimento

Se si esegue la migrazione da SDK di Application Insights meno recenti, vedere la documentazione sulla migrazione.

Python

• Applicazione Python utilizzando Python 3.8+

Suggerimento

Se si esegue la migrazione da OpenCensus, vedere la documentazione sulla migrazione.

Installare la libreria client

ASP.NET Core

Installare il pacchetto più recente Azure.Monitor.OpenTelemetry.AspNetCoreNuGet:

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

.NET

Installare il pacchetto più recente Azure.Monitor.OpenTelemetry.ExporterNuGet:

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Java

Scaricare il file applicationinsights-agent-3.7.8.jar più recente.

Avviso

Se si esegue l'aggiornamento da una versione 3.x precedente, è possibile influire sulla modifica delle impostazioni predefinite o sulle lievi differenze nei dati raccolti. Per altre informazioni, vedere la sezione relativa alla migrazione nelle note sulla versione. 3.5.0, 3.4.0, 3.3.0, 3.2.0 e 3.1.0

Java nativo

Per le applicazioni native Spring Boot:

• Importare le distinte base (DB) di OpenTelemetry.
• Aggiungere la dipendenza Spring Cloud Azure Starter Monitor.
• Seguire le istruzioni per i file JAR Azure SDK (archivio Java).

Per le applicazioni native Quarkus:

• Aggiungere la dipendenza Quarkus OpenTelemetry Exporter for Azure.

Nota

La community di Quarkus supporta e gestisce le estensioni Quarkus. Per assistenza, usare i canali di supporto della community di Quarkus. Microsoft non fornisce supporto tecnico per questa integrazione.

Node.js

Installare il pacchetto più recente @azure/monitor-opentelemetry :

npm install @azure/monitor-opentelemetry

I pacchetti seguenti vengono usati anche per alcuni scenari specifici descritti più avanti in questo articolo:

• @opentelemetry/API
• @opentelemetry/sdk-metrics
• @opentelemetry/resources
• @opentelemetry/semantic-conventions
• @opentelemetry/sdk-trace-base

npm install @opentelemetry/api
npm install @opentelemetry/sdk-metrics
npm install @opentelemetry/resources
npm install @opentelemetry/semantic-conventions
npm install @opentelemetry/sdk-trace-base

Python

Installare la versione più recente del pacchetto azure-monitor-opentelemetry PyPI:

pip install azure-monitor-opentelemetry

Modificare l'applicazione

ASP.NET Core

Importare lo spazio dei nomi Azure.Monitor.OpenTelemetry.AspNetCore, aggiungere OpenTelemetry e configurarlo per l'uso di Monitoraggio di Azure nella classe program.cs:

// Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
using Azure.Monitor.OpenTelemetry.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

.NET

Aggiungere il Monitoraggio di Azure Exporter a ogni segnale OpenTelemetry nella classe program.cs:

// Create a new tracer provider builder and add an Azure Monitor trace exporter to the tracer provider builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace#tracerprovider-management
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter();

// Add an Azure Monitor metric exporter to the metrics provider builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics#meterprovider-management
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs#logger-management
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddAzureMonitorLogExporter();
    });
});

Nota

Per altre informazioni, vedere l'esercitazione introduttiva su OpenTelemetry .NET

Java

La strumentazione automatica viene abilitata tramite le modifiche alla configurazione. Non sono necessarie modifiche al codice.

Configurare la macchina virtuale Java (JVM) per riferirsi al file jar aggiungendo -javaagent:"path/to/applicationinsights-agent-3.7.8.jar" ai parametri JVM dell'applicazione.

Nota

Il campionamento è abilitato per impostazione predefinita a una velocità di cinque richieste al secondo, facilitando la gestione dei costi. I dati di telemetria potrebbero non essere presenti negli scenari che superano questa frequenza. Per altre informazioni sulla modifica della configurazione di campionamento, vedere Override del 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.

Suggerimento

Per indicazioni specifiche per gli scenari, vedere Introduzione (supplementare).

Suggerimento

Se si sviluppa un'applicazione Spring Boot, è possibile sostituire facoltativamente l'argomento JVM con una configurazione a livello di codice. Per altre informazioni, vedere Using Monitoraggio di Azure Application Insights con Spring Boot.

Java nativo

La strumentazione automatica viene abilitata tramite le modifiche alla configurazione. Non sono necessarie modifiche al codice.

Node.js

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

// Call the `useAzureMonitor()` function to configure OpenTelemetry to use Azure Monitor.
useAzureMonitor();

Python

import logging
# 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
# APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.
configure_azure_monitor(
    logger_name="<your_logger_namespace>",  # Set the namespace for the logger in which you would like to collect telemetry for if you are collecting logging telemetry. This is imperative so you do not collect logging telemetry from the SDK itself.
)
logger = logging.getLogger("<your_logger_namespace>")  # Logging telemetry will be collected from logging calls made with this logger and all of it's children loggers.

Copiare il stringa di connessione dalla risorsa di Application Insights

Il stringa di connessione è univoco e specifica dove la distribuzione Monitoraggio di Azure OpenTelemetry invia i dati di telemetria raccolti.

Suggerimento

Se non si ha già una risorsa di Application Insights, crearne una seguendo questa guida. È consigliabile creare una nuova risorsa anziché usarne una esistente.

Per copiare il stringa di connessione:

1. Passare al riquadro Panoramica della risorsa di Application Insights.
2. Trova la tua stringa di connessione.
3. Posiziona il cursore sulla stringa di connessione e seleziona l'icona Copia negli appunti.

Inserisci la stringa di connessione nel tuo ambiente

Per incollare il stringa di connessione, usare uno dei metodi seguenti:

metodo	Lingue disponibili	Consigliati per
Variabile di ambiente	Tutti	Produzione
File di configurazione (applicationinsights.json)	Solo per Java	Produzione (Java)
Codice	ASP.NET Core, Node.js, Python	Solo sviluppo/test locale

Importante

È consigliabile impostare il stringa di connessione tramite codice solo in ambienti di sviluppo e test locali.

Per l'ambiente di produzione, usare una variabile di ambiente o un file di configurazione (solo Java).

• Imposta la stringa di connessione di Application Insights come variabile di ambiente (consigliata per la produzione)

  Sostituire <Your stringa di connessione> nel comando seguente con il stringa di connessione.

  APPLICATIONINSIGHTS_CONNECTION_STRING=<Your connection string>
  

• Impostare la stringa di connessione di Application Insights in un file di configurazione - Solo Java

  Creare un file di configurazione denominato applicationinsights.json e inserirlo nella stessa directory di applicationinsights-agent-3.7.8.jar con il contenuto seguente:

  {
    "connectionString": "<Your connection string>"
  }
  

  Sostituire <Your stringa di connessione> nel codice JSON precedente con la vostra stringa di connessione univoca.

• Impostare la stringa di connessione di Application Insights nel codice - Solo per ASP.NET Core, Node.js e Python

  Vedere configurazione della stringa di connessione per un esempio di impostazione della stringa di connessione tramite codice.

Nota

Se si imposta il stringa di connessione in più posizioni, viene risolto nell'ordine di precedenza seguente (più alto al più basso):

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

Verificare che i dati vengano trasmessi

Dopo aver configurato la distribuzione di OpenTelemetry Monitoraggio di Azure e impostato il stringa di connessione, eseguire l'applicazione e aprire la risorsa di Application Insights nel portale di Azure per verificare che vengano visualizzate tracce, metriche e log. La visualizzazione dei dati potrebbe richiedere alcuni minuti.

Application Insights è ora abilitato per l'applicazione. I passaggi seguenti sono facoltativi e consentono ulteriori personalizzazioni.

Nota

Nell'ambito dell'uso della strumentazione di Application Insights, vengono raccolti e inviati dati di diagnostica a Microsoft. Questi dati consentono di eseguire e migliorare Application Insights. Altre informazioni sono disponibili nelle domande frequenti su Application Insights.

Importante

Se si dispone di due o più servizi che generano dati di telemetria nella stessa risorsa di Application Insights, è necessario impostare i nomi dei ruoli cloud per rappresentarli correttamente nella mappa delle applicazioni.

Risoluzione dei problemi, commenti e suggerimenti e supporto

Suggerimento

Le sezioni seguenti sono disponibili in tutti gli articoli sulla distribuzione di OpenTelemetry.

Risoluzione dei problemi

ASP.NET Core

Per informazioni sulla risoluzione dei problemi, vedere Risoluzione dei problemi di OpenTelemetry in .NET e Risoluzione dei problemi di telemetria dell'applicazione mancante in Monitoraggio di Azure Application Insights.

.NET

Per informazioni sulla risoluzione dei problemi, vedere Risoluzione dei problemi di OpenTelemetry in .NET e Risoluzione dei problemi di telemetria dell'applicazione mancante in Monitoraggio di Azure Application Insights.

Java

Per informazioni sulla risoluzione dei problemi, vedere Risoluzione dei problemi di OpenTelemetry in Java e Risoluzione dei problemi di telemetria applicativa mancante in Monitoraggio di Azure Application Insights.

Java nativo

Per informazioni sulla risoluzione dei problemi, vedere Risoluzione dei problemi di OpenTelemetry nelle applicazioni Spring Boot con immagine nativa e Risoluzione dei problemi di telemetria applicativa mancante in Monitoraggio di Azure Application Insights.

Node.js

Per informazioni sulla risoluzione dei problemi, vedere Risoluzione dei problemi di OpenTelemetry in Node.js e Risoluzione dei problemi di telemetria dell'applicazione mancanti in Monitoraggio di Azure Application Insights.

Python

Per informazioni sulla risoluzione dei problemi, vedere Risoluzione dei problemi di OpenTelemetry in Python e Risoluzione dei problemi di assenza di telemetria dell'applicazione in Monitoraggio di Azure Application Insights.

Feedback su OpenTelemetry

Per inviare un feedback:

• Compilare il sondaggio dei commenti e suggerimenti dei clienti della community OpenTelemetry.
• Parla di te a Microsoft unendoti alla community dei primi utilizzatori di OpenTelemetry.
• Interagire con altri utenti di Monitoraggio di Azure in Microsoft Tech Community.
• Effettuare una richiesta di funzionalità nel forum Azure feedback.

Support

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

ASP.NET Core

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

.NET

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

Java

• Per problemi di supporto Azure, aprire un ticket di supporto Azure.
• Per informazioni sulla risoluzione dei problemi, vedere i passaggi per la risoluzione dei problemi.
• Per i problemi di OpenTelemetry, contattare direttamente la community di OpenTelemetry .
• Per un elenco dei problemi aperti relativi ad Monitoraggio di Azure Java Autoinstrumentation, vedere la pagina delle issues su GitHub.

Java nativo

• Per problemi di supporto Azure, aprire un ticket di supporto Azure.
• Per i problemi di OpenTelemetry, contattare direttamente la community di OpenTelemetry .
• Per un elenco dei problemi aperti relativi alle applicazioni native Spring Boot, vedere la pagina GitHub Issues Page.
• Per un elenco dei problemi aperti relativi alle applicazioni native Quarkus, vedere la pagina GitHub Issues Page.

Nota

La community di Quarkus supporta e gestisce le estensioni Quarkus. Per assistenza, usare i canali di supporto della community di Quarkus. Microsoft non fornisce supporto tecnico per questa integrazione.

Node.js

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

Python

• Per problemi di supporto Azure, aprire un ticket di supporto Azure.
• Per i problemi di OpenTelemetry, contattare direttamente OpenTelemetry Python community.
• Per un elenco dei problemi aperti relativi alla distribuzione Monitoraggio di Azure, vedere la pagina GitHub Pagina problemi.

Passaggi successivi

ASP.NET Core

• Per esaminare il codice sorgente, vedere il repository Monitoraggio di Azure ASP.NET Core GitHub.
• Per esaminare un'applicazione di esempio, vedere Monitoraggio di Azure OpenTelemetry per ASP.NET Core.
• Per installare il pacchetto NuGet, verificare la disponibilità di aggiornamenti o visualizzare le note sulla versione, vedere la pagina Monitoraggio di Azure pacchetto NuGet AspNetCore.
• Per altre informazioni su OpenTelemetry e sulla relativa community, vedere il repository OpenTelemetry .NET GitHub repository.
• Per abilitare le esperienze di utilizzo, abilitare il monitoraggio degli utenti del Web o del browser.

.NET

• Per esaminare il codice sorgente, vedere il repository GitHub Monitoraggio di Azure Exporter.
• Per esaminare un'applicazione di esempio, vedere Monitoraggio di Azure OpenTelemetry per .NET.
• Per installare il pacchetto NuGet, verificare la disponibilità di aggiornamenti o visualizzare le note sulla versione, vedere la pagina Monitoraggio di Azure Exporter NuGet Package.
• Per altre informazioni su OpenTelemetry e sulla relativa community, vedere il repository OpenTelemetry .NET GitHub repository.
• Per abilitare le esperienze di utilizzo, abilitare il monitoraggio degli utenti del Web o del browser.

Java

• Per esaminare le opzioni di configurazione, vedere Java opzioni di configurazione di strumentazione automatica.
• Per esaminare il codice sorgente, vedere il repository GitHub della strumentazione automatica Java di Monitoraggio di Azure.
• Per esaminare le applicazioni di esempio, vedere Application Insights Java Samples.
• Esamina le note di rilascio su GitHub.
• Per ulteriori informazioni su OpenTelemetry e sulla relativa community, vedere il repository Java GitHub OpenTelemetry.
• Per abilitare le esperienze utente, vedere Abilitare il monitoraggio degli utenti web o del browser.

Java nativo

• Per esaminare il codice sorgente, vedere Monitoraggio di Azure OpenTelemetry Distro in Spring Boot native image Java application and Quarkus OpenTelemetry Exporter for Azure.
• Per esaminare un'applicazione di esempio, vedere Telemetry for GraalVM native images.
• Esamina le note di rilascio su GitHub.
• Scopri di più sulle funzionalità per le applicazioni di immagini native Spring Boot in OpenTelemetry SpringBoot starter
• Scopri ulteriori funzionalità per le applicazioni native Quarkus in Quarkus OpenTelemetry Exporter per Azure.
• Per ulteriori informazioni su OpenTelemetry e sulla relativa community, vedere il repository Java GitHub OpenTelemetry.

Node.js

• Per esaminare il codice sorgente, vedere Monitoraggio di Azure OpenTelemetry for JavaScript repository.
• Per esaminare un'applicazione di esempio, vedere Monitoraggio di Azure OpenTelemetry per Node.js.
• Per installare il pacchetto npm e verificare la disponibilità di aggiornamenti, vedere la @azure/monitor-opentelemetry pagina del pacchetto npm .
• Per ulteriori informazioni su OpenTelemetry e sulla sua community, vedere il repository GitHub di JavaScript OpenTelemetry.
• Per abilitare le esperienze di utilizzo, abilitare il monitoraggio degli utenti del Web o del browser.

Python

• Per esaminare il codice sorgente e la documentazione aggiuntiva, vedere il repository Monitoraggio di Azure Python GitHub.
• Per esaminare le applicazioni di esempio, vedere Monitoraggio di Azure OpenTelemetry per Python.
• Per installare il pacchetto PyPI e verificare la disponibilità di aggiornamenti, vedere la pagina Monitoraggio di Azure Distribuzione del pacchetto PyPI.
• Esamina le note di rilascio su GitHub.
• Per esaminare i componenti e le strumentazioni OpenTelemetry disponibili, vedere il repository OpenTelemetry Contributor Python GitHub repository.
• Per altre informazioni su OpenTelemetry e sulla relativa community, vedere il repository OpenTelemetry Python GitHub repository.
• Per abilitare le esperienze di utilizzo, abilitare il monitoraggio degli utenti del Web o del browser.