Partilhar via

Diagnóstico no Kestrel

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Por Sourabh Shirhatti

Este artigo fornece diretrizes para coletar diagnóstico do Kestrel a fim de ajudar a solucionar problemas. Os tópicos abordados incluem:

  • Registro em log: logs estruturados gravados no Registro em log do .NET Core. ILogger é usado por estruturas de aplicativos para gravar logs e por usuários para seus próprios logs em um aplicativo.
  • Métricas: representação de medidas de dados em intervalos de tempo como, por exemplo, solicitações por segundo. As métricas são emitidas usando o EventCounter e podem ser observadas usando a ferramenta de linha de comando dotnet-counters ou o Application Insights.
  • DiagnosticSource: DiagnosticSource é um mecanismo para registro em log em tempo de produção com conteúdos de dados avançados para consumo dentro do processo. Ao contrário do registro em log, que pressupõe que os dados deixarão o processo e espera dados serializáveis, o DiagnosticSource funciona bem com dados complexos.

Log

Como a maioria dos componentes no ASP.NET Core, o Kestrel usa Microsoft.Extensions.Logging para emitir informações de log. O Kestrel emprega o uso de várias categorias, o que permite que você seja seletivo em quais logs você escuta.

Nome da categoria de registro em log Registro em log de eventos
Microsoft.AspNetCore.Server.Kestrel ApplicationError, ConnectionHeadResponseBodyWrite, ApplicationNeverCompleted, RequestBodyStart, RequestBodyDone, RequestBodyNotEntirelyRead, RequestBodyDrainTimedOut, ResponseMinimumDataRateNotSatisfied, InvalidResponseHeaderRemoved, HeartbeatSlow
Microsoft.AspNetCore.Server.Kestrel.BadRequests ConnectionBadRequest, RequestProcessingError, RequestBodyMinimumDataRateNotSatisfied
Microsoft.AspNetCore.Server.Kestrel.Connections ConnectionAccepted, ConnectionStart, ConnectionStop, ConnectionPause, ConnectionResume, ConnectionKeepAlive, ConnectionRejected, ConnectionDisconnect, NotAllConnectionsClosedGracefully, NotAllConnectionsAborted, ApplicationAbortedConnection
Microsoft.AspNetCore.Server.Kestrel.Http2 Http2ConnectionError, Http2ConnectionClosing, Http2ConnectionClosed, Http2StreamError, Http2StreamResetAbort, HPackDecodingError, HPackEncodingError, Http2FrameReceived, Http2FrameSending, Http2MaxConcurrentStreamsReached
Microsoft.AspNetCore.Server.Kestrel.Http3 Http3ConnectionError, Http3ConnectionClosing, Http3ConnectionClosed, Http3StreamAbort, Http3FrameReceived, Http3FrameSending

Registro em log de conexão

O Kestrel também dá suporte à capacidade de emitir logs de nível Debug para comunicação no nível do byte e pode ser habilitado por ponto de extremidade. Para habilitar o registro em log de conexão, confira Configurar pontos de extremidade para Kestrel

Métricas

As métricas são uma representação de medidas de dados em intervalos de tempo, por exemplo, solicitações por segundo. Os dados de métricas permitem a observação do estado de um aplicativo em um alto nível. As métricas Kestrel são emitidas usando EventCounter.

Observação

Os contadores connections-per-second e tls-handshakes-per-second são nomeados incorretamente. Os contadores:

  • Nem sempre contêm o número de novas conexões ou handshakes TLS por segundo
  • Exiba o número de novas conexões ou handshakes TLS no último intervalo de atualização, conforme solicitado como o consumidor de Eventos por meio do argumento EventCounterIntervalSec no filterPayload para KestrelEventSource.

Recomendamos que os consumidores desses contadores dimensionem o valor da métrica com base no DisplayRateTimeScale de um segundo.

Nome Nome de exibição Descrição
connections-per-second Taxa de conexão O número de novas conexões de entrada por intervalo de atualização
total-connections Total de conexões O número total de conexões
tls-handshakes-per-second Taxa de handshake do TLS O número de novos handshakes TLS por intervalo de atualização
total-tls-handshakes Total de handshakes do TLS O número total de handshakes TLS
current-tls-handshakes Handshakes do TLS atuais O número atual de handshakes do TLS em processo
failed-tls-handshakes Handshakes do TLS com falha O número total de handshakes TLS com falha
current-connections Conexões atuais O número total de conexões, incluindo conexões ociosas
connection-queue-length Comprimento da fila de conexão O número total de conexões enfileiradas no pool de threads. Em um sistema íntegro em estado estável, esse número deve estar sempre próximo de zero
request-queue-length Comprimento da fila de conexão O número total de solicitações enfileiradas no pool de threads. Em um sistema íntegro em estado estável, esse número deve estar sempre próximo de zero. Essa métrica é diferente da fila de solicitações do IIS/Http.Sys e não pode ser comparada
current-upgraded-requests Solicitações atualizadas atuais (WebSockets) O número de solicitações WebSocket ativas

DiagnosticSource

O Kestrel emite um evento DiagnosticSource para solicitações HTTP rejeitadas na camada de servidor, como solicitações malformadas e violações de protocolos. Dessa forma, essas solicitações nunca entram na camada de hospedagem do ASP.NET Core.

O Kestrel emite esses eventos com o nome do evento Microsoft.AspNetCore.Server.Kestrel.BadRequest e um IFeatureCollection como o conteúdo do objeto. A exceção subjacente pode ser recuperada acessando o IBadRequestExceptionFeature na coleção de recursos.

Resolver esses eventos é um processo de duas etapas. Um observador para DiagnosticListener deve ser criado:

class BadRequestEventListener : IObserver<KeyValuePair<string, object>>, IDisposable
{
    private readonly IDisposable _subscription;
    private readonly Action<IBadRequestExceptionFeature> _callback;

    public BadRequestEventListener(DiagnosticListener diagnosticListener, Action<IBadRequestExceptionFeature> callback)
    {
        _subscription = diagnosticListener.Subscribe(this!, IsEnabled);
        _callback = callback;
    }
    private static readonly Predicate<string> IsEnabled = (provider) => provider switch
    {
        "Microsoft.AspNetCore.Server.Kestrel.BadRequest" => true,
        _ => false
    };
    public void OnNext(KeyValuePair<string, object> pair)
    {
        if (pair.Value is IFeatureCollection featureCollection)
        {
            var badRequestFeature = featureCollection.Get<IBadRequestExceptionFeature>();

            if (badRequestFeature is not null)
            {
                _callback(badRequestFeature);
            }
        }
    }
    public void OnError(Exception error) { }
    public void OnCompleted() { }
    public virtual void Dispose() => _subscription.Dispose();
}

Assine o ASP.NET Core DiagnosticListener com o observador. Neste exemplo, criamos um retorno de chamada que registra a exceção subjacente.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var diagnosticSource = app.Services.GetRequiredService<DiagnosticListener>();
using var badRequestListener = new BadRequestEventListener(diagnosticSource, (badRequestExceptionFeature) =>
{
    app.Logger.LogError(badRequestExceptionFeature.Error, "Bad request received");
});
app.MapGet("/", () => "Hello world");
app.Run();

Comportamento com depurador anexado

Determinados tempos limite e limites de taxa não são impostos quando um depurador é anexado a um processo Kestrel. Para obter mais informações, confira Comportamento com o depurador anexado.