Monitorowanie aplikacji przy użyciu MSAL.NET

Aby zapewnić prawidłowe działanie usług uwierzytelniania opartych na MSAL.NET, biblioteka MSAL udostępnia wiele sposobów śledzenia ich działania, dzięki czemu problemy można identyfikować i rozwiązywać, zanim wystąpią w środowisku produkcyjnym. Nieprawidłowe użycie biblioteki MSAL (w kontekście cyklu życia tokenu i pamięci podręcznej) nie prowadzi do natychmiastowych błędów, jednak czasami problemy te ujawniają się przy dużym natężeniu ruchu, gdy aplikacja działa już od pewnego czasu w środowisku produkcyjnym.

Jeśli na przykład używane jest tylko jedno wystąpienie poufnej aplikacji klienckiej, a biblioteka MSAL nie jest skonfigurowana do serializacji pamięci podręcznej tokenów, pamięć podręczna będzie rosnąć bez końca. Inny problem pojawia się podczas tworzenia nowej aplikacji klienta poufnego i niekorzystania z pamięci podręcznej, co prowadzi do problemów, takich jak ograniczanie liczby żądań przez dostawcę tożsamości. Aby uzyskać zalecenia dotyczące odpowiedniego korzystania z biblioteki MSAL, zobacz Wysoka dostępność.

Logging

Jednym z narzędzi udostępnianych przez bibliotekę MSAL do rozwiązywania problemów występujących w środowisku produkcyjnym jest rejestrowanie błędów, gdy MSAL nie jest prawidłowo skonfigurowana. Włączenie rejestrowania zawsze, gdy jest to możliwe, ma kluczowe znaczenie dla monitorowania dzienników pod kątem błędów i pomocy w diagnozowaniu problematycznych zdarzeń. Aby uzyskać szczegółowe informacje, zobacz Rejestrowanie w MSAL.NET.

Następujące błędy zostaną zarejestrowane w usłudze MSAL:

• W przypadku używania urzędu certyfikacji kończącego się na /common lub /organizations do uwierzytelniania poświadczeń klienta (AcquireTokenForClient(IEnumerable<String>)).
  • Bieżący autorytet wskazuje na punkt końcowy /common lub /organizations, co nie jest zalecane. Aby uzyskać więcej informacji, zobacz Przepływy poświadczeń klienta .
• Gdy domyślna wewnętrzna pamięć podręczna tokenów jest używana podczas korzystania z poufnych aplikacji klienckich.
  • Domyślna pamięć podręczna tokenów udostępniana przez bibliotekę MSAL nie została zaprojektowana z myślą o wysokiej wydajności w poufnych aplikacjach klienckich. Aby uzyskać więcej informacji, zobacz Serializacja pamięci podręcznej tokenów w MSAL.NET.

Metrics

Oprócz rejestrowania biblioteka MSAL uwidacznia ważne metryki w pliku AuthenticationResult.AuthenticationResultMetadata. Więcej informacji znajduje się w artykule Dodawanie monitorowania dla operacji MSAL.

• DurationTotalInMs — całkowity czas spędzony na uzyskiwaniu tokenu przez bibliotekę MSAL, w tym wywołania sieciowe i operacje pamięci podręcznej. Utwórz alert dotyczący ogólnego dużego opóźnienia (więcej niż 1 sekunda). Należy pamiętać, że pierwsze wywołanie pozyskiwania tokenu zwykle wykonuje dodatkowe wywołanie HTTP.

• DurationInCacheInMs — czas poświęcony na ładowanie lub zapisywanie pamięci podręcznej tokenów, konfigurowanej przez dewelopera aplikacji (na przykład poprzez zapis w usłudze Redis). Utwórz alert w przypadku nagłych wzrostów.

  Note

  Aby dowiedzieć się, jak dostosować buforowanie tokenów, zobacz Serializacja pamięci podręcznej tokenów w MSAL.NET.

• DurationInHttpInMs — czas poświęcony na wykonywanie wywołań HTTP do dostawcy tożsamości. Utwórz alert o nagłych wzrostach.

