Registrazione in Gridwich

Azure

Le procedure consigliate per la registrazione includono:

  • Non usare la formattazione o l'interpolazione di stringhe. La registrazione di una stringa con $"This broke {brokenThing}" non è utile per il debug.

  • Passare oggetti in modo che diventino campi ricercabili.

    Invece di LogInformation(LogEventIds.StartProcessing, $"Processing has started on item {Item.itemNumber}");, usare:

    • Oggetto come tale, ad esempio LogInformationObject(LogEventIds.StartProcessing, Item);, o
    • Oggetti anonimi, ad esempio LogInformationObject(LogEventIds.StartProcessing, new {Item.itemNumber, Item.itemDescription, someData});.

  • Seguire le convenzioni di numerazione EventId descritte in LogEventIds.

  • Per qualsiasi corpo significativo di lavoro, usare il modello di registrazione seguente:

    • Usare LogInformationObject per la voce, ad esempio quando si sta per avviare un processo di codifica.
    • Usare LogInformationObject in caso di esito positivo, ad esempio quando il processo di codifica ha esito positivo.
    • Usare LogWarningObject, LogErrorObjecto LogCriticalObject in caso di errore, ad esempio se il processo di codifica non riesce. Se applicabile, usare varianti del metodo Exception.

  • Anche se è possibile registrare qualsiasi informazione in qualsiasi fase, non inquinare i log con rumore estraneo.

ObjectLogger

ObjectLogger con IObjectLogger è una piccola utilità wrapper per logger/ILogger standard. Questa utilità one-liner registra qualsiasi oggetto C# convertendo gli oggetti C# in oggetti dizionari che il logger può utilizzare.

ObjectLogger/IObjectLogger limita l'uso di metodi logger che non dispongono EventIds di un modello di adattatore anziché di ereditarietà. Questa restrizione impone agli sviluppatori di usare EventIds, utili per il debug.

Altre raccomandazioni per l'uso di ObjectLogger includono:

  • Non ignorare IObjectLogger usando ILogger.
  • Usare IObjectLogger con il tipo appropriato per la classe : IObjectLogger<myClass>.
  • In qualsiasi blocco catch di gestione delle eccezioni usare i metodi IObjectLogger che includono eccezioni. I provider di registrazione come Application Insights possono usare le informazioni sulle eccezioni.

Schema e dati di registrazione

L'infrastruttura di runtime di Griglia di eventi sottostante fornisce uno schema di base. Lo schema di eventi di Griglia di eventi include l'ora dell'evento, il dispositivo di origine, il livello di gravità e il messaggio stringa. Le proprietà personalizzate predefinite di Logger/ILogger includono EventId, Categorye RequestPath.

Oggetti contesto

Per usare API e flussi di lavoro complessi che richiedono diversi input e output, è possibile creare un oggetto contesto, ovvero un contenitore di proprietà di variabili importanti che il codice può passare o generare. Gli oggetti contesto possono gestire molti parametri e le firme dei metodi non devono essere modificate quando si aggiungono o rimuovono parametri. È anche possibile passare oggetti di contesto al logger e ad altre interfacce come unità.

Ad esempio, anziché:

var store = new StorageBlob();
var tier = req.Query["tier"];
var result = await store.SetBlobStorageTier(blobName, tier);
logger.LogInformationObject(LogEventIds.setBlobProperties, result);

È possibile codificare:

var storageContext = new StorageContext();
storageContext.Store = new StorageBlob();
storageContext.Tier = req.Query["tier"];
storageContext.Result = await store.SetBlobStorageTier(blobName, storageContext.Tier);
logger.LogInformationObject(LogEventIds.setBlobProperties, storageContext);

Livelli di registrazione

L'assegnazione del livello di registrazione appropriato potrebbe non essere semplice. Le descrizioni generali seguenti dei livelli di log provengono da LogLevel Enum.

Loglevel Enum Descrizione
LogTrace 0 Contiene i messaggi più dettagliati e può contenere dati sensibili dell'applicazione. Questi messaggi vengono disattivati per impostazione predefinita e non devono essere attivati in un ambiente di produzione.
LogDebug 1 Usato per l'analisi interattiva durante lo sviluppo. Questi log contengono principalmente informazioni utili per il debug e non hanno alcun valore a lungo termine.
LogInformation 2 Tiene traccia del flusso generale dell'applicazione. Questi log devono avere un valore a lungo termine.
LogWarning 3 Evidenzia un evento anomalo o imprevisto nel flusso dell'applicazione, ma non arresta l'esecuzione dell'applicazione.
LogError 4 Registra quando il flusso di esecuzione corrente viene arrestato a causa di un errore. Questi log devono indicare errori nell'attività corrente, non un errore a livello di applicazione.
LogCritical 5 Descrive un'applicazione o un arresto anomalo del sistema irreversibile o un errore irreversibile che richiede attenzione immediata.
LogNone 6 Non usato per la scrittura di messaggi di log. Specifica che una categoria di registrazione non deve scrivere messaggi.

Passaggi successivi

Documentazione sui prodotti:

Moduli di Microsoft Learn: