Monitorando aplicativos usando MSAL.NET

Para garantir que os serviços de autenticação usando MSAL.NET estejam em execução corretamente, a MSAL fornece várias maneiras de monitorar seu comportamento para que os problemas possam ser identificados e resolvidos antes que ocorram na produção. O uso incorreto da MSAL (no que diz respeito ao ciclo de vida do token e ao cache) não leva a falhas imediatas, no entanto, às vezes, elas surgirão em cenários de alto tráfego depois que o aplicativo estiver em produção por um período de tempo.

Por exemplo, se apenas uma instância de um aplicativo cliente confidencial for usada e a MSAL não estiver configurada para serializar o cache de token, o cache crescerá para sempre. Outro problema surge ao criar um novo aplicativo cliente confidencial e não utilizar o cache, o que levará a problemas como a limitação do provedor de identidade. Para obter recomendações sobre como utilizar a MSAL adequadamente, consulte Alta Disponibilidade.

Logging

Uma das ferramentas que a MSAL fornece para combater problemas de produção é registrar erros quando a MSAL não estiver configurada corretamente. É fundamental habilitar o registro em log sempre que possível para monitorar os logs em busca de erros e ajudar no diagnóstico de eventos problemáticos. Consulte Registro em log no MSAL.NET para obter detalhes.

Os seguintes erros serão registrados na MSAL:

• Ao usar uma autoridade que termina em /common ou /organizations para autenticação de credencial de cliente (AcquireTokenForClient(IEnumerable<String>)).
  • A autoridade atual está direcionada ao ponto de extremidade /common ou /organizations, o que não é recomendado. Consulte os fluxos de credenciais do cliente para obter mais detalhes.
• Quando o cache de token interno padrão é usado ao usar aplicativos cliente confidenciais.
  • O cache de token padrão fornecido pela MSAL não foi projetado para ser executado quando usado em aplicativos cliente confidenciais. Consulte a serialização de cache de token em MSAL.NET para obter mais detalhes.

Métricas

Além do registro em log, a MSAL expõe métricas importantes em AuthenticationResult.AuthenticationResultMetadata. Consulte Adicionar monitoramento às operações do MSAL para obter mais detalhes.

• DurationTotalInMs - tempo total gasto na MSAL adquirindo um token, incluindo chamadas de rede e operações de cache. Crie um alerta sobre a alta latência geral (mais de 1 segundo). Observe que a primeira chamada de aquisição de token geralmente faz uma chamada HTTP extra.

• DurationInCacheInMs - tempo gasto carregando ou salvando o cache de token, que é personalizado pelo desenvolvedor do aplicativo (por exemplo, salvar no Redis). Crie um alerta sobre picos.

  Note

  Para entender como personalizar o cache de token, consulte a serialização de cache de token em MSAL.NET.

• DurationInHttpInMs - tempo gasto fazendo chamadas HTTP para o provedor de identidade. Crie um alerta sobre picos.

• TokenSource- indica a origem do token – normalmente, o cache ou o provedor de identidade. Os tokens são recuperados do cache muito mais rápido (por exemplo, ~100 ms versus ~700 ms). Essa métrica pode ser utilizada para monitorar a taxa de acertos do cache.

• CacheRefreshReason – especifica o motivo para buscar o token de acesso do provedor de identidade. Consulte CacheRefreshReason. Use em conjunto com TokenSource.

• TokenEndpoint - o URI real do endpoint de token usado para obter o token. Útil para entender como a MSAL resolve o locatário em chamadas silenciosas e a região em chamadas regionais.

  Note

  A regionalização está disponível apenas para aplicativos Microsoft internos.

• RegionDetails - os detalhes sobre a região usada para fazer chamadas, como a região usada e qualquer erro de detecção automática.

  Note

  A regionalização está disponível apenas para aplicativos Microsoft internos.

OpenTelemetry

A partir da MSAL 4.58.0, a biblioteca dá suporte ao OpenTelemetry – um conjunto de APIs que habilitam a instrumentação, a geração e a coleta de dados de telemetria de maneira consistente e padronizada. Para começar, verifique se você;

1. Instale a versão mais recente do MSAL.NET.
2. Adicione a dependência do pacote OpenTelemetry ao seu projeto.
3. Adicione uma dependência de exportador que permite exportar logs, por exemplo, o exportador de console para OpenTelemetry.NET.

No código de inicialização do aplicativo, antes de inicializar o cliente de autenticação MSAL (por exemplo, PublicClientApplication ou ConfidentialClientApplication), declare uma nova MeterProvider instância usando o código a seguir.

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

Isso inicializará o provedor de métricas e usará o medidor do MSAL.NET (MicrosoftIdentityClient_Common_Meter) integrado, que captura uma série de contadores e histogramas. Quando um exportador de console é usado, você deve ver a saída sendo canalizada diretamente no terminal:

A seção a seguir descreve os contadores e histogramas com suporte para o medidor padrão.

Contadores

msalsuccess_counter

Contador que captura a agregação de solicitações bem-sucedidas na MSAL.

Metadados

msalfailure_counter

Contador para registrar a agregação de solicitações com falha na MSAL.

Metadados

Histogramas

MsalTotalDuration_1a_histogram

Histograma para capturar a latência total em milissegundos para aquisição de token por meio da MSAL.

Metadados

MsalDurationInL1CacheInUs_1b_histogram

Histograma para capturar latência quando um cache L1 é usado. Os valores estão em microssegundos para aquisição de token por meio da MSAL.

Metadados

MsalDurationInL2Cache_1a_histogram

Histograma para capturar a latência de cache L2 em milissegundos para aquisição de token por meio da MSAL.

Metadados

MsalDurationInHttp_1a_histogram

Histograma para capturar a latência HTTP em milissegundos para aquisição de token por meio da MSAL.

Metadados

Informações adicionais

Para obter informações adicionais sobre o uso do OpenTelemetry com aplicativos .NET, consulte .NET observabilidade com o OpenTelemetry.