Condividi tramite

Usare OpenTelemetry con Funzioni di Azure

Questo articolo illustra come configurare l'app per le funzioni per esportare i dati di log e traccia in un formato OpenTelemetry. Funzioni di Azure genera dati di telemetria sulle esecuzioni delle funzioni sia dal processo host di Funzioni che dal processo di lavoro specifico del linguaggio in cui viene eseguito il codice della funzione. Per impostazione predefinita, questi dati di telemetria vengono inviati ad Application Insights usando Application Insights SDK. È tuttavia possibile scegliere di esportare questi dati usando la semantica OpenTelemetry. Anche se è ancora possibile usare un formato OpenTelemetry per inviare i dati ad Application Insights, è ora possibile esportare gli stessi dati in qualsiasi altro endpoint conforme a OpenTelemetry.

È possibile ottenere questi vantaggi abilitando OpenTelemetry nell'app per le funzioni:

  • Correla i dati tra tracce e log generati sia nell'host che nel codice dell'applicazione.
  • Consente una generazione coerente basata su standard di dati di telemetria esportabili.
  • Si integra con altri provider che possono utilizzare dati conformi a OpenTelemetry.

Tenere presenti queste considerazioni quando si usa questo articolo:

  • Provare l'esercitazione OpenTelemetry, progettata per iniziare rapidamente a usare OpenTelemetry e Funzioni di Azure. Questo articolo usa l'interfaccia della riga di comando per sviluppatori di Azure (azd) per creare e distribuire un'app per le funzioni che usa l'integrazione OpenTelemetry per la traccia distribuita.

  • Poiché questo articolo è destinato al linguaggio di sviluppo preferito, ricordarsi di scegliere il linguaggio corretto nella parte superiore dell'articolo.

  • OpenTelemetry è abilitato a livello di app per le funzioni, sia nella configurazione host (host.json) che nel progetto di codice. Funzioni offre anche un'esperienza ottimizzata per il client per l'esportazione dei dati OpenTelemetry dal codice della funzione in esecuzione in un processo di lavoro specifico del linguaggio.

Abilitare OpenTelemetry nell'host di Funzioni

Quando abiliti l'output di OpenTelemetry nel file host.json della funzione app, l'host esporta l'output di OpenTelemetry indipendentemente dallo stack linguistico utilizzato dall'app.

Per abilitare l'output di OpenTelemetry dall'host di Funzioni, aggiornare il file host.json nel progetto di codice per aggiungere un elemento "telemetryMode": "OpenTelemetry" alla raccolta radice. Con OpenTelemetry abilitato, il file host.json potrebbe essere simile al seguente:

{
    "version": "2.0",
    "telemetryMode": "OpenTelemetry",
    ...
}

Configurare le impostazioni dell'applicazione

Quando si abilita OpenTelemetry nel host.json file, le variabili di ambiente dell'app determinano gli endpoint per l'invio di dati in base alle impostazioni dell'applicazione supportate da OpenTelemetry.

Creare impostazioni dell'applicazione specifiche nell'app per le funzioni in base alla destinazione di output di OpenTelemetry. Quando si specificano le impostazioni di connessione per Application Insights e un'utilità di esportazione OTLP (OpenTelemetry Protocol), i dati OpenTelemetry vengono inviati a entrambi gli endpoint.

APPLICATIONINSIGHTS_CONNECTION_STRING: stringa di connessione per un'area di lavoro di Application Insights. Quando questa impostazione esiste, i dati OpenTelemetry vengono inviati all'area di lavoro. Usare la stessa impostazione per connettersi ad Application Insights senza OpenTelemetry abilitato. Se l'app non ha già questa impostazione, potrebbe essere necessario abilitare l'integrazione di Application Insights.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: valore impostato su true in modo che l'host di Funzioni consenta al processo di lavoro Java di trasmettere direttamente i log OpenTelemetry, che impedisce voci duplicate a livello di host.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: valore impostato su true in modo che l'host di Funzioni consenta al processo di lavoro Python di trasmettere direttamente i log di OpenTelemetry, che impedisce voci duplicate a livello di host.

Abilitare OpenTelemetry nell'app

Dopo aver configurato l'host di Funzioni per l'uso di OpenTelemetry, aggiornare il codice dell'applicazione per l'output dei dati OpenTelemetry. Quando si abilita OpenTelemetry sia nell'host che nel codice dell'applicazione, si ottiene una migliore correlazione tra tracce e log generati dal processo host di Funzioni e dal processo di lavoro del linguaggio.

