Megosztás a következőn keresztül:

OpenTelemetria használata az Azure Functions használatával

Ez a cikk bemutatja, hogyan konfigurálhatja a függvényalkalmazást a napló- és nyomkövetési adatok OpenTelemetria formátumban való exportálására. Az Azure Functions telemetriai adatokat hoz létre a függvényvégrehajtásokról mind a Functions-gazdagépfolyamatból, mind a nyelvspecifikus feldolgozói folyamatból, amelyben a függvénykód fut. Alapértelmezés szerint ezek a telemetriai adatok az Application Insights SDK használatával lesznek elküldve az Application Insightsnak. Azonban az OpenTelemetria szemantikával exportálhatja ezeket az adatokat. Bár továbbra is használhat OpenTelemetry-formátumot az adatok Application Insightsba való küldéséhez, ugyanezeket az adatokat exportálhatja bármely más OpenTelemetria-kompatibilis végpontra is.

Ezeket az előnyöket az OpenTelemetria függvényalkalmazásban való engedélyezésével érheti el:

  • Korrelálja az adatokat a gazdagépen és az alkalmazás kódjában létrehozott nyomkövetések és naplók között.
  • Lehetővé teszi az exportálható telemetriai adatok konzisztens, szabványokon alapuló létrehozását.
  • Integrálható más, OpenTelemetry-kompatibilis adatokat használó szolgáltatókkal.

A cikk használatakor tartsa szem előtt ezeket a szempontokat:

  • Próbálja ki az OpenTelemetry oktatóanyagot, amely az OpenTelemetria és az Azure Functions gyors használatának segítésére készült. Ez a cikk az Azure Developer CLI (azd) használatával hoz létre és helyez üzembe egy Olyan függvényalkalmazást, amely OpenTelemetry-integrációt használ az elosztott nyomkövetéshez.

  • Mivel ez a cikk a választott fejlesztési nyelvre irányul, ne felejtse el kiválasztani a megfelelő nyelvet a cikk tetején.

  • Az OpenTelemetria a függvényalkalmazás szintjén engedélyezve van a gazdagép konfigurációjában (host.json) és a kódprojektben is. A Functions emellett ügyféloptimalizált felületet biztosít az OpenTelemetry-adatok exportálásához a nyelvspecifikus feldolgozói folyamatban futó függvénykódból.

OpenTelemetria engedélyezése a Functions-gazdagépen

Ha engedélyezi az OpenTelemetry-kimenetet a függvényalkalmazás host.json fájljában, a gazdagép függetlenül az alkalmazás által használt nyelvi veremtől exportálja az OpenTelemetry-kimenetet.

Ha engedélyezni szeretné az OpenTelemetry-kimenetet a Functions-gazdagépről, frissítse a kódprojekt host.json fájlját , hogy hozzáadjon egy "telemetryMode": "OpenTelemetry" elemet a gyökérgyűjteményhez. Ha az OpenTelemetry engedélyezve van, a host.json fájl a következőképpen nézhet ki:

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

Alkalmazásbeállítások konfigurálása

Amikor engedélyezi az OpenTelemetryt a host.json fájlban, az alkalmazás környezeti változói határozzák meg az adatok küldésének végpontjait az OpenTelemetry által támogatott alkalmazásbeállítások alapján.

Hozzon létre konkrét alkalmazásbeállításokat a függvényalkalmazásban az OpenTelemetry kimeneti célhelyének megfelelően. Amikor megadja az Application Insights és az OpenTelemetry protocol (OTLP) exportőr kapcsolati beállításait, az OpenTelemetry-adatokat a rendszer mindkét végpontra elküldi.

APPLICATIONINSIGHTS_CONNECTION_STRING: egy Application Insights-munkaterület kapcsolati sztringje. Ha ez a beállítás létezik, a rendszer OpenTelemetry-adatokat küld az adott munkaterületre. Ugyanezzel a beállítással csatlakozhat az Application Insightshoz az OpenTelemetry engedélyezése nélkül. Ha az alkalmazás még nem rendelkezik ezzel a beállítással, lehetséges, hogy engedélyeznie kell az Application Insights integrációját.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: úgy van true beállítva, hogy a Functions-gazdagép lehetővé teszi, hogy a Java-feldolgozó folyamat közvetlenül streamelje az OpenTelemetry-naplókat, ami megakadályozza az ismétlődő gazdagépszintű bejegyzéseket.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: olyan értékre van true beállítva, hogy a Functions-gazdagép lehetővé tegye a Python munkafolyamat számára az OpenTelemetry-naplók közvetlen továbbítását, ezáltal megakadályozva a gazdagépszintű bejegyzések ismétlődését.

