Diagnostika a řešení potíží v Durable Functions

Durable Functions poskytuje několik diagnostických nástrojů pro řešení potíží s orchestrací. Tento článek popisuje, jak nakonfigurovat sledování a protokolování, psát kód bezpečný pro přehrání, zkoumat distribuované stopy a ladit lokalně.

Pokyny v tomto článku jsou obecně použitelné napříč poskytovateli úložišť. Pro aplikace, které používají doporučený backend Durable Task Scheduler, poskytují dashboard plánovače, Application Insights a portál Azure nejpřímější zkušenosti s inspekcí a řešením problémů. Pokud vaše aplikace používá poskytovatele Azure Storage, je zahrnut workflow Průzkumník služby Azure Storage, kde přináší hodnotu.

V tomto článku se naučíte:

Konfigurujte sledování pomocí Application Insights

Application Insights je doporučený způsob monitorování Durable Functions. Rozšíření Durable generuje události sledování, které umožňují sledovat průběh orchestrace od začátku do konce. K vyhledání a dotazování těchto sledovacích událostí můžete použít nástroj Application Insights Analytics na portálu Azure.

Konfigurace úrovně protokolování

Konfigurujte úroveň podrobnosti sledování dat odesílaných do Application Insights ve souboru host.json:

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

Ve výchozím nastavení se vygenerují všechny události sledování, které se nepřehrávají . Objem dat můžete snížit nastavením Host.Triggers.DurableTask na "Warning" nebo "Error", což znamená, že události sledování jsou emitovány pouze pro výjimečné situace. Pokud chcete povolit generování podrobných událostí přehrání orchestrace, nastavte logReplayEvents na true v konfiguračním souboru host.json.

Note

Modul runtime Azure Functions ve výchozím nastavení vzorkuje telemetrii Application Insights, aby se zabránilo příliš častému odesílání dat. Vzorkování může způsobit ztrátu sledovacích informací, když během krátké doby nastane mnoho událostí životního cyklu. Článek monitorování služby Azure Functions vysvětluje, jak toto chování nakonfigurovat.

Protokolování vstupu a výstupu

Ve výchozím nastavení nejsou zaprotokolovány vstupy a výstupy funkcí orchestrátoru, aktivity a entity. Tento přístup se doporučuje, protože protokolování vstupů a výstupů by mohlo zvýšit náklady na Application Insights. Vstupní a výstupní datové části funkce mohou také obsahovat citlivé informace. Místo toho se protokoluje počet bajtů pro vstupy a výstupy funkcí. Pokud chcete, aby rozšíření Durable Functions zaznamenávalo úplné vstupní a výstupní data, nastavte vlastnost traceInputsAndOutputs na true v konfiguračním souboru host.json.

Instance orchestrace dotazů

Ke kontrole instancí orchestrace použijte následující dotazy Kusto v Analýzách Application Insights.

Dotaz na jednu instanci

Následující dotaz ukazuje data historického monitorování pro jednu instanci orchestrace funkce Hello Sequence. Filtruje opakované provádění tak, aby se zobrazila pouze logická cesta provádění. Události můžete seřadit podle timestamp a sequenceNumber jak je znázorněno v následujícím dotazu:

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

Výsledkem je seznam sledování událostí, které zobrazují cestu provádění orchestrace, včetně všech funkcí aktivit seřazených podle času provádění ve vzestupném pořadí.

Snímek obrazovky Application Insights zobrazující výsledky dotazu seřazených jednou instancí se sledováním událostí

Souhrnný dotaz instance

Následující dotaz zobrazí stav všech instancí orchestrace, které byly spuštěny v zadaném časovém rozsahu.

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

Výsledkem je seznam ID instancí a jejich aktuální stav modulu runtime.

Snímek obrazovky Application Insights zobrazující souhrnné výsledky dotazu s jednou instancí s ID instancí a stavem

Referenční informace ke sledování dat

Každá instance orchestrace generuje sledovací události během svého životního cyklu. Každá událost životního cyklu obsahuje datovou část customDimensions s několika poli. Všechny názvy polí jsou připojeny s prop__.