La modalità di strumentazione dell'applicazione per l'uso di OpenTelemetry dipende dall'endpoint OpenTelemetry di destinazione:

Gli esempi in questo articolo presuppongono che l'app usi IHostApplicationBuilder, disponibile nella versione 2.x e successiva di Microsoft.Azure.Functions.Worker. Per altre informazioni, vedere la versione 2.x nella guida al modello di lavoro isolato C#.

  1. Eseguire questi comandi per installare gli assembly necessari nell'app:

    dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting 
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

  2. Nel file di progetto Program.cs aggiungere questa istruzione using:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Configurare OpenTelemetry in base a se l'avvio del progetto utilizza IHostBuilder o IHostApplicationBuilder. Quest'ultimo è stato introdotto nella versione 2.x dell'estensione del modello di lavoro isolato .NET.

    In program.cs aggiungere questa riga di codice dopo ConfigureFunctionsWebApplication:

    builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

    È possibile esportare in entrambi gli endpoint OpenTelemetry dalla stessa app.

  1. Aggiungere le librerie necessarie all'app. Il modo in cui si aggiungono librerie dipende dal fatto che si distribuisca usando Maven o Kotlin e se si vogliono anche inviare dati ad Application Insights.

    <dependency>
  <groupId>com.microsoft.azure.functions</groupId>
  <artifactId>azure-functions-java-opentelemetry</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
  <version>1.2.0</version>
</dependency>

  2. (Facoltativo) Aggiungere questo codice per creare intervalli personalizzati:

    import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.context.Scope;

Span span = FunctionsOpenTelemetry.startSpan(
        "com.contoso.PaymentFunction",  // tracer name
        "validateCharge",               // span name
        null,                           // parent = current context
        SpanKind.INTERNAL);

try (Scope ignored = span.makeCurrent()) {
    // business logic here
} finally {
    span.end();
}

  1. Installare questi pacchetti npm nel progetto:

    npm install @opentelemetry/api 
npm install @opentelemetry/auto-instrumentations-node 
npm install @azure/monitor-opentelemetry-exporter 
npm install @azure/functions-opentelemetry-instrumentation

  1. Creare un file di codice nel progetto, copiare e incollare il codice seguente in questo nuovo file e salvare il file come src/index.js:

    const { AzureFunctionsInstrumentation } = require('@azure/functions-opentelemetry-instrumentation');
