Problemen in Durable Functions diagnosticeren en oplossen

Durable Functions biedt verschillende diagnostische hulpprogramma's voor het oplossen van problemen met orkestraties. In dit artikel wordt beschreven hoe u tracering en logboekregistratie configureert, veilige code voor opnieuw afspelen schrijft, gedistribueerde traceringen inspecteert en lokaal fouten opspoort.

In dit artikel leert u het volgende:

Application Insights-tracering configureren

Application Insights is de aanbevolen manier om Durable Functions te bewaken. De Durable-extensie verzendt traceringsgebeurtenissen waarmee u de end-to-end-uitvoering van een orkestratie kunt traceren. U kunt deze traceringsgebeurtenissen vinden en er query's op uitvoeren met behulp van het hulpprogramma Application Insights Analytics in de Azure-portal.

Configuratie op logboekniveau

Configureer de uitgebreidheid van traceringsgegevens die worden verzonden naar Application Insights in uw host.json-bestand :

{
    "logging": {
        "logLevel": {
            "Host.Triggers.DurableTask": "Information",
        },
    }
}

Standaard worden alle niet-herhalingstraceringsgebeurtenissen verzonden. U kunt het volume van gegevens verminderen door Host.Triggers.DurableTask in te stellen op "Warning" of "Error", waardoor alleen bijhoudingsgebeurtenissen worden verzonden voor uitzonderlijke situaties. Als u het verzenden van de uitgebreide herafspeelgebeurtenissen van orchestratie wilt inschakelen, stelt u logReplayEvents in op true in het host.json configuratiebestand.

Invoer- en uitvoerlogboekregistratie

Standaard worden de invoer en uitvoer van orchestrator-, activiteits- en entiteitsfuncties niet vastgelegd. Deze methode wordt aanbevolen omdat het loggen van invoer en uitvoer de kosten van Application Insights kan verhogen. Functie-invoer- en uitvoerladingen kunnen ook gevoelige informatie bevatten. In plaats daarvan wordt het aantal bytes voor functie-invoer en -uitvoer vastgelegd. Als u wilt dat de Durable Functions-extensie de volledige invoer- en uitvoergegevens logt, stelt u de eigenschap traceInputsAndOutputs in op true in het configuratiebestand host.json.

Queryindelingexemplaren

Gebruik de volgende Kusto-queries in Application Insights Analytics om orkestratie-exemplaren te inspecteren.

Query voor een enkele instantie

In de volgende query ziet u historische trackinggegevens voor een enkel exemplaar van de Hello Sequence functie-orkestratie. Hiermee wordt de uitvoering van herhalingen gefilterd, zodat alleen het logische uitvoeringspad wordt weergegeven. U kunt gebeurtenissen ordenen door te sorteren op timestamp en sequenceNumber, zoals wordt weergegeven in de volgende query:

let targetInstanceId = "ddd1aaa685034059b545eb004b15d4eb";
let start = datetime(2018-03-25T09:20:00);
traces
| where timestamp > start and timestamp < start + 30m
| where customDimensions.Category == "Host.Triggers.DurableTask"
| extend functionName = customDimensions["prop__functionName"]
| extend instanceId = customDimensions["prop__instanceId"]
| extend state = customDimensions["prop__state"]
| extend isReplay = tobool(tolower(customDimensions["prop__isReplay"]))
| extend sequenceNumber = tolong(customDimensions["prop__sequenceNumber"])
| where isReplay != true
| where instanceId == targetInstanceId
| sort by timestamp asc, sequenceNumber asc
| project timestamp, functionName, state, instanceId, sequenceNumber, appName = cloud_RoleName

Het resultaat is een lijst met gebeurtenissen die het uitvoeringspad van de orchestratie weergeven, inclusief activiteitsfuncties die zijn gerangschikt in oplopende volgorde op uitvoeringstijd.

Samenvattingsquery exemplaar

De volgende query toont de status van alle orchestratie-instanties die binnen een opgegeven tijdsbestek zijn uitgevoerd.