OpenTelemetria engedélyezése az alkalmazásban

Miután konfigurálta a Functions-gazdagépet az OpenTelemetria használatára, frissítse az alkalmazáskódot az OpenTelemetry-adatok kimenetére. Ha az OpenTelemetryt a gazdagépen és az alkalmazás kódjában is engedélyezi, jobb korrelációt kap a Functions-gazdafolyamat és a nyelvi feldolgozó folyamat által kibocsátott nyomkövetések és naplók között.

Az alkalmazás OpenTelemetry használatára való előkészítése attól függ, melyik cél OpenTelemetry-végpontot használja:

A cikkben szereplő példák feltételezik, hogy az alkalmazás a IHostApplicationBuilderMicrosoft.Azure.Functions.Worker 2.x és újabb verziójában érhető el. További információ: 2.x verzió a C# izolált feldolgozómodell útmutatójában.

  1. Futtassa az alábbi parancsokat a szükséges szerelvények telepítéséhez az alkalmazásban:

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

  2. A Program.cs projektfájlban adja hozzá ezt az utasítást using :

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Konfigurálja az OpenTelemetryt attól függően, hogy a projekt indítása IHostBuilder vagy IHostApplicationBuilder használatával történik. Ez utóbbi a .NET izolált feldolgozómodell-bővítmény 2.x verziójában lett bevezetve.

    Adja hozzá ezt a kódsort a program.cs fájlban a következő után ConfigureFunctionsWebApplication.

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

    Mindkét OpenTelemetry-végpontra exportálhat ugyanabból az alkalmazásból.

  1. Adja hozzá a szükséges könyvtárakat az alkalmazáshoz. A kódtárak hozzáadásának módja attól függ, hogy a Maven vagy a Kotlin használatával helyezi-e üzembe, és hogy adatokat szeretne-e küldeni az Application Insightsnak.

    <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. (Nem kötelező) Adja hozzá ezt a kódot egyéni tartományok létrehozásához:

    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. Telepítse ezeket az npm-csomagokat a projektben:

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

  1. Hozzon létre egy kódfájlt a projektben, másolja és illessze be az alábbi kódot az új fájlba, és mentse a fájlt a következőként 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. Frissítse a main package.json fájl mezőjét úgy, hogy az tartalmazza az új src/index.js fájlt. Például:

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

  1. Hozzon létre egy kódfájlt a projektben, másolja és illessze be az alábbi kódot az új fájlba, és mentse a fájlt a következőként 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. Frissítse a main package.json fájl mezőjét úgy, hogy az tartalmazza az új src/index.ts fájl kimenetét, amely így nézhet ki:

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

Fontos

A PowerShell-alkalmazások jelenleg nem támogatják az Application Insights openTelemetry kimenetét a nyelvi feldolgozótól. Érdemes lehet inkább OTLP-exportőri végpontot használnia. Amikor a hostot beállítja OpenTelemetry-kimenetre az Application Insights számára, a PowerShell-munkafolyamat által generált naplók továbbra is továbbítódnak, de az elosztott nyomkövetés jelenleg nincs támogatva.

