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

Se si usa il campionamento a frequenza fissa/percentuale e non si è sicuri del valore su cui impostare la frequenza di campionamento, iniziare con 5% (ovvero, rapporto di campionamento 0,05), quindi regolare la frequenza in base alla precisione delle operazioni indicate nei riquadri 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.

Redact URL Query Strings

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".