let start = datetime(2017-09-30T04:30:00);
traces
| where timestamp > start and timestamp < start + 1h
| where customDimensions.Category == "Host.Triggers.DurableTask"
| extend functionName = tostring(customDimensions["prop__functionName"])
| extend instanceId = tostring(customDimensions["prop__instanceId"])
| extend state = tostring(customDimensions["prop__state"])
| extend isReplay = tobool(tolower(customDimensions["prop__isReplay"]))
| extend output = tostring(customDimensions["prop__output"])
| where isReplay != true
| summarize arg_max(timestamp, *) by instanceId
| project timestamp, instanceId, functionName, state, output, appName = cloud_RoleName
| order by timestamp asc

Het resultaat is een lijst met exemplaar-id's en hun huidige runtimestatus.

Referentie voor traceringsgegevens

Elke orchestratie-instantie genereert tracking events tijdens zijn levenscyclus. Elke levenscyclusgebeurtenis bevat een customDimensions payload met verschillende velden. Veldnamen worden allemaal voorafgegaan door prop__.

Durable Task Framework-logboekregistratie (DTFx)

De durable-extensielogboeken zijn handig om inzicht te krijgen in het gedrag van uw indelingslogica. Deze logboeken bevatten echter niet altijd voldoende informatie om prestatie- en betrouwbaarheidsproblemen op frameworkniveau op te sporen. Vanaf v2.3.0 van de Durable-extensie zijn logboeken die worden verzonden door het onderliggende Durable Task Framework (DTFx) ook beschikbaar voor verzameling.

Wanneer u logboeken bekijkt die door de DTFx worden verzonden, is het belangrijk om te begrijpen dat de DTFx-engine twee onderdelen heeft: de kern-dispatch-engine (DurableTask.Core) en een van de vele ondersteunde opslagproviders.

U kunt deze logboeken inschakelen door de sectie van het logging/logLevel host.json-bestand van uw functie-app bij te werken. In het volgende voorbeeld ziet u hoe u waarschuwings- en foutlogboeken van zowel DurableTask.Core als DurableTask.AzureStorage kunt inschakelen.

{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "DurableTask.AzureStorage": "Warning",
      "DurableTask.Core": "Warning"
    }
  }
}

Als Application Insights is ingeschakeld, worden deze logboeken automatisch toegevoegd aan de trace verzameling. U kunt ze op dezelfde manier doorzoeken als u andere trace logboeken zoekt met behulp van Kusto-query's.

De volgende Kusto-query laat zien hoe u query's kunt uitvoeren op DTFx-logboeken. Het belangrijkste onderdeel van de query is where customerDimensions.Category startswith "DurableTask", aangezien het de resultaten filtert naar logs in de DurableTask.Core- en DurableTask.AzureStorage-categorieën.

traces
| where customDimensions.Category startswith "DurableTask"
| project
    timestamp,
    severityLevel,
    Category = customDimensions.Category,
    EventId = customDimensions.EventId,
    message,
    customDimensions
| order by timestamp asc 

Het resultaat is een set logboeken die zijn geschreven door de Durable Task Framework-logboekproviders.

Zie de documentatie over gestructureerde logging van het Durable Task Framework op GitHub voor meer informatie over welke logboekgebeurtenissen beschikbaar zijn.

Gedistribueerde tracering

Gedistribueerde tracering houdt aanvragen bij en laat zien hoe verschillende services met elkaar communiceren. In Durable Functions correleert het orkestraties, entiteiten en activiteiten. Gedistribueerde tracering toont de uitvoeringstijd voor elke orchestratiestap ten opzichte van de gehele orkestratie en identificeert waar problemen of uitzonderingen optreden. Deze functie wordt ondersteund in Application Insights voor alle talen en opslagproviders.

Prerequisites

Voor gedistribueerde tracering zijn specifieke minimale uitbreidingsversies vereist:

• Voor .NET Geïsoleerde apps, Microsoft.Azure.Functions.Worker.Extensions.DurableTask>= v1.4.0.
• Voor niet-.NET-apps, volg deze instructies om handmatig Microsoft.Azure.WebJobs.Extensions.DurableTask>= v3.2.0 voor nu te installeren. Gedistribueerde tracering is beschikbaar in extensiebundels >v4.24.x.