Název pole Description
hubName Název centra úloh, ve kterém vaše orchestrace běží.
appName Název funkční aplikace. Toto pole je užitečné, když máte více aplikací funkcí, které sdílejí stejnou instanci Application Insights.
slotName Slot nasazení, ve kterém běží aktuální funkční aplikace. Toto pole je užitečné při použití nasazovacích slotů pro správu verzí orchestrací.
functionName Název orchestrátoru nebo funkce aktivity.
functionType Typ funkce, například Orchestrator nebo Activity.
instanceId Jedinečné ID instance orchestrace.
state Stav provádění životního cyklu instance.
state.Scheduled Funkce byla naplánována pro spuštění, ale ještě nebyla spuštěna.
state.Started Funkce se spustila, ale ještě nečekala ani nedokončila.
state.Awaited Orchestrátor naplánoval nějakou práci a čeká na dokončení.
state.Listening Orchestrátor naslouchá oznámení o externí události.
state.Completed Funkce byla úspěšně dokončena.
state.Failed Funkce selhala s chybou.
reason Další data přidružená k události sledování Pokud například instance čeká na oznámení o externí události, toto pole označuje název události, na které čeká. Pokud funkce selže, obsahuje toto pole podrobnosti o chybě.
isReplay Logická hodnota označující, zda je událost sledování pro opakované provedení.
extensionVersion Verze rozšíření Durable Task. Informace o verzi jsou obzvláště důležitá data při hlášení možných chyb v rozšíření. Dlouhotrvající instance můžou hlásit více verzí, pokud dojde k aktualizaci, když je instance spuštěná.
sequenceNumber Pořadové číslo spuštění události. V kombinaci s časovým razítkem to pomáhá uspořádat události podle času spuštění. Všimněte si, že toto číslo se resetuje na nulu, pokud se hostitel restartuje během běhu instance. Je proto důležité nejprve řadit podle časového razítka a až poté podle pořadového čísla.

Protokolování událostí v rámci Durable Task Framework (DTFx)

Protokoly rozšíření Durable jsou užitečné pro pochopení chování logiky orchestrace. Tyto protokoly ale vždy neobsahují dostatek informací pro ladění problémů s výkonem a spolehlivostí na úrovni architektury. Od verze 2.3.0 rozšíření Durable jsou protokoly generované podkladovou architekturou Durable Task Framework (DTFx) také k dispozici pro kolekci.

Když procházíte logy, které DTFx vysílá, pamatujte, že engine DTFx má dvě komponenty: jádro dispečerského motoru (DurableTask.Core) a jednoho z několika poskytovatelů úložišť.

Component Description
DurableTask.Core Základní orchestrace spouštění a plánování protokolů a telemetrie nízké úrovně
DurableTask.AzureManagedBackend Back-endové protokoly specifické pro plánovač úloh Durable.
DurableTask.AzureStorage Protokoly backendu specifické pro poskytovatele stavu služby Azure Storage. Mezi tyto protokoly patří podrobné interakce s interními frontami, datovými objekty a tabulkami úložiště, které se používají k ukládání a načítání interních stavů orchestrace.
DurableTask.Netherite Back-end protokoly specifické pro poskytovatele úložiště Netherite, pokud je povolen.
DurableTask.SqlServer Protokoly back-endu specifické pro poskytovatele úložiště Microsoft SQL (MSSQL), pokud je povoleno.
{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "DurableTask.AzureStorage": "Warning",
      "DurableTask.Core": "Warning"
    }
  }
}

Pokud máte službu Application Insights povolenou, tyto protokoly se automaticky přidají do trace kolekce. Můžete je prohledávat stejným způsobem, jakým hledáte jiné trace protokoly pomocí dotazů Kusto.

Note

Pro produkční aplikace povolte DurableTask.Core a nastavte příslušnou kategorii backend log pro vašeho poskytovatele úložiště (například DurableTask.AzureManagedBackend pro doporučený backend Durable Task Scheduler nebo DurableTask.AzureStorage pro poskytovatele Azure Storage) pomocí filtru"Warning". Filtry "Information" s vyšší rozvětvností jsou užitečné pro ladění výkonnostních problémů. Tyto události protokolu ale můžou být velké a můžou výrazně zvýšit náklady na úložiště dat Application Insights.

Následující dotaz Kusto ukazuje, jak získat protokoly DTFx. Nejdůležitější částí dotazu je where customerDimensions.Category startswith "DurableTask", protože výsledky filtruje na protokoly v kategoriích DurableTask.Core a DurableTask.AzureStorage.

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

Výsledkem je sada protokolů napsaných poskytovateli protokolů Durable Task Framework.

Snímek obrazovky Application Insights zobrazující výsledky dotazu DTFx s protokoly Durable Task Framework

Další informace o dostupných událostech protokolu najdete v dokumentaci strukturovaného protokolování Durable Task Framework na GitHubu.

Distribuované trasování

