Dela via

Använda OpenTelemetry med Azure Functions

Den här artikeln visar hur du konfigurerar funktionsappen för att exportera logg- och spårningsdata i ett OpenTelemetry-format. Azure Functions genererar telemetridata om dina funktionskörningar från både Functions-värdprocessen och den språkspecifika arbetsprocess där funktionskoden körs. Som standard skickas dessa telemetridata till Application Insights med hjälp av Application Insights SDK. Du kan dock välja att exportera dessa data med hjälp av OpenTelemetry-semantik. Du kan fortfarande använda ett OpenTelemetry-format för att skicka dina data till Application Insights, men du kan nu även exportera samma data till andra OpenTelemetry-kompatibla slutpunkter.

Du kan få dessa fördelar genom att aktivera OpenTelemetry i funktionsappen:

  • Korrelerar data mellan spårningar och loggar som genereras både på värden och i programkoden.
  • Möjliggör konsekvent, standardbaserad generering av exportbara telemetridata.
  • Integrerar med andra leverantörer som kan använda OpenTelemetry-kompatibla data.

Tänk på följande när du använder den här artikeln:

  • Testa OpenTelemetry-handledningen, som är utformad för att hjälpa dig att komma igång snabbt med OpenTelemetry och Azure Functions. Den här artikeln använder Azure Developer CLI (azd) för att skapa och distribuera en funktionsapp som använder OpenTelemetry-integrering för distribuerad spårning.

  • Eftersom den här artikeln riktar sig till valfritt utvecklingsspråk bör du komma ihåg att välja rätt språk överst i artikeln.

  • OpenTelemetry är aktiverat på funktionsappsnivå, både i värdkonfigurationen (host.json) och i kodprojektet. Functions ger också en klientoptimerad upplevelse för att exportera OpenTelemetry-data från din funktionskod som körs i en språkspecifik arbetsprocess.

Aktivera OpenTelemetry i Functions-värden

När du aktiverar OpenTelemetry-utdata i funktionsappens host.json-fil exporterar värddatorn OpenTelemetry-utdata oavsett vilken språkstack som används av appen.

Om du vill aktivera OpenTelemetry-utdata från Functions-värden uppdaterar du filen host.json i kodprojektet för att lägga till ett "telemetryMode": "OpenTelemetry" element i rotsamlingen. Med OpenTelemetry aktiverat kan din host.json-fil se ut så här:

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

Konfigurera programinställningar

När du aktiverar OpenTelemetry i host.json filen avgör appens miljövariabler slutpunkterna för att skicka data baserat på vilka Programinställningar som stöds av OpenTelemetry.

Skapa specifika programinställningar i funktionsappen baserat på utdatamålet OpenTelemetry. När du anger anslutningsinställningar för både Application Insights och en exportör av OpenTelemetry Protocol (OTLP) skickas OpenTelemetry-data till båda slutpunkterna.

APPLICATIONINSIGHTS_CONNECTION_STRING: anslutningssträngen för en Application Insights-arbetsyta. När den här inställningen finns skickas OpenTelemetry-data till den arbetsytan. Använd samma inställning för att ansluta till Application Insights utan OpenTelemetry aktiverat. Om din app inte redan har den här inställningen kan du behöva aktivera Application Insights-integrering.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: inställd på true så att Functions-värden tillåter Att Java-arbetsprocessen strömmar OpenTelemetry-loggar direkt, vilket förhindrar duplicerade poster på värdnivå.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: inställt på true så att Functions-värden tillåter Python-arbetsprocessen att strömma OpenTelemetry-loggar direkt, vilket förhindrar duplicerade poster på värdnivå.

Aktivera OpenTelemetry i din app

När du har konfigurerat Functions-värden att använda OpenTelemetry uppdaterar du programkoden för att mata ut OpenTelemetry-data. När du aktiverar OpenTelemetry i både värden och din programkod får du bättre korrelation mellan spår och loggar som Functions-värdprocessen och språkarbetarprocessen genererar.

Hur du instrumentera ditt program för att använda OpenTelemetry beror på målslutpunkten för OpenTelemetry:

Exempel i den här artikeln förutsätter att din app använder IHostApplicationBuilder, som är tillgänglig i version 2.x och senare version av Microsoft.Azure.Functions.Worker. Mer information finns i Version 2.x i modellguiden för isolerad C#-arbetsmodell.

  1. Kör dessa kommandon för att installera de nödvändiga sammansättningarna i din app:

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

  2. Lägg till den här using instruktionen i din Program.cs projektfil:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Konfigurera OpenTelemetry baserat på om projektets start använder IHostBuilder eller IHostApplicationBuilder. Det senare introducerades i v2.x i .NET-tillägget för isolerade arbetsmodeller.

    I program.cs lägger du till den här kodraden efter ConfigureFunctionsWebApplication:

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

    Du kan exportera till båda OpenTelemetry-slutpunkterna från samma app.

  1. Lägg till de bibliotek som krävs i din app. Hur du lägger till bibliotek beror på om du distribuerar med Maven eller Kotlin och om du även vill skicka data till 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. (Valfritt) Lägg till den här koden för att skapa anpassade intervall:

    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. Installera dessa npm-paket i projektet:

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

  1. Skapa en kodfil i projektet, kopiera och klistra in följande kod i den nya filen och spara filen som 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. Uppdatera fältet main i package.json-filen så att det innehåller den nya src/index.js filen. Till exempel:

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

  1. Skapa en kodfil i projektet, kopiera och klistra in följande kod i den nya filen och spara filen som 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. Uppdatera fältet main i package.json-filen så att det innehåller utdata från den nya src/index.ts filen, vilket kan se ut så här:

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

Viktigt!

OpenTelemetry-utdata till Application Insights från språkarbetaren stöds för närvarande inte för PowerShell-appar. Du kanske i stället vill använda en SLUTpunkt för OTLP-exportören. När du konfigurerar din värd för OpenTelemetry-utdata till Application Insights, vidarebefordras fortfarande de loggar som genereras av PowerShell-arbetsprocessen, men för närvarande stöds inte distribuerad spårning.

Dessa instruktioner gäller endast för en OTLP-exportör:

  1. Lägg till en programinställning med namnet OTEL_FUNCTIONS_WORKER_ENABLED med värdet True.

  2. Skapa en Modules på appnivå i appens rot och kör följande kommando:

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

    Det här kommandot installerar den nödvändiga AzureFunctions.PowerShell.OpenTelemetry.SDK modulen direkt i din app. Du kan inte använda requirements.psd1 filen för att installera det här beroendet automatiskt eftersom hanterade beroenden för närvarande inte stöds i förhandsversionen av Flex Consumption-planen .

  3. Lägg till den här koden i filen profile.ps1:

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

  1. Kontrollera att de här biblioteken finns i filen requirements.txt , oavsett om du vill ta bort kommentarer eller lägga till dig själv:

    azure-monitor-opentelemetry

  2. Lägg till den här koden i huvudinmatningspunktens function_app.py fil:

    Om du redan har lagt till PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true i programinställningarna kan du hoppa över det här steget. Om du vill aktivera Application Insights-samlingen manuellt utan automatisk instrumentering lägger du till den här koden i din app:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Mer information om hur du konfigurerar SDK finns i dokumentationen om Distribution av distribution i Azure Monitor .

Överväganden för OpenTelemetry

När du exporterar dina data med hjälp av OpenTelemetry bör du tänka på dessa överväganden.

  • Azure-portalen stöder Recent function invocation endast spårningar om telemetrin skickas till Azure Monitor.

  • Vid konfigurering av värden för att använda OpenTelemetry stöder inte Azure-portalen loggströmning.

  • Om du anger telemetryMode till OpenTelemetrygäller inte konfigurationen logging.applicationInsights i avsnittet i host.json.

  • Anpassade intervall inkluderar automatiskt alla resursattribut och använder de exportörer som konfigurerats i din app.

  • När din app körs utanför Azure, inklusive under lokal utveckling, anger resursdetektorn service.name attributet till java-function-app som standard.

  • Använd dessa JVM-flaggor (Java Virtual Machine) för att tysta telemetri när du kör lokalt under enhetstester:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • Du behöver inte registrera mellanprogram manuellt; Java Worker upptäcker OpenTelemetryInvocationMiddleware automatiskt.

Felsökning

När du exporterar dina data med hjälp av OpenTelemetry bör du ha dessa vanliga problem och lösningar i åtanke.

Loggfiltrering

Om du vill konfigurera loggfiltrering i funktionsappen korrekt måste du förstå skillnaden mellan värdprocessen och arbetsprocessen.

Värdprocessen är Azure Functions-körningen som hanterar utlösare, skalning och genererar telemetri på systemnivå, till exempel initieringsloggar, spårning av begäranden och hälsoinformation för körning.