Gedistribueerde tracering instellen

Als u gedistribueerde tracering wilt configureren, werkt u de host.json Application Insights-resource bij en stelt u deze in.

host.json

{
   "extensions": {
     "durableTask": {
       "tracing": {
         "distributedTracingEnabled": true,
         "version": "V2"
       }
     }
   }
 }

Analyses van toepassingen

Configureer uw functie-app met een Application Insights-resource.

De traceringen inspecteren

Navigeer in uw Application Insights-resource naar Transaction Search. Zoek in de resultaten naar Request en Dependency gebeurtenissen die beginnen met duurzame voorvoegsels (bijvoorbeeld orchestration:, activity:enzovoort). Als u een van deze gebeurtenissen selecteert, wordt een Gantt-diagram geopend waarin de end-to-end gedistribueerde tracering wordt weergegeven. In de grafiek wordt elke orkestratiestap weergegeven als een horizontale balk, met activiteits- en suborkestratieoproepen die zijn genest onder de bovenliggende orkestratie. De staaflengte vertegenwoordigt de duur van de wandklok van elke stap, zodat u eenvoudig knelpunten of onverwacht trage activiteiten kunt herkennen.

Logging met herhalingsbeveiliging in orkestraatorfuncties

Orchestrator-functies worden telkens opnieuw afgespeeld wanneer nieuwe invoer wordt ontvangen, wat betekent dat elke logboekinstructie in een orchestrator meerdere keren wordt uitgevoerd voor één logische uitvoering. Een functie met drie activiteitsoproepen produceert bijvoorbeeld logboekuitvoer zoals deze tijdens het opnieuw afspelen:

Calling F1.
Calling F1.
Calling F2.
Calling F1.
Calling F2.
Calling F3.
Calling F1.
Calling F2.
Calling F3.
Done!

Als u dubbele logregels wilt voorkomen, controleer dan de vlag 'wordt herhaald' zodat logs alleen worden uitgevoerd tijdens de eerste keer (niet-herhaling). In de volgende voorbeelden ziet u veilige logboekregistratie tegen herhaling in elke taal.

[FunctionName("FunctionChain")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context,
    ILogger log)
{
    log = context.CreateReplaySafeLogger(log);
    log.LogInformation("Calling F1.");
    await context.CallActivityAsync("F1");
    log.LogInformation("Calling F2.");
    await context.CallActivityAsync("F2");
    log.LogInformation("Calling F3");
    await context.CallActivityAsync("F3");
    log.LogInformation("Done!");
}

[Function("FunctionChain")]
public static async Task Run([OrchestrationTrigger] TaskOrchestrationContext context)
{
    ILogger log = context.CreateReplaySafeLogger("FunctionChain");
    log.LogInformation("Calling F1.");
    await context.CallActivityAsync("F1");
    log.LogInformation("Calling F2.");
    await context.CallActivityAsync("F2");
    log.LogInformation("Calling F3");
    await context.CallActivityAsync("F3");
    log.LogInformation("Done!");
}

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context){
    if (!context.df.isReplaying) context.log("Calling F1.");
    yield context.df.callActivity("F1");
    if (!context.df.isReplaying) context.log("Calling F2.");
    yield context.df.callActivity("F2");
    if (!context.df.isReplaying) context.log("Calling F3.");
    yield context.df.callActivity("F3");
    context.log("Done!");
});

import * as df from "durable-functions";

df.app.orchestration("FunctionChain", function* (context) {
    if (!context.df.isReplaying) context.log("Calling F1.");
    yield context.df.callActivity("F1");
    if (!context.df.isReplaying) context.log("Calling F2.");
    yield context.df.callActivity("F2");
    if (!context.df.isReplaying) context.log("Calling F3.");
    yield context.df.callActivity("F3");
    context.log("Done!");
});

import logging
import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    if not context.is_replaying:
        logging.info("Calling F1.")
    yield context.call_activity("F1")
    if not context.is_replaying:
        logging.info("Calling F2.")
    yield context.call_activity("F2")
    if not context.is_replaying:
        logging.info("Calling F3.")
    yield context.call_activity("F3")
    logging.info("Done!")
    return None