Distribuované trasování sleduje požadavky a ukazuje, jak vzájemně vzájemně komunikují různé služby. Ve službě Durable Functions se orchestrace, entity a aktivity vzájemně korrelují. Distribuované trasování zobrazuje čas spuštění pro každý krok orchestrace vzhledem k celé orchestraci a identifikuje, kde dochází k problémům nebo výjimkám. Tato funkce je dostupná v Application Insights pro všechny jazyky a poskytovatele úložišť.

Předpoklady

Distribuované trasování vyžaduje konkrétní minimální verze rozšíření:

Nastavení distribuovaného trasování

Pokud chcete nakonfigurovat distribuované trasování, aktualizujte host.json a nastavte prostředek Application Insights.

host.json

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

Application Insights

Nakonfigurujte aplikaci funkcí pomocí prostředku Application Insights.

Kontrola trasování

V prostředku Application Insights přejděte do vyhledávání transakcí. Ve výsledcích vyhledejte Request a Dependency události, které začínají předponami specifickými pro Durable (například orchestration:, atd activity:.). Výběrem jedné z těchto událostí se otevře Ganttův diagram, který zobrazuje kompletní distribuované trasování. Graf zobrazuje každý krok orchestrace jako vodorovný pruh, přičemž volání aktivit a dílčích orchestrací jsou vnořeny pod svou nadřazenou orchestraci. Délka sloupce představuje reálný čas trvání jednotlivých kroků, což usnadňuje rozpoznávání úzkých míst nebo neočekávaně pomalých aktivit.

Snímek obrazovky Ganttova diagramu znázorňující distribuované trasování Application Insights s orchestrací a časovými osami aktivit

Note

Nevidíte stopy v Application Insights? Počkejte asi pět minut po spuštění aplikace, abyste zajistili, že se všechna data rozšíří do prostředku Application Insights.

Zabezpečené protokolování proti opakování ve funkcích orchestrátoru

Funkce orchestrátoru se přehrávají při každém přijetí nového vstupu, což znamená, že jakýkoli příkaz protokolu v orchestrátoru se může spustit několikrát během jednoho logického provedení. Například funkce se třemi voláními aktivit vytváří při přehrání takovýto výstup protokolu:

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

Pokud chcete zabránit duplicitním řádkům protokolu, zkontrolujte příznak "is replaying", aby se protokoly spouštěly pouze při prvním průchodu (bez opětovného přehrání). Následující příklady ukazují, jak funguje protokolování bezpečné proti opakování v různých jazycích.

Počínaje Durable Functions 2.0 použijte CreateReplaySafeLogger k automatickému vyfiltrování příkazů protokolu během přehrávání:

[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!");
}

Při protokolování bezpečném proti opakování je výstup protokolu následující:

Calling F1.
Calling F2.
Calling F3.
Done!

Stav vlastní orchestrace

Pomocí vlastního stavu orchestrace můžete hlásit průběh pracovního postupu externím klientům. Mezi běžné vzory patří procenta dokončení, popisy kroků a souhrny chyb. Externí klienti můžou zobrazit vlastní stav prostřednictvím rozhraní API pro dotazy na stav HTTP nebo volání rozhraní API specifického pro jazyk.

Následující kód ukazuje, jak nastavit vlastní hodnotu stavu ve funkci orchestrátoru:

[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...
}

Note

Předchozí příklad jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x je nutné použít DurableOrchestrationContext místo IDurableOrchestrationContext. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions .

Když je orchestrace spuštěná, můžou externí klienti načíst tento vlastní stav:

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

Klienti obdrží následující odpověď:

{
  "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"
}

Warning

Vlastní stavový payload je omezen na 16 KB JSON textu UTF-16, protože se musí vejít do základního úložiště metadat za běhu. U aplikací podporovaných Azure Storage je tento limit vázán na Azure Table Storage. Pokud vaše aplikace používá Durable Task Scheduler nebo jiný backend, použijte externí úložiště, pokud potřebujete větší payload.

Debugging

