Condividi tramite

Aggiungere e modificare Azure Monitor OpenTelemetry per applicazioni .NET, Java, Node.js e Python

Questa guida fornisce istruzioni sull'integrazione e la personalizzazione della strumentazione OpenTelemetry (OTel) in Azure Monitor Application Insights.

Per altre informazioni sui concetti relativi a OpenTelemetry, vedere panoramica di OpenTelemetry o Domande frequenti su OpenTelemetry.

Nota

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

Raccolta dati automatica

Le distribuzioni raccolgono automaticamente i dati raggruppando librerie di strumentazione OpenTelemetry.

Librerie di strumentazione incluse

Richieste

Dipendenze

Registrazione

  • ILogger

Per ridurre o aumentare il numero di log inviati a Monitoraggio di Azure, configurare la registrazione per impostare il livello di log appropriato o applicare filtri. Ad esempio, è possibile scegliere di inviare solo Warning e Error log a OpenTelemetry/Azure Monitor. OpenTelemetry non controlla il routing o il filtro dei log. La ILogger configurazione prende queste decisioni. Per altre informazioni sulla configurazione di ILogger, vedere Configurare la registrazione.

Per altre informazioni su ILogger, vedere Registrazione in C# e .NET ed esempi di codice.

Note a piè di pagina

  • ¹: supporta la creazione automatica di report di eccezioni non gestite/non rilevate
  • ²: supporta le metriche OpenTelemetry

Nota

Le distribuzioni di Azure Monitor OpenTelemetry includono logica e mappatura personalizzata per emettere automaticamente metriche standard di Application Insights.

Suggerimento

Tutte le metriche di OpenTelemetry raccolte automaticamente dalle librerie di strumentazione o raccolte manualmente dalla codifica personalizzata sono attualmente considerate "metriche personalizzate" di Application Insights ai fini della fatturazione. Altre informazioni.

Aggiungere una libreria di strumentazione di comunità

È possibile raccogliere più dati automaticamente quando si includono librerie di strumentazione della community OpenTelemetry.

Attenzione

Non è supportata né garantita la qualità delle librerie di strumentazione della community. Per suggerirne uno per una distribuzione, pubblicare o votare a favore utilizzando i commenti e suggerimenti della community. Essere consapevoli che alcune si basano sulle specifiche sperimentali di OpenTelemetry e potrebbero introdurre modifiche di rilievo nel futuro.

Per aggiungere una libreria della community, usare i metodi ConfigureOpenTelemetryMeterProvider o ConfigureOpenTelemetryTracerProvider dopo aver aggiunto il pacchetto NuGet per la libreria.

Ecco un esempio che dimostra come aggiungere la strumentazione di runtime per raccogliere ulteriori metriche:

dotnet add package OpenTelemetry.Instrumentation.Runtime 

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Rilevatori di risorse

I rilevatori di risorse individuano i metadati dell'ambiente all'avvio e popolano gli attributi delle risorse OpenTelemetry, service.namead esempio , cloud.providere cloud.resource_id. Questi metadati supportano esperienze in Application Insights, ad esempio Mappa applicazioni e collegamento dei servizi di calcolo, e migliorano la correlazione tra tracce, metriche e log.

Suggerimento

Gli attributi delle risorse descrivono il processo e il relativo ambiente. Gli attributi span descrivono una singola operazione. Usare gli attributi delle risorse per le proprietà a livello di app, ad esempio service.name.

Ambienti supportati

Ambiente Funzionamento del rilevamento Note
Servizio app di Azure L'SDK del linguaggio o la distribuzione di Monitoraggio di Azure legge le variabili di ambiente note di Servizio app e i metadati dell'host Funziona con .NET, Java, Node.jse Python quando si usano le linee guida in questo articolo.
Azure Functions Vedere la procedura OpenTelemetry per Funzioni di Azure Tutte le linee guida su Azure Functions si trovano lì.
Macchine virtuali di Azure Lo SDK del linguaggio o la distribuzione esegue una query sul servizio metadati dell'istanza di Azure. Verificare che la macchina virtuale abbia accesso all'endpoint del servizio metadati dell'istanza.
Il Servizio Azure Kubernetes (AKS) Usare il processore dell'agente di raccolta k8sattributes OpenTelemetry per aggiungere metadati Kubernetes Consigliato per tutti i linguaggi in esecuzione nel servizio Azure Kubernetes.
App contenitore di Azure I rilevatori eseguono il mapping delle variabili di ambiente e degli identificatori di risorsa, se disponibili È anche possibile impostare OTEL_RESOURCE_ATTRIBUTES per riempire le lacune.

Strumentazione manuale e automatica

  • La strumentazione automatica e le distribuzioni di Monitoraggio di Azure abilitano il rilevamento delle risorse quando sono in esecuzione in ambienti di Azure in cui è supportato.

  • Per le configurazioni manuali, è possibile impostare gli attributi delle risorse direttamente con le opzioni OpenTelemetry standard:

    # Applies to .NET (ASP.NET/ASP.NET Core), Java, Node.js, and Python
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

    In Windows PowerShell:

    $Env:OTEL_SERVICE_NAME="my-service"
$Env:OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

Considerazioni sull'ingestione OTLP

  • Application Insights usa service.name per derivare il nome del ruolo cloud. Scegliere un nome stabile per servizio per evitare nodi frammentati nella mappa delle applicazioni.
  • cloud.resource_id migliora il collegamento di calcolo alle risorse di Azure. Se questo attributo non è presente, alcune esperienze potrebbero non mostrare la risorsa di Azure che ha prodotto i dati.

Raccogliere dati di telemetria personalizzati

Questa sezione illustra come raccogliere dati di telemetria personalizzati dall'applicazione.

A seconda della lingua e del tipo di segnale, esistono diversi modi per raccogliere dati di telemetria personalizzati, tra cui:

  • API OpenTelemetry
  • Librerie di registrazione/metriche specifiche del linguaggio
  • API Classica di Application Insights

Nota

Micrometer Tracing API per Java non è supportata.

La tabella seguente rappresenta i tipi di telemetria personalizzati attualmente supportati:

Lingua Eventi personalizzati Metriche personalizzate Dipendenze Eccezioni Visualizzazioni pagina Requests Traces
ASP.NET Core
   API OpenTelemetry Sì Sì Sì Sì
    API ILogger Sì
   API IA classica
Giava
   API OpenTelemetry Sì Sì Sì Sì
   Logback, Log4j, JUL Sì Sì
   Metriche di Micrometer Sì
   API IA classica Sì Sì Sì Sì Sì Sì Sì
Node.js
   API OpenTelemetry Sì Sì Sì Sì
Pitone
   API OpenTelemetry Sì Sì Sì Sì
   Modulo di registrazione Python Sì
   Estensione eventi Sì Sì

Nota

Application Insights Java 3.x e Application Insights Node.js 3.x raccolgono i dati di telemetria dall'API classica di Application Insights. Questo comportamento semplifica gli aggiornamenti e supporta temporaneamente i dati di telemetria personalizzati fino a quando l'API OpenTelemetry include tutti i tipi di telemetria personalizzati.

Aggiungere le metriche personalizzate

In questo contesto, il termine delle metriche personalizzate si riferisce alla strumentazione manuale del codice per raccogliere metriche aggiuntive oltre a quanto raccolto automaticamente dalle librerie di strumentazione OpenTelemetry. Per altre informazioni sull'uso delle metriche, vedere Metriche in Application Insights.

L'API OpenTelemetry offre sei “strumenti” di metrica per coprire vari scenari di metrica ed è necessario scegliere il “tipo di aggregazione” corretto durante la visualizzazione delle metriche in Esplora metriche. Questo requisito è vero quando si usa l'API metrica OpenTelemetry per inviare metriche e quando si usa una libreria di strumentazione.

La tabella seguente illustra i tipi di aggregazione consigliati per ognuno di OpenTelemetry Metric Instruments.

Strumento OpenTelemetry Tipo di aggregazione di Monitoraggio di Azure
Contatore Somma
Contatore asincrono Somma
Istogramma Min, Max, Media, Somma e Numero
Misuratore asincrono Media
UpDownCounter Somma
UpDownCounter asincrono Somma

Attenzione

Altri tipi di aggregazione non sono significativi nella maggior parte dei casi.

La specifica OpenTelemetry descrive gli strumenti e fornisce esempi di quando è possibile usare ognuno di essi.

Suggerimento

L'istogramma è il più versatile e più strettamente equivalente all'API getMetric classica di Application Insights. Monitoraggio di Azure attualmente semplifica lo strumento istogramma nei cinque tipi di aggregazione supportati e il supporto per i percentili è in corso. Anche se meno versatile, altri strumenti OpenTelemetry hanno un effetto minore sulle prestazioni dell'applicazione.

Esempio di istogramma

L'avvio dell'applicazione deve sottoscrivere un contatore in base al nome:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter deve essere inizializzato utilizzando lo stesso nome:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Controesempio

L'avvio dell'applicazione deve sottoscrivere un contatore in base al nome:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter deve essere inizializzato utilizzando lo stesso nome:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Esempio di misuratore

L'avvio dell'applicazione deve sottoscrivere un contatore in base al nome:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter deve essere inizializzato utilizzando lo stesso nome:

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

Aggiungere eccezioni personalizzate

Selezionare le librerie di strumentazione che segnalano automaticamente le eccezioni ad Application Insights. Tuttavia, potresti voler segnalare manualmente le eccezioni oltre a quelle che riportano le librerie di strumentazione. Ad esempio, le eccezioni rilevate dal codice non vengono in genere segnalate. È possibile segnalarle per attirare l'attenzione sulle esperienze pertinenti, tra cui la sezione errori e le viste delle transazioni end-to-end.

  • Per registrare un'eccezione usando un'attività:

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Per registrare un'eccezione usando ILogger:

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Aggiungere intervalli personalizzati

È possibile aggiungere un intervallo personalizzato in due scenari. In primo luogo, quando è presente una richiesta di dipendenza non già raccolta da una libreria di strumentazione. In secondo luogo, quando si vuole modellare un processo dell'applicazione come segmento nella visualizzazione delle transazioni end-to-end.

