Delen via

OpenTelemetry gebruiken met Azure Functions

In dit artikel leest u hoe u uw functie-app configureert voor het exporteren van logboek- en traceringsgegevens in een OpenTelemetry-indeling. Azure Functions genereert telemetriegegevens over de uitvoering van uw functie vanuit zowel het Functions-hostproces als het taalspecifieke werkproces waarin uw functiecode wordt uitgevoerd. Deze telemetriegegevens worden standaard naar Application Insights verzonden met behulp van de Application Insights-SDK. U kunt er echter voor kiezen om deze gegevens te exporteren met behulp van openTelemetry-semantiek. Hoewel u nog steeds een OpenTelemetry-indeling kunt gebruiken om uw gegevens naar Application Insights te verzenden, kunt u nu ook dezelfde gegevens exporteren naar elk ander openTelemetry-compatibel eindpunt.

U kunt deze voordelen verkrijgen door OpenTelemetry in te schakelen in uw functie-app:

  • Correleert gegevens over traceringen en logboeken die zowel op de host als in uw toepassingscode worden gegenereerd.
  • Maakt consistente, op standaarden gebaseerde generatie van exportbare telemetriegegevens mogelijk.
  • Integreert met andere providers die openTelemetry-compatibele gegevens kunnen gebruiken.

Houd rekening met deze overwegingen bij het gebruik van dit artikel:

  • Probeer de zelfstudie OpenTelemetry, die is ontworpen om snel aan de slag te gaan met OpenTelemetry en Azure Functions. In dit artikel wordt de Azure Developer CLI (azd) gebruikt om een functie-app te maken en te implementeren die gebruikmaakt van OpenTelemetry-integratie voor gedistribueerde tracering.

  • Omdat dit artikel is gericht op uw ontwikkeltaal van keuze, moet u de juiste taal bovenaan het artikel kiezen.

  • OpenTelemetry is ingeschakeld op het niveau van de functie-app, zowel in de hostconfiguratie (host.json) als in uw codeproject. Functions biedt ook een door de client geoptimaliseerde ervaring voor het exporteren van OpenTelemetry-gegevens uit uw functiecode die wordt uitgevoerd in een taalspecifiek werkproces.

OpenTelemetry inschakelen in de Functions-host

Wanneer u OpenTelemetry-uitvoer inschakelt in het bestand van host.json de functie-app, exporteert de host OpenTelemetry-uitvoer, ongeacht de taalstack die door uw app wordt gebruikt.

Als u OpenTelemetry-uitvoer van de Functions-host wilt inschakelen, werkt u het host.json-bestand in uw codeproject bij om een "telemetryMode": "OpenTelemetry" element toe te voegen aan de hoofdverzameling. Als OpenTelemetry is ingeschakeld, ziet uw host.json bestand er als volgt uit:

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

Toepassingsinstellingen configureren

Wanneer u OpenTelemetry inschakelt in het host.json bestand, bepalen de omgevingsvariabelen van de app de eindpunten voor het verzenden van gegevens op basis waarvan door OpenTelemetry ondersteunde toepassingsinstellingen beschikbaar zijn.

Maak specifieke toepassingsinstellingen in uw functie-app op basis van de doeluitvoer van OpenTelemetry. Wanneer u verbindingsinstellingen opgeeft voor zowel Application Insights als een OTLP-exporteur (OpenTelemetry Protocol), worden OpenTelemetry-gegevens naar beide eindpunten verzonden.

APPLICATIONINSIGHTS_CONNECTION_STRING: de verbindingsreeks voor een Application Insights-werkruimte. Wanneer deze instelling bestaat, worden OpenTelemetry-gegevens naar die werkruimte verzonden. Gebruik dezelfde instelling om verbinding te maken met Application Insights zonder OpenTelemetry ingeschakeld. Als uw app deze instelling nog niet heeft, moet u mogelijk Application Insights-integratie inschakelen.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: zo true ingesteld dat de Functions-host het Java-werkproces toestaat om OpenTelemetry-logboeken rechtstreeks te streamen, waardoor dubbele vermeldingen op hostniveau worden voorkomen.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: zo true ingesteld dat de Functions-host het Python-werkproces toestaat om OpenTelemetry-logboeken rechtstreeks te streamen, waardoor dubbele vermeldingen op hostniveau worden voorkomen.