Azure Functions podporuje ladění kódu funkce přímo a stejná podpora se přenese do Durable Functions bez ohledu na to, jestli běží v Azure nebo místně. Pro nejlepší zážitek z ladění použijte následující pracovní postup:

  1. Spusťte novou ladicí relaci s novým centrem úloh nebo vymažte obsah centra úloh mezi relacemi. Zbývající zprávy z předchozích spuštění můžou způsobit neočekávané opětovné spuštění.

  2. Nastavte zarážky ve funkcích orchestrátoru nebo aktivit. U funkcí orchestrátoru použijte podmíněnou zarážku, která se přeruší jenom v případě, že hodnota "přehrává se" je false, aby se během opakovaného přehrávání zabránilo vícenásobnému dosažení stejné zarážky.

  3. Procházejte kód, jak je běžné. Mějte na paměti následující chování:

    • Replay:
      Funkce orchestratoru se pravidelně opakují při přijetí nových vstupů. Jedno logické spuštění funkce orchestrátoru může vést k vícenásobnému dosažení stejné zarážky, zejména pokud je nastavená dříve v kódu funkce.

    • Čekají:
      Jakmile se ve funkci orchestrátoru objeví await, vrátí řízení zpět dispečeru Durable Task Framework. Pokud dojde k prvnímu zobrazení konkrétního await úkolu, přidružený úkol se nikdy neobnoví . Vzhledem k tomu, že se úloha nikdy neobnoví, není možné přeskočit operátor await (F10 ve Visual Studiu). Krokování funguje jenom tehdy, když je úkol přehráván.

    • Časové limity zasílání zpráv:
      Durable Functions interně používá zprávy fronty k řízení provádění orchestrátoru, aktivity a funkcí entit. V prostředí s více virtuálními počítači mohou delší ladicí relace způsobit, že zprávu zpracuje jiný virtuální počítač, což vede k duplicitnímu spuštění. Ačkoli toto chování existuje také pro standardní funkce triggeru fronty, je důležité tento kontext zdůraznit, protože fronty jsou implementační detail.

    • Zastavení a spuštění:
      Zprávy v rámci Durable Functions se uchovávají mezi relacemi ladění. Pokud zastavíte ladění a ukončíte místní hostitelský proces během spuštění trvalé funkce, může se tato funkce v budoucí relaci ladění automaticky znovu spustit.

Další nástroje

Zkontrolujte stav backendu

Pro aplikace, které používají doporučený backend Durable Task Scheduler, začněte s dashboardem Durable Task Scheduler, Application Insights a portálem Azure pro kontrolu stavu orchestrace a zpráv. Pokud vaše aplikace používá poskytovatele Azure Storage, můžete také kontrolovat stav orchestrace a zprávy pomocí nástrojů jako Microsoft Průzkumník služby Azure Storage.

Snímek obrazovky z Průzkumník služby Azure Storageu zobrazující stav orchestrací Durable Functions v tabulkách a frontách.

Warning

I když je vhodné vidět historii spouštění v úložišti tabulek, vyhněte se závislostem na této tabulce. S vývojem rozšíření Durable Functions se to může změnit.

Note

Toto doporučení je nejrelevantnější, když vaše aplikace používá poskytovatele Azure Storage. Pokud vaše aplikace používá Durable Task Scheduler, plánovač spravuje základní stav, takže dashboard, Application Insights a Azure portál jsou nejdůležitější nástroje pro inspekci. Můžete také nastavit jiné poskytovatele úložišť; V závislosti na poskytovateli úložišti nastaveném pro vaši aplikaci možná budete muset použít různé nástroje pro kontrolu základního stavu.

Monitor odolných funkcí

Durable Functions Monitor je grafický nástroj pro monitorování, správu a ladění orchestrace a instancí entit. Je k dispozici jako rozšíření Visual Studio Code nebo samostatná aplikace. Pokyny k nastavení a seznam funkcí najdete na Wiki Durable Functions Monitor.

Diagnostika portálu Azure

Portál Azure poskytuje integrované diagnostické nástroje pro vaše aplikace funkcí.

Diagnostika a řešení problémů: Azure Function App Diagnostics je užitečný prostředek pro monitorování a diagnostiku potenciálních problémů ve vaší aplikaci. Poskytuje také návrhy, které vám pomůžou vyřešit problémy na základě diagnózy. Další informace najdete v tématu Diagnostika aplikace funkcí Azure.

Trasování orchestrace: Portál Azure poskytuje podrobné informace o trasování orchestrace, které vám pomohou porozumět stavu jednotlivých instancí orchestrace a end-to-end provedení. Když si v aplikaci Azure Functions zobrazíte seznam funkcí, tak se zobrazí sloupec Monitor obsahující odkazy na sledování. Abyste mohli získat přístup k tomuto informacím, musíte mít pro vaši aplikaci povolenou službu Application Insights.

Analyzátor Roslyn

Analyzátor Durable Functions Roslyn je živý analyzátor kódu, který vede vývojáře jazyka C#, aby sledovali Durable Functions konkrétní omezení kódu. Pokyny k povolení v Visual Studio a Visual Studio Code najdete v tématu Durable Functions Roslyn Analyzer.

Troubleshooting

Chcete-li vyřešit běžné problémy, jako jsou zablokované orchestrace, nedaří se spustit nebo běží pomalu, přečtěte si v průvodci odstraňování potíží Durable Functions.

Další kroky