Sdílet prostřednictvím

Použití OpenTelemetry se službou Azure Functions

V tomto článku se dozvíte, jak nakonfigurovat aplikaci funkcí pro export dat protokolu a trasování ve formátu OpenTelemetry. Azure Functions generuje telemetrická data na spouštění funkcí z hostitelského procesu Functions i pracovního procesu specifického pro jazyk, ve kterém běží kód funkce. Ve výchozím nastavení se tato telemetrická data odesílají do Application Insights pomocí sady Application Insights SDK. Tato data však můžete exportovat pomocí sémantiky OpenTelemetry. I když stále můžete k odesílání dat do Application Insights použít formát OpenTelemetry, můžete teď také exportovat stejná data do jakéhokoli jiného koncového bodu kompatibilního s OpenTelemetry.

Tyto výhody můžete získat povolením OpenTelemetry ve vaší aplikaci funkcí:

  • Koreluje data napříč trasováními a protokoly generovanými na hostiteli i v kódu vaší aplikace.
  • Umožňuje konzistentní generování exportovatelných telemetrických dat založených na standardech.
  • Integruje se s dalšími poskytovateli, kteří můžou využívat data kompatibilní s OpenTelemetry.

Při používání tohoto článku mějte na paměti tyto aspekty:

  • Vyzkoušejte kurz OpenTelemetry, který je navržený tak, aby vám pomohl rychle začít s OpenTelemetry a Azure Functions. Tento článek používá Azure Developer CLI (azd) k vytvoření a nasazení aplikace funkcí, která používá integraci OpenTelemetry pro distribuované trasování.

  • Vzhledem k tomu, že se tento článek zaměřuje na zvolený vývojový jazyk, nezapomeňte zvolit správný jazyk v horní části článku.

  • OpenTelemetry je povolená na úrovni aplikace funkcí v konfiguraci hostitele (host.json) i v projektu kódu. Funkce také poskytují prostředí optimalizované pro klienta pro export dat OpenTelemetry z kódu funkce, který běží v pracovním procesu specifickém pro jazyk.

Povolení OpenTelemetry v hostiteli Functions

Když povolíte výstup OpenTelemetry v souboru funkční aplikace host.json, hostitel exportuje výstup OpenTelemetry bez ohledu na jazykový zásobník používaný vaší aplikací.

Pokud chcete povolit výstup OpenTelemetry z hostitele Functions, aktualizujte soubor host.json v projektu kódu a přidejte "telemetryMode": "OpenTelemetry" do kořenové kolekce prvek. Když je povolený OpenTelemetry, může váš soubor host.json vypadat takto:

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

Konfigurace nastavení aplikace

Když v host.json souboru povolíte OpenTelemetry, proměnné prostředí aplikace určují koncové body pro odesílání dat na základě toho, jaká nastavení aplikace podporuje OpenTelemetry.

Vytvořte v aplikaci funkcí konkrétní nastavení aplikace na základě cíle výstupu OpenTelemetry. Když zadáte nastavení připojení pro Application Insights a exportér protokolu OpenTelemetry (OTLP), data OpenTelemetry se odesílají do obou koncových bodů.

APPLICATIONINSIGHTS_CONNECTION_STRING: připojovací řetězec pro pracovní prostor Application Insights. Pokud toto nastavení existuje, data OpenTelemetry se odesílají do tohoto pracovního prostoru. Stejné nastavení použijte pro připojení k Application Insights bez povolení OpenTelemetry. Pokud vaše aplikace toto nastavení ještě nemá, budete možná muset povolit integraci Application Insights.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: nastavte na hodnotu true tak, aby hostitel functions umožnil pracovnímu procesu Javy přímo streamovat protokoly OpenTelemetry, což brání duplicitním položkám na úrovni hostitele.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: nastavte na hodnotu true tak, aby hostitel functions umožnil pracovnímu procesu Pythonu přímo streamovat protokoly OpenTelemetry, což brání duplicitním položkám na úrovni hostitele.

Povolení OpenTelemetry v aplikaci

Jakmile nakonfigurujete hostitele Functions tak, aby používal OpenTelemetry, aktualizujte kód aplikace na výstup dat OpenTelemetry. Když v hostiteli i kódu aplikace povolíte OpenTelemetry, získáte lepší korelaci mezi trasováními a protokoly, které hostitelský proces Functions a váš jazykový pracovní proces vygenerují.

Způsob instrumentace aplikace pro použití OpenTelemetry závisí na cílovém koncovém bodu OpenTelemetry:

Příklady v tomto článku předpokládají, že vaše aplikace používá IHostApplicationBuilder, která je k dispozici ve verzi 2.x a novější verzi Microsoft.Azure.Functions.Worker. Další informace najdete ve verzi 2.x v průvodci izolovaným pracovním modelem jazyka C#.

  1. Spuštěním těchto příkazů nainstalujte požadovaná sestavení v aplikaci:

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

  2. Do souboru projektu Program.cs přidejte tento using příkaz:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Nakonfigurujte OpenTelemetry podle toho, zda při spuštění projektu používáte IHostBuilder nebo IHostApplicationBuilder. Druhá verze byla zavedena v 2.x rozšíření izolovaného pracovního modelu .NET.

    Do program.cs přidejte tento řádek kódu za ConfigureFunctionsWebApplication:

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

    Z jedné aplikace můžete exportovat do obou koncových bodů OpenTelemetry.

  1. Přidejte do aplikace požadované knihovny. Způsob přidávání knihoven závisí na tom, jestli nasazujete pomocí Mavenu nebo Kotlinu a jestli chcete také odesílat data do 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. (Volitelné) Přidejte tento kód pro vytvoření vlastních rozsahů:

    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. Nainstalujte do projektu tyto balíčky npm:

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

  1. Vytvořte v projektu soubor kódu, zkopírujte a vložte do tohoto nového souboru následující kód a uložte ho takto 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. main Aktualizujte pole v souboru package.json tak, aby zahrnovalo nový src/index.js soubor. Například:

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

  1. Vytvořte v projektu soubor kódu, zkopírujte a vložte do tohoto nového souboru následující kód a uložte ho takto 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. main Aktualizujte pole v souboru package.json tak, aby zahrnovalo výstup tohoto nového src/index.ts souboru, který může vypadat takto:

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

Důležité

Výstup OpenTelemetry do Application Insights z pracovního procesu jazyka se v současné době nepodporuje pro aplikace PowerShellu. Místo toho můžete chtít použít koncový bod exportéru OTLP. Když nakonfigurujete hostitele pro generování výstupu OpenTelemetry do Application Insights, protokoly vygenerované procesem pracovníka PowerShellu se stále přeposílají, ale distribuované trasování není v tuto chvíli podporováno.

Tyto pokyny platí pouze pro vývozce OTLP:

  1. Přidejte nastavení aplikace s názvem OTEL_FUNCTIONS_WORKER_ENABLED hodnota True.

  2. V kořenovém adresáři aplikace vytvořte Modules na úrovni aplikace a spusťte následující příkaz:

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

    Tento příkaz nainstaluje požadovaný AzureFunctions.PowerShell.OpenTelemetry.SDK modul přímo do vaší aplikace. Tento soubor nemůžete použít requirements.psd1 k automatické instalaci této závislosti, protože spravované závislosti nejsou v současné době podporovány v plánu Flex Consumption Ve verzi Preview.

  3. Přidejte tento kód do souboru profile.ps1:

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

  1. Ujistěte se, že se tyto knihovny nacházejí ve vašem requirements.txt souboru, ať už od odkomentování nebo přidávání sami:

    azure-monitor-opentelemetry

  2. Přidejte tento kód do function_app.py hlavního souboru vstupního bodu:

    Pokud jste už přidali PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true do nastavení aplikace, můžete tento krok přeskočit. Pokud chcete ručně povolit shromažďování Application Insights bez automatické instrumentace, přidejte do aplikace tento kód:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Informace o další konfiguraci sady SDK najdete v dokumentaci k využití distro služby Azure Monitor .

Důležité informace o OpenTelemetry

Při exportu dat pomocí OpenTelemetry mějte na paměti tyto aspekty.

  • Azure Portal podporuje Recent function invocation trasování pouze v případě, že se telemetrie odesílá do služby Azure Monitor.

  • Když nakonfigurujete hostitele tak, aby používal OpenTelemetry, Azure Portal nepodporuje streamování protokolů.

  • Pokud nastavíte telemetryMode na OpenTelemetry, konfigurace v části logging.applicationInsights souboru host.json se nepoužije.

  • Vlastní rozsahy automaticky zahrnují všechny atributy prostředků a používají exportéry nakonfigurované ve vaší aplikaci.

  • Když vaše aplikace běží mimo Azure, včetně během místního vývoje, nastaví detektor service.name prostředků ve výchozím nastavení atribut java-function-app .

  • Pomocí těchto příznaků prostředí Java Virtual Machine (JVM) můžete při místním spuštění během testů jednotek umlčet telemetrii:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • Nemusíte ručně registrovat middleware; pracovní proces Java automaticky rozpozná OpenTelemetryInvocationMiddleware.

Řešení problémů

Při exportu dat pomocí OpenTelemetry mějte na paměti tyto běžné problémy a řešení.

Filtrování protokolů

Pokud chcete správně nakonfigurovat filtrování protokolů v aplikaci funkcí, musíte pochopit rozdíl mezi hostitelským procesem a pracovním procesem.

Hostitelský proces je Azure Functions runtime, který spravuje události, škálování a generuje telemetrii na úrovni systému, jako jsou inicializační protokoly, trasování požadavků a informace o stavu modulu runtime.

Pracovní proces je specifický pro jazyk, spouští kód funkce a vytváří protokoly aplikací a telemetrii nezávisle.