OpenTelemetry inschakelen in uw app

Nadat u de Functions-host hebt geconfigureerd voor het gebruik van OpenTelemetry, werkt u de toepassingscode bij om OpenTelemetry-gegevens uit te voeren. Wanneer u OpenTelemetry inschakelt in zowel de host als uw toepassingscode, krijgt u een betere correlatie tussen traceringen en logboeken die het Functions-hostproces en het taalwerkproces verzenden.

Hoe u uw toepassing instrumenteren voor het gebruik van OpenTelemetry, is afhankelijk van uw doeleindpunt voor OpenTelemetry:

In de voorbeelden in dit artikel wordt ervan uitgegaan dat uw app IHostApplicationBuilder gebruikt, wat beschikbaar is in versie 2.x en latere versies van Microsoft.Azure.Functions.Worker. Zie versie 2.x in de handleiding voor het geïsoleerde werkrolmodel van C# voor meer informatie.

  1. Voer deze opdrachten uit om de vereiste assembly's in uw app te installeren:

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

  2. Voeg in het Program.cs projectbestand deze using instructie toe:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Configureer OpenTelemetry op basis van of de opstart van uw project IHostBuilder of IHostApplicationBuilder gebruikt. De laatste is geïntroduceerd in v2.x van de extensie .NET-geïsoleerde werkrolmodellen.

    Voeg in program.cs deze coderegel toe na ConfigureFunctionsWebApplication:

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

    U kunt vanuit dezelfde app exporteren naar beide OpenTelemetry-eindpunten.

  1. Voeg de vereiste bibliotheken toe aan uw app. De manier waarop u bibliotheken toevoegt, is afhankelijk van of u implementeert met Behulp van Maven of Kotlin en of u ook gegevens naar Application Insights wilt verzenden.

    <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. (Optioneel) Voeg deze code toe om aangepaste spans te maken:

    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. Installeer deze NPM-pakketten in uw project:

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

  1. Maak een codebestand in uw project, kopieer en plak de volgende code in dit nieuwe bestand en sla het bestand op als 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. Werk het veld in het main package.json-bestand bij om het nieuwe src/index.js bestand op te nemen. Voorbeeld:

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

  1. Maak een codebestand in uw project, kopieer en plak de volgende code in dit nieuwe bestand en sla het bestand op als 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. Werk het veld in het main package.json-bestand bij om de uitvoer van dit nieuwe src/index.ts bestand op te nemen. Dit kan er als volgt uitzien:

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

Belangrijk

OpenTelemetry-uitvoer naar Application Insights van de taalwerker wordt momenteel niet ondersteund voor PowerShell-apps. U kunt in plaats daarvan een OTLP-exporteur-eindpunt gebruiken. Wanneer u uw host configureert voor OpenTelemetry-uitvoer naar Application Insights, worden de logboeken die door het PowerShell-werkproces worden gegenereerd, nog steeds doorgestuurd, maar gedistribueerde tracering wordt op dit moment niet ondersteund.