Arbetsprocessen är språkspecifik, kör funktionskoden och skapar programloggar och telemetri oberoende av varandra.

Viktigt!

Filter som definierats i host.json gäller endast för loggar som genereras av värdprocessen. Du måste använda språkspecifika OpenTelemetry-inställningar för att filtrera loggar från arbetsprocessen.

Exempel: Filtrera värdloggar för alla leverantörer i host.json

Använd den här metoden för att ange en global loggnivå för alla leverantörer som hanteras av värden:

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

Exempel: Filtrera loggar endast för OpenTelemetry-loggningsprovidern

Använd den här metoden för att endast rikta in sig på OpenTelemetry-loggningsprovidern medan andra leverantörer (till exempel konsol- eller filloggning) inte påverkas:

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

Konsolloggning

Värdplattformen för Functions fångar automatiskt upp allt som skrivs till stdout eller stderr och vidarebefordrar det till telemetripipelinen. Om du också använder en ConsoleExporter eller skriver direkt till konsolen i din kod kan dubblerade loggar uppstå i dina telemetridata.

Anmärkning

Lägg inte till ConsoleExporter eller skriv till konsolen i produktionskoden för att undvika dubbletter av telemetriposter.

Microsoft Entra-autentisering

När du använder Microsoft Entra-autentisering med OpenTelemetry måste du konfigurera autentisering separat för både värdprocessen och arbetsprocessen.

Information om hur du konfigurerar autentisering för värdprocessen finns i Kräv Microsoft Entra-autentisering.

Information om hur du konfigurerar autentisering för arbetsprocessen finns i Aktivera Microsoft Entra-autentisering.

Stöd för resursattribut

Stöd för resursattribut i Azure Monitor är för närvarande i förhandsversion. Om du vill aktivera den här funktionen anger du OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS miljövariabeln till true. Den här inställningen matar in resursattribut i tabellen med anpassade mått.

Telemetri för duplicerad begäran

Värdprocessen genererar automatiskt telemetri för begäran. Om arbetsprocessen också instrumenteras med bibliotek för spårning av begäranden (till exempel AspNetCoreInstrumentation i .NET) rapporteras samma begäran två gånger.

Anmärkning

Eftersom Azure Monitor Distro vanligtvis innehåller AspNetCoreInstrumentation i .NET och liknande instrumentation på andra språk bör du undvika att använda Azure Monitor-distributionen i arbetsprocessen för att förhindra duplicerad telemetri.

Loggningsomfång ingår inte

Som standard inkluderar inte arbetsprocessen omfång i sina loggar. Om du vill aktivera omfång måste du konfigurera den här inställningen explicit i arbetaren. I följande exempel visas hur du aktiverar omfång i .NET Isolerad:

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

Telemetri för begäran saknas

Utlösare som HTTP, Service Bus och Event Hubs är beroende av kontextspridning för distribuerad spårning. Med överordnad sampling som standardbeteende genereras inte telemetri för begäran när den inkommande begäran eller meddelandet inte samplas.

Duplicerat OperationId

I Azure Functions kommer den OperationId som används för korrelering av telemetri direkt från traceparent värdet i den inkommande begäran eller meddelandet. Om flera anrop återanvänder samma traceparent värde får alla samma OperationId.

Konfigurera OpenTelemetry med miljövariabler

Du kan konfigurera OpenTelemetry-beteendet med hjälp av dess standardmiljövariabler. De här variablerna är ett konsekvent sätt att styra beteendet mellan olika språk och körningsmiljöer. Du kan justera samplingsstrategier, exportinställningar och resursattribut. Mer information om miljövariabler som stöds finns i dokumentationen om OpenTelemetry.

Använda diagnostik för att felsöka övervakningsproblem

Azure Functions-diagnostik i Azure-portalen är en användbar resurs för att identifiera och diagnostisera potentiella övervakningsrelaterade problem.

Så här får du åtkomst till diagnostik i din app:

  1. Gå till funktionsappresursen i Azure-portalen.

  2. I den vänstra rutan väljer du Diagnostisera och lösa problem och söker efter funktionsappen som saknar telemetriarbetsflödet Application Insights eller OpenTelemetry .

  3. Välj det här arbetsflödet, välj din inmatningsmetod och välj Nästa.

  4. Granska riktlinjerna och eventuella rekommendationer som tillhandahålls av felsökaren.

Nästa steg

Läs mer om OpenTelemetry och övervakning av Azure Functions:

  • Last updated on