Důležité

Filtry definované v host.json se vztahují pouze na protokoly vygenerované hostitelským procesem. K filtrování protokolů z pracovního procesu musíte použít nastavení OpenTelemetry specifické pro jazyk.

Příklad: Filtrování protokolů hostitele pro všechny poskytovatele v host.json

Tento přístup použijte k nastavení globální úrovně protokolu napříč všemi poskytovateli spravovanými hostitelem:

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

Příklad: Filtrování protokolů pouze pro zprostředkovatele protokolovacího nástroje OpenTelemetry

Tento přístup použijte k cílení pouze na poskytovatele loggeru OpenTelemetry, zatímco ostatní poskytovatelé (například konzolové nebo souborové protokolování) zůstávají neovlivněni.

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

Protokolování konzoly

Hostitel Functions automaticky zachytí všechno, co je zapsáno do stdoutu nebo stderru, a předá ho do kanálu telemetrie. Pokud také použijete ConsoleExporter nebo zapisujete přímo do konzoly ve svém kódu, může dojít k duplicitním záznamům v telemetrických datech.

Poznámka:

Abyste se vyhnuli duplicitním položkám telemetrie, nepřidávejte ConsoleExporter ani nezapisujte do konzoly v produkčním kódu.

Ověřovací systém Microsoft Entra

Pokud používáte ověřování Microsoft Entra s OpenTelemetry, musíte nakonfigurovat ověřování samostatně pro hostitelský proces i pracovní proces.

Pokud chcete nakonfigurovat ověřování pro hostitelský proces, přečtěte si téma Vyžadovat ověřování Microsoft Entra.

Pokud chcete nakonfigurovat ověřování pro pracovní proces, přečtěte si téma Povolení ověřování Microsoft Entra.

Podpora atributů prostředků

Podpora atributů prostředků ve službě Azure Monitor je aktuálně ve verzi Preview. Chcete-li tuto funkci povolit, nastavte proměnnou OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS prostředí na truehodnotu . Toto nastavení ingestuje atributy prostředků do tabulky vlastních metrik.

Duplicitní telemetrie požadavků

Hostitelský proces automaticky generuje telemetrii požadavků. Pokud je pracovní proces instrumentován také pomocí knihoven pro sledování požadavků (například AspNetCoreInstrumentation v .NET), stejný požadavek se ohlásí dvakrát.

Poznámka:

Vzhledem k tomu, že distribuce služby Azure Monitor obvykle zahrnuje AspNetCoreInstrumentation v .NET a podobné instrumentaci v jiných jazycích, nepoužívejte v pracovním procesu distribuci služby Azure Monitor, abyste zabránili duplicitní telemetrii.

Nezahrnuté obory protokolování

Ve výchozím nastavení pracovní proces neobsahuje do svých protokolů obory. Pokud chcete povolit scopy, musíte toto nastavení explicitně nakonfigurovat ve workeru. Následující příklad ukazuje, jak povolit obory v izolovaném prostředí .NET:

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

Chybějící telemetrie požadavků

Triggery, jako jsou HTTP, Service Bus a Event Hubs, závisí na šíření kontextu pro distribuované trasování. U vzorkování založeného na nadřazených objektech jako výchozího chování se telemetrie požadavků negeneruje, když se vzorek příchozího požadavku nebo zprávy nevygeneruje.

Duplicitní identifikátor operace

Ve službě Azure Functions, OperationId používaný pro korelaci telemetrie pochází přímo z hodnoty traceparent obsažené v příchozím požadavku nebo zprávě. Pokud více volání znovu použije stejnou traceparent hodnotu, všechny získají stejnou OperationIdhodnotu .

Konfigurace OpenTelemetry s proměnnými prostředí

Chování OpenTelemetry můžete nakonfigurovat pomocí standardních proměnných prostředí. Tyto proměnné poskytují konzistentní způsob řízení chování v různých jazycích a runtimes. Můžete upravit strategie vzorkování, nastavení vývozce a atributy prostředků. Další informace o podporovaných proměnných prostředí najdete v dokumentaci k OpenTelemetry.

Řešení potíží s monitorováním pomocí diagnostiky

Diagnostika azure Functions na webu Azure Portal je užitečným prostředkem pro zjišťování a diagnostiku potenciálních problémů souvisejících s monitorováním.

Přístup k diagnostice v aplikaci:

  1. Na webu Azure Portal přejděte k prostředku vaší aplikace funkcí.

  2. V levém podokně vyberte Diagnostikovat a řešit problémy a vyhledejte workflow Application Insights nebo OpenTelemetry pro aplikaci Function App chybějící telemetrii.

  3. Vyberte tento pracovní postup, zvolte metodu příjmu dat a vyberte Další.

  4. Projděte si pokyny a všechna doporučení poskytnutá poradcem při potížích.

Další kroky

Další informace o OpenTelemetry a monitorování Azure Functions:

  • Last updated on