Procedure consigliate e strumenti di diagnostica per Durable Functions
Questo articolo illustra in dettaglio alcune procedure consigliate per l'uso di Durable Functions. Descrive anche vari strumenti per diagnosticare i problemi durante l'uso di produzione, test e sviluppo.
Procedure consigliate
Usare l'ultima versione dell'estensione Durable Functions e dell'SDK
Esistono due componenti usati da un'app per le funzioni per eseguire Durable Functions. Uno è l'SDK Durable Functions, che consente di scrivere funzioni di orchestrazione, attività ed entità usando il linguaggio di programmazione di destinazione. L'altro è l'estensione Durable, che è il componente di runtime che esegue effettivamente il codice. Ad eccezione delle app in-process .NET, le versioni dell'SDK e dell'estensione vengono gestite in modo indipendente.
Rimanere aggiornati con l'estensione e l'SDK più recenti garantisce che l'applicazione tragga vantaggio dai miglioramenti, dalle funzionalità e dalle correzioni di bug più recenti. L'aggiornamento alle versioni più recenti garantisce anche che Microsoft possa raccogliere i dati di telemetria di diagnostica più recenti per accelerare il processo di indagine quando si apre un caso di supporto con Azure.
- Per istruzioni su come ottenere la versione più recente dell'estensione, vedere Aggiornare la versione dell'estensione Durable Functions.
- Per assicurarsi di usare la versione più recente dell'SDK, controllare la gestione pacchetti della lingua in uso.
Rispettare i vincoli di codice di Durable Functions
Il comportamento di ripetizione del codice di orchestrazione crea vincoli al tipo di codice che è possibile scrivere in una funzione dell'agente di orchestrazione. Un esempio di vincolo è che la funzione dell'agente di orchestrazione deve usare API deterministiche in modo che a ogni ripetizione venga riprodotto lo stesso risultato.
Nota
L'analizzatore Roslyn di Durable Functions è un analizzatore di codice in tempo reale che guida gli utenti C# a rispettare vincoli di codice specifici di Durable Functions. Per istruzioni su come abilitarlo in Visual Studio e Visual Studio Code, vedere Analizzatore Roslyn di Durable Functions.
Acquisire familiarità con le impostazioni delle prestazioni di Funzioni di Azure del linguaggio di programmazione
Usando le impostazioni predefinite, il runtime del linguaggio selezionato può imporre restrizioni rigorose di concorrenza sulle funzioni. Ad esempio, consentendo l'esecuzione di 1 sola funzione alla volta in una determinata macchina virtuale. Queste restrizioni in genere possono essere ridotte ottimizzando le impostazioni di concorrenza e prestazioni della lingua. Se si desidera ottimizzare le prestazioni dell'applicazione Durable Functions, è necessario acquisire familiarità con queste impostazioni.
Di seguito è riportato un elenco non esaustivo di alcune delle lingue che spesso traggono vantaggio dall'ottimizzazione delle impostazioni di concorrenza e prestazioni e delle relative linee guida per farlo.
Garantire nomi univoci dell'hub attività per app
Più app Durable Functions possono condividere un account di archiviazione. Per impostazione predefinita, il nome dell'app viene usato come nome dell'hub attività, il che garantisce che la condivisione accidentale degli hub attività non venga eseguita. Se è necessario configurare in modo esplicito i nomi dell'hub attività per le app in host.json, è necessario assicurarsi che i nomi siano univoci. In caso contrario, le app multiple saranno in competizione per i messaggi, il che potrebbe comportare un comportamento non definito, tra cui orchestrazioni che si bloccano in modo imprevisto nello stato In sospeso o In esecuzione.
L'unica eccezione è se si distribuiscono copie della stessa app in più aree; in questo caso, è possibile usare lo stesso hub attività per le copie.
Seguire il materiale sussidiario per la distribuzione delle modifiche al codice agli agenti di orchestrazione in esecuzione
Per la durata di un'applicazione è comune che vengano aggiunte, rimosse e modificate funzioni. Esempi di modifiche di rilievo comuni sono la modifica delle firme delle funzioni di attività o entità e la modifica della logica dell'agente di orchestrazione. Queste modifiche sono un problema quando influiscono sulle orchestrazioni ancora in esecuzione. Se le modifiche al codice vengono distribuite in modo non corretto, le orchestrazioni potrebbero avere esito negativo con un errore non deterministico, rimanere bloccate a tempo indeterminato, subire una riduzione del livello delle prestazioni e così via. Quando si apportano modifiche al codice che potrebbero influire sull'esecuzione delle prestazioni, fare riferimento alle strategie di mitigazione.
Mantenere gli input e gli output della funzione di dimensioni più ridotte possibili
È possibile che si verifichino problemi di memoria se si forniscono input e output di grandi dimensioni da e verso le API Durable Functions.
Gli input e gli output nelle API Durable Functions vengono serializzati nella cronologia dell'orchestrazione. Questo significa che, nel corso del tempo, gli input e gli output di grandi dimensioni possono contribuire notevolmente a una crescita incontrollata della cronologia dell'agente di orchestrazione, che rischia di causare eccezioni di memoria durante la ripetizione.
Per ridurre l'impatto di input e output di grandi dimensioni nelle API, è possibile scegliere di delegare alcune operazioni agli agenti di orchestrazione secondari. Ciò consente di bilanciare il carico di memoria della cronologia da uno solo a più agenti di orchestrazione, mantenendo quindi un footprint di memoria ridotto per le singole cronologie.
Detto questo, la procedura consigliata per gestire dati di grandi dimensioni consiste nel mantenerli nell'archiviazione esterna e materializzare solo i dati all'interno delle attività, quando necessario. Quando si usa questo approccio, invece di comunicare i dati stessi come input e/o output delle API Durable Functions, è possibile passare un identificatore leggero che consente di recuperare i dati da una risorsa di archiviazione esterna quando necessario nelle attività.
Mantenere dati delle entità di piccole dimensioni
Proprio come per gli input e gli output nelle API Durable Functions, se lo stato esplicito di un'entità è troppo grande, è possibile che si verifichino problemi di memoria. In particolare, lo stato di un'entità deve essere serializzato e de-serializzato dall'archiviazione in qualsiasi richiesta, quindi gli stati di grandi dimensioni aggiungono latenza di serializzazione a ogni chiamata. Pertanto, se un'entità deve tenere traccia di dati di grandi dimensioni, è consigliabile eseguire l'offload dei dati nell'archiviazione esterna e tenere traccia di un identificatore leggero nell'entità che consenta di materializzare i dati dall'archiviazione quando necessario.
Ottimizzare le impostazioni di concorrenza di Durable Functions
Una singola istanza del ruolo di lavoro può eseguire più elementi di lavoro contemporaneamente per aumentare l'efficienza. Tuttavia, l'elaborazione simultanea di troppi elementi di lavoro rischia di esaurire risorse come la capacità della CPU, le connessioni di rete e così via. In molti casi questo non dovrebbe essere un problema perché il ridimensionamento e la limitazione delle operazioni vengono gestiti automaticamente. Detto questo, se si verificano problemi di prestazioni (ad esempio gli agenti di orchestrazione richiedono troppo tempo per terminare, sono bloccati in sospeso e così via) o si eseguono test delle prestazioni, è possibile configurare i limiti di concorrenza nel file host.json.
Nota
Non si tratta di una sostituzione per ottimizzare le impostazioni di concorrenza e prestazioni del runtime del linguaggio in Funzioni di Azure. Le impostazioni di concorrenza di Durable Functions determinano solo la quantità di operazioni che può essere assegnata a una determinata macchina virtuale alla volta, ma non determina il grado di parallelismo nell'elaborazione di tale operazione all'interno della macchina virtuale. Quest'ultima richiede l'ottimizzazione delle impostazioni delle prestazioni del runtime del linguaggio.
Usare nomi univoci per gli eventi esterni
Come le funzioni di attività, gli eventi esterni hanno una garanzia di essere recapitati almeno una volta. Ciò significa che, in determinate rare condizioni (che possono verificarsi durante i riavvii, il ridimensionamento, gli arresti anomali e così via), l'applicazione potrebbe ricevere duplicati dello stesso evento esterno. Pertanto, è consigliabile che gli eventi esterni contengano un ID che ne consenta la deduplica manuale negli agenti di orchestrazione.
Nota
Il provider di archiviazione MSSQL utilizza eventi esterni e aggiorna lo stato dell'agente di orchestrazione in modo transazionale, quindi in tale back-end non dovrebbe esserci alcun rischio di eventi duplicati, a differenza del provider di Archiviazione di Azure predefinito. Detto questo, è comunque consigliabile che gli eventi esterni abbiano nomi univoci in modo che il codice sia portabile tra back-end.
Investire in test di stress
Come per qualsiasi risultato correlato alle prestazioni, le impostazioni di concorrenza ideali e l'architettura dell'app dipendono in definitiva dal carico di lavoro dell'applicazione. È quindi consigliabile investire in un test delle prestazioni che simula il carico di lavoro previsto e usarlo per eseguire esperimenti di prestazioni e affidabilità per l'app.
Evitare dati sensibili in input, output ed eccezioni
Gli input e gli output (incluse le eccezioni) da e verso le API Durable Functions vengono resi persistenti in modo permanente nel provider di archiviazione scelto. Se tali input, output o eccezioni contengono dati sensibili (ad esempio segreti, stringhe di connessione, informazioni personali e così via), chiunque abbia accesso in lettura alle risorse del provider di archiviazione potrà ottenerli. Per gestire in modo sicuro i dati sensibili, è consigliabile che gli utenti recuperino tali dati all'interno delle funzioni di attività da Azure Key Vault o variabili di ambiente e non comunichino mai tali dati direttamente ad agenti di orchestrazione o entità. Questo dovrebbe impedire la perdita di dati sensibili nelle risorse di archiviazione.
Nota
Queste indicazioni si applicano anche all'API dell'agente di orchestrazione CallHttp, che rende persistenti anche i payload di richiesta e risposta nell'archiviazione. Se gli endpoint HTTP di destinazione richiedono l'autenticazione, che può essere sensibile, è consigliabile che siano gli utenti stessi a implementare la chiamata HTTP all'interno di un'attività o usino il supporto dell'identità gestita predefinita offerto da CallHttp, che non rende persistenti le credenziali per l'archiviazione.
Suggerimento
Analogamente, evitare di registrare i dati contenenti segreti, perché chiunque abbia accesso in lettura ai log (ad esempio in Application Insights) sarà in grado di ottenere tali segreti.
Strumenti di diagnostica
Sono disponibili diversi strumenti per diagnosticare i problemi.
Log di Durable Functions e Durable Task Framework
Estensione Durable Functions
L'estensione Durable genera eventi di tracciamento che consentono di tenere traccia dell'esecuzione end-to-end di un'orchestrazione. È possibile individuare e sottoporre a query questi eventi di rilevamento usando lo strumento Application Insights Analytics nel portale di Azure. Il livello di dettaglio dei dati di rilevamento generati può essere configurato nella sezione logger (Funzioni 1.x) o logging (Funzioni 2.0) del file host.json. Vedere i dettagli di configurazione.
Durable Task Framework
A partire dalla versione 2.3.0 dell'estensione Durable, per la raccolta sono disponibili anche i log generati da Durable Task Framework (DTFx) sottostante. Vedere i dettagli su come abilitare questi log.
Portale di Azure
Diagnostica e risoluzione dei problemi
La diagnostica dell'app per le funzioni di Azure è una risorsa utile del portale di Azure per monitorare e diagnosticare potenziali problemi nell'applicazione. Fornisce anche suggerimenti per risolvere i problemi in base alla diagnosi. Vedere Diagnostica dell'app per le funzioni di Azure.
Tracce dell'orchestrazione di Durable Functions
Il portale di Azure fornisce informazioni dettagliate sulle tracce dell'orchestrazione per aiutare a comprendere lo stato di ogni istanza di orchestrazione e tracciare l'esecuzione end-to-end. Quando si esamina l'elenco delle funzioni all'interno dell'app Funzioni di Azure, verrà visualizzata una colonna Monitoraggio che contiene collegamenti alle tracce. Per ottenere queste informazioni, è necessario che Application Insights sia abilitato per l'app.
Estensione Durable Functions Monitor
Si tratta di un'estensione di Visual Studio Code che fornisce un'interfaccia utente per il monitoraggio, la gestione e il debug delle istanze di orchestrazione.
Analizzatore Roslyn
L'analizzatore Roslyn di Durable Functions è un analizzatore di codice in tempo reale che guida gli utenti C# a rispettare vincoli di codice specifici di Durable Functions. Per istruzioni su come abilitarlo in Visual Studio e Visual Studio Code, vedere Analizzatore Roslyn di Durable Functions.
Supporto tecnico
Per domande e supporto, è possibile aprire un ticket in uno dei repository GitHub seguenti. La segnalazione di un bug in Azure, incluse informazioni come gli ID istanza interessati, gli intervalli di tempo in formato UTC che mostrano il problema, il nome dell'applicazione (se possibile) e l'area di distribuzione, velocizza notevolmente le indagini.