main = df.Orchestrator.create(orchestrator_function)

@FunctionName("FunctionChain")
public void functionChain(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx,
        ExecutionContext functionContext) {
    Logger log = functionContext.getLogger();
    if (!ctx.getIsReplaying()) log.info("Calling F1.");
    ctx.callActivity("F1").await();
    if (!ctx.getIsReplaying()) log.info("Calling F2.");
    ctx.callActivity("F2").await();
    if (!ctx.getIsReplaying()) log.info("Calling F3.");
    ctx.callActivity("F3").await();
    log.info("Done!");
}

Bij replay-veilige logboekregistratie is de logboekuitvoer:

Calling F1.
Calling F2.
Calling F3.
Done!

Aangepaste orkestratiestatus

Gebruik de aangepaste orkestratiestatus om de voortgang van de werkstroom te rapporteren aan externe klanten. Veelvoorkomende patronen zijn voltooiingspercentages, stapbeschrijvingen en samenvattingen van fouten. Externe clients kunnen de aangepaste status bekijken via de HTTP-statusquery-API of taalspecifieke API-aanroepen.

De volgende code laat zien hoe u een aangepaste statuswaarde instelt in een orchestratorfunctie:

[FunctionName("SetStatusTest")]
public static async Task SetStatusTest([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    var customStatus = new { completionPercentage = 90.0, status = "Updating database records" };
    context.SetCustomStatus(customStatus);

    // ...do more work...
}

[Function("SetStatusTest")]
public static async Task SetStatusTest([OrchestrationTrigger] TaskOrchestrationContext context)
{
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    var customStatus = new { completionPercentage = 90.0, status = "Updating database records" };
    context.SetCustomStatus(customStatus);

    // ...do more work...
}

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    const customStatus = { completionPercentage: 90.0, status: "Updating database records", };
    context.df.setCustomStatus(customStatus);

    // ...do more work...
});

import * as df from "durable-functions";

df.app.orchestration("SetStatusTest", function* (context) {
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    const customStatus = { completionPercentage: 90.0, status: "Updating database records" };
    context.df.setCustomStatus(customStatus);

    // ...do more work...
});

import logging
import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    # ...do work...

    # update the status of the orchestration with some arbitrary data
    custom_status = {'completionPercentage': 90.0, 'status': 'Updating database records'}
    context.set_custom_status(custom_status)
    # ...do more work...

    return None

main = df.Orchestrator.create(orchestrator_function)

@FunctionName("SetStatusTest")
public void setStatusTest(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    ctx.setCustomStatus(new Object() {
        public final double completionPercentage = 90.0;
        public final String status = "Updating database records";
    });

    // ...do more work...
}

Terwijl de orkestratie wordt uitgevoerd, kunnen externe cliënten deze aangepaste status ophalen.

GET /runtime/webhooks/durabletask/instances/instance123?code=XYZ

Clients krijgen het volgende antwoord:

{
  "runtimeStatus": "Running",
  "input": null,
  "customStatus": { "completionPercentage": 90.0, "status": "Updating database records" },
  "output": null,
  "createdTime": "2017-10-06T18:30:24Z",
  "lastUpdatedTime": "2017-10-06T19:40:30Z"
}

foutopsporing

Azure Functions biedt rechtstreeks ondersteuning voor het debuggen van functiecode, en dezelfde ondersteuning is van toepassing op Durable Functions, ongeacht of deze wordt uitgevoerd in Azure of lokaal. Gebruik de volgende werkstroom voor de beste foutopsporingservaring:

1. Start een nieuwe foutopsporingssessie met een nieuwe taakhub of wis de inhoud van de taakhub tussen sessies. Restberichten van eerdere uitvoeringen kunnen onverwachte heruitvoering veroorzaken.

2. Stel onderbrekingspunten in uw orchestrator- of activiteitsfuncties in. Gebruik voor orchestratorfuncties een voorwaardelijk onderbrekingspunt dat alleen wordt verbroken wanneer de waarde 'opnieuw afspelen' is false om te voorkomen dat hetzelfde onderbrekingspunt meerdere keren wordt bereikt tijdens het opnieuw afspelen.

3. Doorloop uw code zoals gewoonlijk. Houd rekening met het volgende gedrag:

   • Replay:
     Orchestrator-functies worden regelmatig opnieuw afgespeeld wanneer nieuwe invoer wordt ontvangen. Een enkele logische uitvoering van een orchestratorfunctie kan ertoe leiden dat hetzelfde onderbrekingspunt meerdere keren wordt bereikt, vooral als deze vroeg in de functiecode is ingesteld.

   • Wachten:
     Wanneer er een await in een orchestratorfunctie wordt aangetroffen, wordt de controle teruggegeven aan de dispatcher van het Durable Task Framework. Als het de eerste keer is dat een bepaalde await taak wordt aangetroffen, wordt de bijbehorende taak nooit hervat. Omdat de taak nooit wordt hervat, is stappen over het wachten (F10 in Visual Studio) niet mogelijk. Stappen werkt alleen wanneer een taak opnieuw wordt afgespeeld.

   • Time-outs voor berichten:
     Durable Functions maakt intern gebruik van wachtrijberichten om de uitvoering van orchestrator-, activiteits- en entiteitsfuncties te stimuleren. In een omgeving met meerdere VM's kunnen uitgebreide foutopsporingssessies ertoe leiden dat een andere VIRTUELE machine het bericht verwerkt, wat resulteert in dubbele uitvoering. Hoewel dit gedrag ook bestaat voor reguliere functies voor wachtrijtriggers, is deze context belangrijk om te markeren omdat de wachtrijen een implementatiedetails zijn.

   • Stoppen en starten:
     Berichten in Durable Functions worden behouden tussen foutopsporingssessies. Als u de foutopsporing stopt en het lokale hostproces beëindigt terwijl een duurzame functie wordt uitgevoerd, kan die functie automatisch opnieuw worden uitgevoerd in een toekomstige foutopsporingssessie.

Aanvullende hulpprogramma’s

Opslagstatus controleren

Durable Functions slaat standaard de status op in Azure Storage. U kunt indelingsstatus en berichten inspecteren met behulp van hulpprogramma's zoals Microsoft Azure Storage Explorer.

Monitor voor duurzame functies

Durable Functions Monitor is een grafisch hulpprogramma voor het bewaken, beheren en debuggen van orchestratie- en entiteitsinstanties. Het is beschikbaar als een Visual Studio Code-extensie of een zelfstandige app. Zie de Durable Functions Monitor Wiki voor installatie-instructies en een lijst met functies.

Diagnostiek van het Azure-portaal

De Azure-portal biedt ingebouwde diagnostische hulpprogramma's voor uw functie-apps.

Problemen vaststellen en oplossen: Diagnostische gegevens van Azure Function-apps zijn een nuttige resource voor het bewaken en diagnosticeren van mogelijke problemen in uw toepassing. Het biedt ook suggesties om problemen op te lossen op basis van de diagnose. Zie Azure Function App Diagnostics voor meer informatie.

Orchestratie-tracering: De Azure-portal biedt details over orchestratie-tracering om inzicht te hebben in de status van elk orchestratie-exemplaar en de uitvoering van begin tot eind te volgen. Wanneer u de lijst met functies in uw Azure Functions-app bekijkt, ziet u een kolom Monitor met koppelingen naar de traceringen. U moet Application Insights hebben ingeschakeld voor uw app om toegang te krijgen tot deze informatie.

Roslyn Analyzer (een tool voor .NET-ontwikkeling)

De Durable Functions Roslyn Analyzer is een live code analyzer waarmee C#-ontwikkelaars Durable Functions specifieke beperkingen voor het coderen van code kunnen volgen. Zie Durable Functions Roslyn Analyzer voor instructies over het inschakelen ervan in Visual Studio en Visual Studio Code.

Troubleshooting

Als u veelvoorkomende problemen wilt oplossen, zoals orchestraties die vastlopen, niet kunnen worden gestart of langzaam worden uitgevoerd, raadpleegt u de Durable Functions-handleiding voor probleemoplossing Durable Functions.

Volgende stappen