Deze instructies zijn alleen van toepassing op een OTLP-exporteur:

  1. Voeg een toepassingsinstelling toe met de OTEL_FUNCTIONS_WORKER_ENABLED naam met de waarde van True.

  2. Maak een Modules op app-niveau in de hoofdmap van uw app en voer de volgende opdracht uit:

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

    Met deze opdracht wordt de vereiste AzureFunctions.PowerShell.OpenTelemetry.SDK module rechtstreeks in uw app geïnstalleerd. U kunt het requirements.psd1 bestand niet gebruiken om deze afhankelijkheid automatisch te installeren, omdat beheerde afhankelijkheden momenteel niet worden ondersteund in de preview van het Flex Consumption-abonnement .

  3. Voeg deze code toe aan uw profiel.ps1-bestand:

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

  1. Zorg ervoor dat deze bibliotheken zich in uw requirements.txt bestand bevinden, ongeacht of u geen opmerkingen maakt of uzelf toevoegt:

    azure-monitor-opentelemetry

  2. Voeg deze code toe aan het function_app.py hoofdinvoerpuntbestand:

    Als u al aan uw toepassingsinstellingen hebt toegevoegd PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true , kunt u deze stap overslaan. Als u Application Insights-verzameling handmatig wilt inschakelen zonder automatische instrumentatie, voegt u deze code toe aan uw app:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Raadpleeg de documentatie over het gebruik van Azure Monitor Distro voor opties voor het verder configureren van de SDK.

Overwegingen voor OpenTelemetry

Houd rekening met deze overwegingen wanneer u uw gegevens exporteert met behulp van OpenTelemetry.

  • Azure Portal ondersteunt Recent function invocation alleen traceringen als de telemetrie naar Azure Monitor wordt verzonden.

  • Wanneer u de host configureert voor het gebruik van OpenTelemetry, biedt Azure Portal geen ondersteuning voor logboekstreaming.

  • Als u deze optie instelt telemetryModeOpenTelemetry, is de configuratie in de logging.applicationInsights sectie van host.json niet van toepassing.

  • Aangepaste reeksen bevatten automatisch alle resourcekenmerken en gebruiken de exporteurs die in uw app zijn geconfigureerd.

  • Wanneer uw app buiten Azure wordt uitgevoerd, inclusief tijdens lokale ontwikkeling, stelt de resourcedetector het service.name kenmerk java-function-app standaard in.

  • Gebruik deze JVM-vlaggen (Java Virtual Machine) om telemetrie stil te leggen bij lokaal uitvoeren tijdens eenheidstests:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • U hoeft middleware niet handmatig te registreren; de Java-worker detecteert OpenTelemetryInvocationMiddleware automatisch.

Probleemoplossingsproces

Wanneer u uw gegevens exporteert met behulp van OpenTelemetry, moet u rekening houden met deze veelvoorkomende problemen en oplossingen.

Logboekfiltering

Als u logboekfiltering correct wilt configureren in uw functie-app, moet u het verschil tussen het hostproces en het werkproces begrijpen.

Het hostproces is de Azure Functions-runtime waarmee triggers, schaalaanpassing en telemetrie op systeemniveau worden beheerd, zoals initialisatielogboeken, aanvraagtraceringen en runtimestatusgegevens.

Het werkproces is taalspecifiek, voert uw functiecode uit en produceert toepassingslogboeken en telemetrie onafhankelijk van elkaar.

Belangrijk

Filters die zijn gedefinieerd in host.json zijn alleen van toepassing op logboeken die door het hostproces worden gegenereerd. U moet taalspecifieke OpenTelemetry-instellingen gebruiken om logboeken uit het werkproces te filteren.

Voorbeeld: Hostlogboeken filteren voor alle providers in host.json

Gebruik deze methode om een globaal logboekniveau in te stellen voor alle providers die worden beheerd door de host:

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

Voorbeeld: Filter de logs alleen voor de OpenTelemetry-loggerprovider

Gebruik deze methode om alleen de OpenTelemetry-loggerprovider te richten terwijl andere providers (zoals console- of bestandslogging) niet worden beïnvloed:

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

Consolelogboekregistratie

De Functions-host legt automatisch alles vast dat naar stdout of stderr wordt geschreven en stuurt deze door naar de telemetriepijplijn. Als u ook een ConsoleExporter gebruikt of rechtstreeks naar de console schrijft in uw code, kunnen dubbele logboeken voorkomen in uw telemetriegegevens.

Opmerking

