Monitoraggio delle applicazioni tramite MSAL.NET

Per garantire che i servizi di autenticazione che usano MSAL.NET vengano eseguiti correttamente, MSAL offre molti modi per monitorarne il comportamento, in modo che i problemi possano essere identificati e risolti prima che si verifichino nell'ambiente di produzione. L'uso non corretto di MSAL (per quanto riguarda il ciclo di vita dei token e la cache) non causa problemi immediati; tuttavia, a volte questi possono emergere in condizioni di traffico elevato dopo che l'app è rimasta in produzione per un certo periodo di tempo.

Ad esempio, se viene usata una sola istanza di un'applicazione client riservata e MSAL non è configurato per serializzare la cache dei token, la cache crescerà per sempre. Un altro problema si verifica quando si crea una nuova applicazione client confidenziale senza utilizzare la cache, il che comporterà problemi come la limitazione delle richieste da parte del provider di identità. Per consigli su come usare MSAL in modo appropriato, vedere Disponibilità elevata.

Logging

Uno degli strumenti forniti da MSAL per combattere i problemi di produzione è la registrazione degli errori quando MSAL non è configurato correttamente. È fondamentale abilitare la registrazione ogni volta che è possibile monitorare i log per individuare gli errori e facilitare la diagnosi di eventi problematici. Per informazioni dettagliate, vedere Registrazione in MSAL.NET.

Gli errori seguenti verranno registrati in MSAL:

• Quando si usa un'autorità che termina con /common o /organizations per l'autenticazione con credenziali client (AcquireTokenForClient(IEnumerable<String>)).
  • L'autorità attuale sta puntando all'endpoint /common o /organizations, operazione non consigliata. Per altri dettagli, vedere Flussi di credenziali client .
• Quando la cache dei token interna predefinita viene usata durante l'uso di applicazioni client riservate.
  • La cache dei token predefinita fornita da MSAL non è progettata per essere efficiente quando usata nelle applicazioni client riservate. Per altri dettagli, vedere Serializzazione della cache dei token in MSAL.NET.

Metriche

Oltre alla registrazione, MSAL espone metriche importanti in AuthenticationResult.AuthenticationResultMetadata. Per altri dettagli, vedere Aggiungere il monitoraggio per le operazioni MSAL .

• DurationTotalInMs - tempo totale dedicato all'acquisizione di un token in MSAL, incluse le chiamate di rete e le operazioni della cache. Creare un avviso sulla latenza complessiva elevata (più di 1 secondo). Si noti che la prima chiamata di acquisizione di token in genere effettua una chiamata HTTP aggiuntiva.

• DurationInCacheInMs - tempo impiegato per il caricamento o il salvataggio della cache dei token, che viene personalizzato dallo sviluppatore dell'app (ad esempio, salva in Redis). Creare un avviso in caso di picchi.

  Note

  Per informazioni su come personalizzare la memorizzazione nella cache dei token, vedere Serializzazione della cache dei token in MSAL.NET.

• DurationInHttpInMs - tempo impiegato per effettuare chiamate HTTP al provider di identità. Crea un avviso in caso di picchi.

• TokenSource- indica l'origine del token, in genere la cache o il provider di identità. I token vengono recuperati dalla cache molto più velocemente ,ad esempio ~100 ms rispetto a ~700 ms. Questa metrica può essere usata per monitorare il rapporto di riscontri nella cache.

• CacheRefreshReason : specifica il motivo del recupero del token di accesso dal provider di identità. Vedete CacheRefreshReason. Usare insieme a TokenSource.

• TokenEndpoint : l'URI effettivo dell'endpoint del token usato per recuperare il token. Utile per comprendere come MSAL risolve il tenant nelle chiamate silenziose e l'area geografica nelle chiamate regionali.

  Note

  La regionalizzazione è disponibile solo per le applicazioni Microsoft interne.

• RegionDetails : i dettagli sull'area usata per effettuare chiamate, ad esempio l'area usata e qualsiasi errore di rilevamento automatico.

  Note

  La regionalizzazione è disponibile solo per le applicazioni Microsoft interne.

OpenTelemetry

A partire da MSAL 4.58.0, la libreria supporta OpenTelemetry , ovvero un set di API che consentono la strumentazione, la generazione e la raccolta di dati di telemetria in modo coerente e standardizzato. Per iniziare, assicurati di:

1. Installare la versione più recente di MSAL.NET.
2. Aggiungere la dipendenza del pacchetto OpenTelemetry al progetto.
3. Aggiungere una dipendenza di esportazione che consente di esportare i log, ad esempio l'utilità di esportazione della console per OpenTelemetry.NET.

Nel codice di inizializzazione dell'applicazione, prima di eseguire il bootstrap del client di autenticazione MSAL (ad esempio, PublicClientApplication o ConfidentialClientApplication), dichiarare una nuova MeterProvider istanza usando il codice seguente.

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter("MicrosoftIdentityClient_Common_Meter")
    .AddConsoleExporter()
    .Build();

Verrà inizializzato il provider di contatori e verrà usato il contatore MSAL.NET predefinito (MicrosoftIdentityClient_Common_Meter) che acquisisce una serie di contatori e istogrammi. Quando si usa un esportatore della console, dovresti vedere l'output indirizzato direttamente al terminale:

Nella sezione seguente vengono descritti i contatori e gli istogrammi supportati per il contatore predefinito.

Contatori

msalsuccess_counter

Contatore per registrare l'aggregazione delle richieste completate con successo in MSAL.

Metadata

msalfailure_counter

Contatore per rilevare il conteggio aggregato delle richieste non riuscite in MSAL.

Metadata

Istogrammi

MsalTotalDuration_1a_histogram

Istogramma per acquisire la latenza totale in millisecondi per l'acquisizione di token tramite MSAL.

Metadata

MsalDurationInL1CacheInUs_1b_histogram

Istogramma per acquisire la latenza quando viene usata una cache L1. I valori sono in microsecondi per l'acquisizione di token tramite MSAL.

Metadata

MsalDurationInL2Cache_1a_histogram

Istogramma per acquisire la latenza della cache L2 in millisecondi per l'acquisizione di token tramite MSAL.

Metadata

MsalDurationInHttp_1a_histogram

Istogramma per acquisire la latenza HTTP in millisecondi per l'acquisizione di token tramite MSAL.

Metadata

Informazioni aggiuntive

Per altre informazioni sull'uso di OpenTelemetry con applicazioni .NET, vedere .NET osservabilità con OpenTelemetry.