const { AzureMonitorLogExporter, AzureMonitorTraceExporter } = require('@azure/monitor-opentelemetry-exporter');
const { getNodeAutoInstrumentations, getResourceDetectors } = require('@opentelemetry/auto-instrumentations-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { detectResourcesSync } = require('@opentelemetry/resources');
const { LoggerProvider, SimpleLogRecordProcessor } = require('@opentelemetry/sdk-logs');
const { NodeTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-node');

const resource = detectResourcesSync({ detectors: getResourceDetectors() });

const tracerProvider = new NodeTracerProvider({ resource });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new AzureMonitorTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new AzureMonitorLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

  2. Aggiornare il main campo nel file package.json in modo da includere il nuovo src/index.js file. Per esempio:

    "main": "src/{index.js,functions/*.js}"

  1. Creare un file di codice nel progetto, copiare e incollare il codice seguente in questo nuovo file e salvare il file come src/index.ts:

    import { AzureFunctionsInstrumentation } from '@azure/functions-opentelemetry-instrumentation';
import { AzureMonitorLogExporter, AzureMonitorTraceExporter } from '@azure/monitor-opentelemetry-exporter';
import { getNodeAutoInstrumentations, getResourceDetectors } from '@opentelemetry/auto-instrumentations-node';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { detectResourcesSync } from '@opentelemetry/resources';
import { LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { NodeTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';

const resource = detectResourcesSync({ detectors: getResourceDetectors() });

const tracerProvider = new NodeTracerProvider({ resource });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new AzureMonitorTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new AzureMonitorLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

  2. Aggiornare il campo main nel file package.json in modo da includere l'output del nuovo file src/index.ts, che potrebbe essere simile al seguente:

    "main": "dist/src/{index.js,functions/*.js}"

Importante

L'output di OpenTelemetry in Application Insights dal ruolo di lavoro del linguaggio non è attualmente supportato per le app di PowerShell. È invece possibile usare un endpoint di esportazione OTLP. Quando si configura l'host per l'output di OpenTelemetry in Application Insights, i log generati dal processo di lavoro di PowerShell vengono comunque inoltrati, ma il tracciamento distribuito non è attualmente supportato.

Queste istruzioni si applicano solo per un'utilità di esportazione OTLP:

  1. Aggiungere un'impostazione dell'applicazione denominata OTEL_FUNCTIONS_WORKER_ENABLED con il valore True.

  2. Creare una cartella Modulesa livello di app nella radice dell'app ed eseguire il comando seguente:

    Save-Module -Name AzureFunctions.PowerShell.OpenTelemetry.SDK

    Questo comando installa il modulo richiesto AzureFunctions.PowerShell.OpenTelemetry.SDK direttamente nell'app. Non è possibile usare il file requirements.psd1 per installare automaticamente questa dipendenza perché le dipendenze gestite non sono attualmente supportate nell'anteprima del piano a Consumo Flessibile.

  3. Aggiungere questo codice al file profile.ps1:

    Import-Module AzureFunctions.PowerShell.OpenTelemetry.SDK -Force -ErrorAction Stop 
Initialize-FunctionsOpenTelemetry

  1. Assicurarsi che queste librerie si trovino nel file requirements.txt, indipendentemente dalla rimozione del commento o dall'aggiunta di se stessi:

    azure-monitor-opentelemetry

  2. Aggiungere questo codice al file del punto di ingresso principale function_app.py:

    Se è già stata effettuata l'aggiunta di PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true nelle impostazioni dell'applicazione, è possibile ignorare questo passaggio. Per abilitare manualmente la raccolta di Application Insights senza strumentazione automatica, aggiungere questo codice all'app:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Per altre opzioni su come configurare ulteriormente l'SDK, vedere la documentazione sull'utilizzo della distribuzione di Monitoraggio di Azure.

Considerazioni su OpenTelemetry

Quando si esportano i dati usando OpenTelemetry, tenere presenti queste considerazioni.

  • Il portale di Azure supporta le tracce Recent function invocation solo se i dati di telemetria vengono inviati a Monitoraggio di Azure.

  • Quando si configura l'host per l'uso di OpenTelemetry, il portale di Azure non supporta lo streaming dei log.

  • Se si imposta telemetryMode su OpenTelemetry, la configurazione nella sezione logging.applicationInsights di host.json non si applica.

  • Gli intervalli personalizzati includono automaticamente tutti gli attributi delle risorse e usano gli strumenti di esportazione configurati nell'app.

  • Quando l'app viene eseguita all'esterno di Azure, incluso durante lo sviluppo locale, il rilevatore di risorse imposta l'attributo service.name su java-function-app per impostazione predefinita.

  • Usare questi flag JVM (Java Virtual Machine) per disattivare i dati di telemetria durante l'esecuzione in locale durante gli unit test:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • Non è necessario registrare manualmente il middleware; il ruolo di lavoro Java individua automaticamente OpenTelemetryInvocationMiddleware.

Risoluzione dei problemi

Quando si esportano i dati usando OpenTelemetry, tenere presenti questi problemi e soluzioni comuni.

Filtro dei log

Per configurare correttamente il filtro dei log nell'app per le funzioni, è necessario comprendere la differenza tra il processo host e il processo di lavoro.

Il processo host è il runtime di Funzioni di Azure che gestisce i trigger, il ridimensionamento e genera dati di telemetria a livello di sistema, ad esempio i log di inizializzazione, le tracce delle richieste e le informazioni sull'integrità del runtime.

Il processo di lavoro è specifico del linguaggio, esegue il codice della funzione e produce log applicazioni e dati di telemetria in modo indipendente.

Importante

I filtri definiti in host.json si applicano solo ai log generati dal processo host. È necessario usare le impostazioni OpenTelemetry specifiche della lingua per filtrare i log dal processo di lavoro.

Esempio: Filtrare i log host per tutti i provider in host.json

Usare questo approccio per impostare un livello di log globale in tutti i provider gestiti dall'host:

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry",
  "logging": {
    "logLevel": {
      "default": "Warning"
    }
  }
}

Esempio: Filtrare i log solo per il provider di logger OpenTelemetry

Usare questo approccio per impostare come destinazione solo il provider di logger OpenTelemetry lasciando invariati altri provider, ad esempio la registrazione della console o dei file:

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry",
  "logging": {
    "OpenTelemetry": {
      "logLevel": {
        "default": "Warning"
      }
    }
  }
}

Log della console

L'host di Funzioni acquisisce automaticamente qualsiasi elemento scritto in stdout o stderr e lo inoltra alla pipeline di telemetria. Se si utilizza anche un ConsoleExporter o si scrive direttamente nel codice nella console, possono verificarsi log duplicati nei dati di telemetria.

Annotazioni

Per evitare voci di telemetria duplicate, non aggiungere ConsoleExporter o scrivere nella console nel codice di produzione.

Autenticazione di Microsoft Entra

Quando si usa l'autenticazione di Microsoft Entra con OpenTelemetry, è necessario configurare l'autenticazione separatamente sia per il processo host che per il processo di lavoro.

Per configurare l'autenticazione per il processo host, vedere Richiedere l'autenticazione di Microsoft Entra.

Per configurare l'autenticazione per il processo di lavoro, vedere Abilitare l'autenticazione di Microsoft Entra.

Supporto degli attributi delle risorse

Il supporto degli attributi delle risorse in Monitoraggio di Azure è attualmente in anteprima. Per abilitare questa funzionalità, impostare la OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS variabile di ambiente su true. Questa impostazione inserisce gli attributi delle risorse nella tabella delle metriche personalizzate.

Dati di telemetria delle richieste duplicati

Il processo host genera automaticamente i dati di telemetria delle richieste. Se il processo di lavoro viene instrumentato anche con librerie di rilevamento delle richieste (ad esempio, AspNetCoreInstrumentation in .NET), la stessa richiesta viene segnalata due volte.

Annotazioni

Poiché la distribuzione di Monitoraggio di Azure include in genere AspNetCoreInstrumentation in .NET e strumentazione simile in altri linguaggi, evitare di usare la distribuzione di Monitoraggio di Azure nel processo di lavoro per evitare dati di telemetria duplicati.

Ambiti di registrazione non inclusi

Per impostazione predefinita, il processo di lavoro non include gli ambiti nei relativi log. Per abilitare gli ambiti, è necessario configurare esplicitamente questa impostazione nel worker. L'esempio seguente illustra come abilitare gli ambiti in .NET Isolated:

builder.Logging.AddOpenTelemetry(b => b.IncludeScopes = true);

Dati di telemetria delle richieste mancanti

Trigger, ad esempio HTTP, Service Bus ed Event Hubs, dipendono dalla propagazione del contesto per il tracciamento distribuito. Con il campionamento basato sui genitori come comportamento predefinito, i dati di telemetria delle richieste non vengono generati quando la richiesta o il messaggio in ingresso non viene campionato.

OperationId duplicato

In Funzioni di Azure, l'oggetto OperationId usato per correlare i dati di telemetria proviene direttamente dal traceparent valore nella richiesta o nel messaggio in ingresso. Se più chiamate riutilizzano lo stesso traceparent valore, ottengono tutti lo stesso OperationId.

Configurare OpenTelemetry con le variabili di ambiente

È possibile configurare il comportamento di OpenTelemetry usando le variabili di ambiente standard. Queste variabili offrono un modo coerente per controllare il comportamento tra linguaggi e runtime diversi. È possibile modificare le strategie di campionamento, le impostazioni di esportazione e gli attributi delle risorse. Per altre informazioni sulle variabili di ambiente supportate, vedere la documentazione di OpenTelemetry.

Usare la diagnostica per risolvere i problemi di monitoraggio

La diagnostica di Funzioni di Azure nel portale di Azure è una risorsa utile per rilevare e diagnosticare potenziali problemi correlati al monitoraggio.

Per accedere alla diagnostica nell'app:

  1. Nel portale di Azure, vai alla risorsa della tua app delle funzioni.

  2. Nel riquadro sinistro, selezionare Diagnosticare e risolvere i problemi e cercare il flusso di lavoro Telemetria mancante in app per le funzioni per Application Insights o OpenTelemetry.

  3. Selezionare questo flusso di lavoro, scegliere il metodo di inserimento e selezionare Avanti.

  4. Esaminare le linee guida e le raccomandazioni fornite dallo strumento di risoluzione dei problemi.

Passaggi successivi

Altre informazioni su OpenTelemetry e il monitoraggio di Funzioni di Azure:

  • Last updated on