Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Important
Support pro model v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovních procesů pro plnou podporu.
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:
- Konfigurace sledování Application Insights pro události životního cyklu
- Orchestrace instancí dotazů s využitím Kusta
- Povolení protokolování DTFx (Durable Task Framework) pro diagnostiku nízké úrovně
- Nastavení distribuovaného trasování pro vizualizaci kompletních toků orchestrace
- Zápis protokolů bezpečných pro přehrání do funkcí orchestratoru
- Hlášení stavu vlastní orchestrace externím klientům
- Místní ladění orchestrací pomocí zarážek
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í.
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.
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.
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í:
- Pro izolované aplikace .NET Microsoft.Azure.Functions.Worker.Extensions.DurableTask>= v1.4.0.
- V případě non-.NET aplikací podle těchto pokynů prozatím ručně nainstalujte Microsoft.Azure.WebJobs.Extensions.DurableTask>= v3.2.0 . Distribuované trasování bude dostupné v sadách rozšíření >v4.24.x.
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.
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:
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í.
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.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íhoawaitú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.
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.