Ezek az utasítások csak egy OTLP-exportőrre vonatkoznak:

  1. Adjon hozzá egy olyan alkalmazásbeállítást OTEL_FUNCTIONS_WORKER_ENABLED , amelynek értéke : True.

  2. Hozzon létre egy alkalmazásszintű Modules mappát az alkalmazás gyökerében, és futtassa a következő parancsot:

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

    Ez a parancs közvetlenül az alkalmazásban telepíti a szükséges AzureFunctions.PowerShell.OpenTelemetry.SDK modult. A fájllal nem telepítheti automatikusan ezt a requirements.psd1 függőséget, mert a Felügyelt függőségek jelenleg nem támogatottak a Flex Consumption csomag előzetes verziójában.

  3. Adja hozzá ezt a kódot a profile.ps1 fájlhoz:

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

  1. Győződjön meg arról, hogy ezek a könyvtárak a requirements.txt fájlban szerepelnek, akár úgy, hogy megjegyzésből kivesszük, akár úgy, hogy saját maga adja hozzá őket:

    azure-monitor-opentelemetry

  2. Adja hozzá ezt a kódot a fő belépési pont fájljához function_app.py :

    Ha már felvette PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true az alkalmazásbeállításokba, kihagyhatja ezt a lépést. Ha automatikus rendszerezés nélkül szeretné manuálisan engedélyezni az Application Insights-gyűjteményt, adja hozzá ezt a kódot az alkalmazáshoz:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Tekintse át az Azure Monitor Disztribúció használati dokumentációját az SDK további konfigurálásával kapcsolatos lehetőségekért.

Az OpenTelemetria szempontjai

Amikor OpenTelemetria használatával exportálja az adatokat, tartsa szem előtt ezeket a szempontokat.

  • Az Azure Portal csak akkor támogatja Recent function invocation a nyomkövetéseket, ha a telemetriát elküldi az Azure Monitornak.

  • Amikor a gazdagépet OpenTelemetria használatára konfigurálja, az Azure Portal nem támogatja a naplóstreamelést.

  • Ha a telemetryMode értéket OpenTelemetry-re állítja, a host.json fájl logging.applicationInsights szakaszának konfigurációja nem alkalmazható.

  • Az egyéni spanok automatikusan tartalmazzák az összes erőforrásattribútumot, és az alkalmazásban konfigurált exportőröket használják.

  • Amikor az alkalmazás az Azure-on kívül fut, beleértve a helyi fejlesztés során is, az erőforrás-érzékelő alapértelmezés szerint beállítja az service.name attribútumot java-function-app .

  • Ezeket a Java virtuális gépek (JVM) jelzőket használva elnémíthatja a telemetriát, amikor helyileg fut az egységtesztek során:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • Nincs szükség a köztes szoftver manuális regisztrálására; a Java worker automatikusan észleli OpenTelemetryInvocationMiddleware.

Hibaelhárítás

Amikor OpenTelemetria használatával exportálja az adatokat, tartsa szem előtt ezeket a gyakori problémákat és megoldásokat.

Naplószűrés

Ha megfelelően szeretné konfigurálni a naplószűrést a függvényalkalmazásban, ismernie kell a gazdafolyamat és a feldolgozói folyamat közötti különbséget.

A gazdafolyamat az Azure Functions-futtatókörnyezet, amely kezeli az eseményindítókat, a skálázást, és rendszerszintű telemetriát bocsát ki, például inicializálási naplókat, kérelmek nyomkövetéseit és futásidejű állapotinformációkat.

A feldolgozói folyamat nyelvspecifikus, végrehajtja a függvénykódot, és egymástól függetlenül állítja elő az alkalmazásnaplókat és a telemetriát.

Fontos

A host.json fájlban meghatározott szűrők csak a gazdagépfolyamat által létrehozott naplókra vonatkoznak. A munkavégző folyamat naplóinak szűréséhez nyelvspecifikus OpenTelemetria-beállításokat kell használnia.

Példa: Gazdagépnaplók szűrése az host.jsonösszes szolgáltatója számára

Ezzel a módszerrel globális naplószintet állíthat be a gazdagép által felügyelt összes szolgáltatóra:

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

Példa: Csak az OpenTelemetry logger szolgáltató esetében szűrje a naplókat

Ezzel a módszerrel csak az OpenTelemetry-naplózó szolgáltatóját célozhatja meg, miközben más szolgáltatókat (például konzolt vagy fájlnaplózást) nem érint:

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

Konzolnaplózás

A Functions-gazdagép automatikusan rögzíti az stdout-ra vagy stderrre írt adatokat, és továbbítja azt a telemetriai folyamatnak. Ha ConsoleExportert használ, vagy közvetlenül a konzolra írja a kódot, telemetriai adataiban ismétlődő naplóbejegyzések fordulhatnak elő.

Megjegyzés:

Az ismétlődő telemetriai bejegyzések elkerülése érdekében ne adjon hozzá ConsoleExportert, és ne írjon a konzolra gyártói kódban.

Microsoft Entra-hitelesítés

Ha a Microsoft Entra-hitelesítést OpenTelemetria használatával használja, a hitelesítést külön kell konfigurálnia a gazdafolyamathoz és a feldolgozó folyamathoz is.

A gazdafolyamat hitelesítésének konfigurálásához lásd: Microsoft Entra-hitelesítés megkövetelése.

A feldolgozói folyamat hitelesítésének konfigurálásához lásd: Microsoft Entra-hitelesítés engedélyezése.

Erőforrásattribútumok támogatása

Az Azure Monitor erőforrásattribútumainak támogatása jelenleg előzetes verzióban érhető el. A funkció engedélyezéséhez állítsa a OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS környezeti változót a következőre: true. Ez a beállítás betölti az erőforrásattribútumokat az egyéni metrikák táblájába.

Ismétlődő lekérdezés-telemetria

A gazdafolyamat automatikusan küldi a kérés telemetriáját. Ha a munkavégző folyamatot kérelemkövetési kódtárakkal is rendszerezik (például AspNetCoreInstrumentation a .NET-ben), ugyanazt a kérést kétszer jelenti a rendszer.

Megjegyzés:

Mivel az Azure Monitor disztró általában tartalmazza az AspNetCoreInstrumentationt a .NET-ben és más programozási nyelvek hasonló instrumentációját is, kerülje az Azure Monitor disztró használatát a munkafolyamatokban, az ismétlődő telemetriai adatok elkerülése érdekében.

Nem tartalmazzák a naplózási hatóköröket

Alapértelmezés szerint a feldolgozói folyamat nem tartalmaz hatóköröket a naplóiban. A hatókörök engedélyezéséhez ezt a beállítást explicit módon kell konfigurálnia a feldolgozóban. Az alábbi példa bemutatja, hogyan engedélyezheti a hatóköröket az izolált .NET-ben:

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

Hiányzó kérés telemetria

Az olyan eseményindítók, mint a HTTP, a Service Bus és az Event Hubs, az elosztott nyomkövetés környezetpropagálásától függenek. Ha a szülőalapú mintavételezés az alapértelmezett viselkedés, a kérés telemetriája nem jön létre, ha a bejövő kérés vagy üzenet nincs mintavételezésre.

Duplikált műveletazonosító

Az Azure Functionsben a OperationId telemetriai adatok korrelációja közvetlenül a traceparent bejövő kérés vagy üzenet értékéből származik. Ha több hívás is ugyanazt traceparent az értéket használja újra, mindegyik ugyanazt OperationIdkapja.

OpenTelemetria konfigurálása környezeti változókkal

Az OpenTelemetry viselkedését a szokásos környezeti változók használatával konfigurálhatja. Ezek a változók egységes módot biztosítanak a különböző nyelvek és futtatókörnyezetek viselkedésének szabályozására. Módosíthatja a mintavételezési stratégiákat, az exportőr beállításait és az erőforrás-attribútumokat. A támogatott környezeti változókkal kapcsolatos további információkért tekintse meg az OpenTelemetry dokumentációját.

Monitorozási problémák elhárítása diagnosztikák használatával

Az Azure Functions-diagnosztika az Azure Portalon hasznos erőforrás a lehetséges figyeléssel kapcsolatos problémák észleléséhez és diagnosztizáléséhez.

Diagnosztikához való hozzáférés az alkalmazásban:

  1. Az Azure Portalon nyissa meg a függvényalkalmazás erőforrását.

  2. A bal oldali panelen válassza a Problémák diagnosztizálása és megoldása lehetőséget, és keresse meg a Függvényalkalmazás hiányzó telemetriáját az Application Insights vagy az OpenTelemetry munkafolyamat esetében.

  3. Válassza ki ezt a munkafolyamatot, válassza ki a betöltési módszert, és válassza a Tovább lehetőséget.

  4. Tekintse át a hibaelhárító által megadott irányelveket és javaslatokat.

Következő lépések

További információ az OpenTelemetryről és az Azure Functions monitorozásáról:

  • Last updated on