Om dubbele telemetriegegevens te voorkomen, voeg ConsoleExporter niet toe en schrijf niet naar de console in de productiecode.

Microsoft Entra-authenticatie

Wanneer u Microsoft Entra-verificatie met OpenTelemetry gebruikt, moet u verificatie afzonderlijk configureren voor zowel het hostproces als het werkproces.

Zie Microsoft Entra-verificatie vereisen om verificatie voor het hostproces te configureren.

Zie Microsoft Entra-verificatie inschakelen om verificatie voor het werkproces te configureren.

Ondersteuning voor resourcekenmerken

Ondersteuning voor resourcekenmerken in Azure Monitor is momenteel beschikbaar als preview-versie. Als u deze functie wilt inschakelen, stelt u de OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS omgevingsvariabele in op true. Met deze instelling worden resourcekenmerken opgenomen in de aangepaste tabel met metrische gegevens.

Dubbele verzoektelemetrie

Het hostproces verzendt automatisch aanvraagtelemetrie. Als het werkproces ook wordt geïnstrumenteerd met bibliotheken voor het bijhouden van aanvragen (bijvoorbeeld AspNetCoreInstrumentation in .NET), wordt dezelfde aanvraag tweemaal gerapporteerd.

Opmerking

Aangezien de Azure Monitor-distributie doorgaans AspNetCoreInstrumentation in .NET en vergelijkbare instrumentatie in andere talen bevat, vermijdt u het gebruik van de Azure Monitor-distributie in het werkproces om dubbele telemetrie te voorkomen.

Logboekregistratiebereiken zijn niet opgenomen

Het workerproces bevat standaard geen "scopes" in de logboeken. Om scopes in te schakelen, moet u deze instelling expliciet configureren in de worker. In het volgende voorbeeld ziet u hoe u scopes activeert in .NET Isolated.

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

Ontbrekende verzoektelemetrie

Triggers zoals HTTP, Service Bus en Event Hubs zijn afhankelijk van contextdoorgifte voor gedistribueerde tracering. Met oudergebaseerde steekproeven als standaardgedrag wordt er geen aanvraagtelemetrie gegenereerd wanneer de binnenkomende aanvraag of het bericht niet wordt gesampled.

Dubbele OperationId

In Azure Functions komt de voor het correleren van telemetrie gebruikte waarde rechtstreeks van de traceparent-waarde in het binnenkomende verzoek of bericht. Als meerdere aanroepen dezelfde traceparent waarde opnieuw gebruiken, krijgen ze allemaal dezelfde OperationIdwaarde.

OpenTelemetry configureren met omgevingsvariabelen

U kunt het gedrag van OpenTelemetry configureren met behulp van de standaardomgevingsvariabelen. Deze variabelen bieden een consistente manier om gedrag in verschillende talen en runtimes te beheren. U kunt samplingstrategieën, instellingen voor exporteurs en resourcekenmerken aanpassen. Zie de OpenTelemetry-documentatie voor meer informatie over ondersteunde omgevingsvariabelen.

Diagnostische gegevens gebruiken om bewakingsproblemen op te lossen

Diagnostische gegevens van Azure Functions in Azure Portal zijn een nuttige resource voor het detecteren en diagnosticeren van mogelijke problemen met betrekking tot bewaking.

Ga als volgende te werk om toegang te krijgen tot diagnostische gegevens in uw app:

  1. Ga in Azure Portal naar de resource van uw functie-app.

  2. Selecteer in het linkerdeelvenster Diagnose en los problemen op en zoek naar de ontbrekende telemetriewerkstroom van Application Insights of OpenTelemetry voor de functie-app .

  3. Selecteer deze werkstroom, kies uw opnamemethode en selecteer Volgende.

  4. Bekijk de richtlijnen en eventuele aanbevelingen van de probleemoplosser.

Volgende stappen

Meer informatie over OpenTelemetry en het bewaken van Azure Functions:

  • Last updated on