• TokenSource— wskazuje źródło tokenu — zazwyczaj pamięć podręczną lub dostawcę tożsamości. Tokeny są pobierane z pamięci podręcznej znacznie szybciej (na przykład ~100 ms w porównaniu z ok. 700 ms). Ta metryka może służyć do monitorowania współczynnika trafień pamięci podręcznej.

• CacheRefreshReason — określa przyczynę pobierania tokenu dostępu od dostawcy tożsamości. Zobacz: CacheRefreshReason. Użyj w połączeniu z TokenSource.

• TokenEndpoint — rzeczywisty adres URI punktu końcowego tokena używany do pobrania tokena. Przydatne do zrozumienia, jak biblioteka MSAL określa dzierżawcę w wywołaniach nieinteraktywnych i region w wywołaniach regionalnych.

  Note

  Regionalizacja jest dostępna tylko dla aplikacji Microsoft wewnętrznych.

• RegionDetails — szczegółowe informacje o regionie używanym do nawiązywania połączenia, takie jak używany region i wszelkie błędy automatycznego wykrywania.

  Note

  Regionalizacja jest dostępna tylko dla aplikacji Microsoft wewnętrznych.

OpenTelemetry

Począwszy od biblioteki MSAL 4.58.0, biblioteka obsługuje bibliotekę OpenTelemetry — zestaw interfejsów API, które umożliwiają instrumentację, generowanie i zbieranie danych telemetrycznych w spójny i ustandaryzowany sposób. Aby rozpocząć, upewnij się, że:

1. Zainstaluj najnowszą wersję MSAL.NET.
2. Dodaj zależność pakietu OpenTelemetry do projektu.
3. Dodaj zależność dla eksportera, która umożliwia eksportowanie logów, na przykład eksporter konsoli dla OpenTelemetry.NET.

W kodzie inicjowania aplikacji przed uruchomieniem klienta uwierzytelniania MSAL (np PublicClientApplication . lub ConfidentialClientApplication) zadeklaruj nowe MeterProvider wystąpienie przy użyciu następującego kodu.

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

Spowoduje to zainicjowanie dostawcy metryk i użycie wbudowanego miernika MSAL.NET (MicrosoftIdentityClient_Common_Meter), który rejestruje serię liczników i histogramów. Gdy jest używany eksporter konsoli, powinny zostać wyświetlone dane wyjściowe przesyłane potokiem bezpośrednio w terminalu:

W poniższej sekcji opisano obsługiwane liczniki i histogramy dla miernika domyślnego.

Counters

msalsuccess_counter

Licznik do rejestrowania zbiorczej liczby pomyślnie zakończonych żądań w MSAL.

Metadata

msalfailure_counter

Licznik do przechwytywania agregacji żądań, które zakończyły się niepowodzeniem w usłudze MSAL.

Metadata

Histogramy

MsalTotalDuration_1a_histogram

Histogram do rejestrowania całkowitego opóźnienia w milisekundach podczas uzyskiwania tokenu za pośrednictwem MSAL.

Metadata

MsalDurationInL1CacheInUs_1b_histogram

Histogram rejestrujący opóźnienia przy użyciu pamięci podręcznej L1. Wartości są podane w mikrosekundach dla uzyskiwania tokenu przy użyciu biblioteki MSAL.

Metadata

MsalDurationInL2Cache_1a_histogram

Histogram przedstawiający opóźnienie pamięci podręcznej L2 w milisekundach podczas pozyskiwania tokenu przy użyciu biblioteki MSAL.

Metadata

MsalDurationInHttp_1a_histogram

Histogram rejestrujący opóźnienie HTTP w milisekundach podczas uzyskiwania tokenu przez bibliotekę MSAL.

Metadata

Dodatkowe informacje

Aby uzyskać dodatkowe informacje na temat używania OpenTelemetry w aplikacjach .NET, zobacz Obserwowalność w środowisku .NET z użyciem OpenTelemetry.