Nota

Le classi Activity e ActivitySource dello spazio dei nomi System.Diagnostics rappresentano rispettivamente i concetti OpenTelemetry di Span e Tracer. È possibile creare ActivitySource direttamente usando il relativo costruttore anziché TracerProvider. Ogni classe ActivitySource deve essere connessa in modo esplicito a TracerProvider tramite AddSource(). È dovuto al fatto che parti dell'API di traccia OpenTelemetry vengono incorporate direttamente nel runtime .NET. Per altre informazioni, vedere Introduzione all'API di tracing di OpenTelemetry .NET.

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity per impostazione predefinita è ActivityKind.Internal, ma è possibile specificare qualsiasi altro ActivityKind. ActivityKind.Client, ActivityKind.Producer e ActivityKind.Internal vengono mappati a dependencies Application Insights. ActivityKind.Server e ActivityKind.Consumer vengono mappati a requests Application Insights.

Inviare eventi personalizzati

Application Insights archivia eventi personalizzati nella customEvents tabella. Un modo per analizzare, filtrare e visualizzarli consiste nell'usare le esperienze di utilizzo di Application Insights.

Se si vuole automatizzare la raccolta di eventi di interazione lato client, è possibile usare il plug-in in JavaScript SDK.

Gli eventi personalizzati sono disponibili in anteprima pubblica e utilizzano Azure.Monitor.OpenTelemetry.AspNetCore 1.3.0-beta.3.

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.

Per inviare un CustomEvent utilizzando ILogger, impostare l'attributo "microsoft.custom_event.name" nel modello di messaggio.

// Create a logger factory and configure OpenTelemetry with Azure Monitor
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddOpenTelemetry(options =>
        {
            options.AddAzureMonitorLogExporter();
        });
});

// Create a logger for the specified category
var logger = loggerFactory.CreateLogger(logCategoryName);

// Log a custom event with a custom name and additional attribute
// The 'microsoft.custom_event.name' value will be used as the name of the customEvent
logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}", "test-event-name", "val1");

Modificare la telemetria

Questa sezione illustra come modificare i dati di telemetria.

Aggiungere attributi span

Questi attributi possono includere l'aggiunta di una proprietà personalizzata ai dati di telemetria. È inoltre possibile usare gli attributi per impostare campi facoltativi nello schema di Application Insights, ad esempio IP client.

Aggiungere una proprietà personalizzata a un Span

Tutti gli attributi aggiunti agli intervalli vengono esportati come proprietà personalizzate. Popolano il campo customDimensions nella tabella richieste, dipendenze, tracce o eccezioni.

Per aggiungere attributi di span, usare uno dei seguenti due modi:

Suggerimento

Il vantaggio di usare le opzioni fornite dalle librerie di strumentazione, quando sono disponibili, è che l'intero contesto sia disponibile. Di conseguenza, gli utenti possono effettuare una selezione per aggiungere o filtrare altri attributi. Ad esempio, l'opzione enrich nella libreria di strumentazione HttpClient consente agli utenti di accedere a HttpRequestMessage e a HttpResponseMessage stesso. Da lì, possono selezionare qualsiasi elemento e archiviarlo come attributo.

  1. Molte librerie di strumentazione offrono un'opzione di arricchimento. Per indicazioni, vedere i file leggimi delle singole librerie di strumentazione:

  2. Usare un processore personalizzato:

    Suggerimento

    Aggiungere il processore illustrato qui prima di aggiungere Azure Monitor.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Aggiungere ActivityEnrichingProcessor.cs al progetto con il codice seguente:

    public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Impostare l'IP utente

È possibile popolare il campo client_IP per le richieste impostando un attributo sull'intervallo. Application Insights usa l'indirizzo IP per generare gli attributi di posizione utente e quindi lo rimuove per impostazione predefinita.

Usare l'esempio di proprietà personalizzata, ma sostituire le righe di codice seguenti in ActivityEnrichingProcessor.cs:

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

Impostare l'ID utente o l'ID utente autenticato

È possibile popolare il campo user_Id o user_AuthenticatedId per le richieste usando le indicazioni seguenti. L'ID utente è un ID utente anonimo. L'ID utente autenticato è un ID utente noto.

Importante

Prima di impostare l'ID utente autenticato, consultare le leggi sulla privacy applicabili.

Usare l'esempio di proprietà personalizzata:

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

Aggiungere attributi di log

OpenTelemetry usa ILogger di .NET. È possibile allegare dimensioni personalizzate ai log usando un modello di messaggio.

Ottenere l'ID di traccia o l'ID intervallo

È possibile ottenere il Trace ID e il Span ID dello Span attualmente attivo seguendo i passaggi seguenti.

Nota

Le classi Activity e ActivitySource dello spazio dei nomi System.Diagnostics rappresentano rispettivamente i concetti OpenTelemetry di Span e Tracer. È dovuto al fatto che parti dell'API di traccia OpenTelemetry vengono incorporate direttamente nel runtime .NET. Per altre informazioni, vedere Introduzione all'API di tracing di OpenTelemetry .NET.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Passaggi successivi

  • Last updated on