Log do lado do cliente com a biblioteca de clientes para .NET

Artigo
06/27/2023

Com a biblioteca de clientes do Armazenamento do Azure para .NET (versão 2.1 e posterior), você pode registrar solicitações do Armazenamento do Azure de dentro do aplicativo cliente .NET usando a infraestrutura de diagnóstico padrão do .NET. Dessa forma, você pode ver detalhes das solicitações que seu cliente envia aos serviços do Armazenamento do Azure e as respostas recebidas.

A biblioteca de clientes do Armazenamento do Azure fornece controle sobre quais solicitações de armazenamento você pode registrar e a infraestrutura de diagnóstico do .NET fornece controle total sobre os dados de log, como para onde enviá-los. Por exemplo, você pode optar por enviar os dados de log para um arquivo ou para um aplicativo para processamento. Em combinação com a Análise de Armazenamento do Azure e o monitoramento de rede, você pode usar o log da biblioteca de clientes para criar uma imagem detalhada de como seu aplicativo interage com os serviços de Armazenamento do Azure. Para obter mais informações, consulte Monitorar, diagnosticar e solucionar problemas do Armazenamento do Azure.

Como habilitar o log da biblioteca de clientes

O exemplo a seguir mostra a configuração de system.diagnostics necessária para coletar e persistir as mensagens de log de armazenamento em um arquivo de texto. A seção de configuração pode ser adicionada a arquivos app.config ou web.config.

Observação

Se você estiver usando uma versão anterior a 10.0.0, use o nome Microsoft.WindowsAzure.Storage em vez de Microsoft.Azure.Storage.

<system.diagnostics>  
     <!--In a dev/test environment you can set autoflush to true in order to autoflush to the log file. -->  
  <trace autoflush="false">  
    <listeners>  
      ...
      <add name="storageListener" />  
    </listeners>  
  </trace>  
  <sources>  
    <source name="Microsoft.Azure.Storage">  
      <listeners>  
        <add name="storageListener"/>  
      </listeners>  
    </source>  
  </sources>  
  <switches>  
    <add name="Microsoft.Azure.Storage" value="Verbose" />  
  </switches>  
  <sharedListeners>  
    <add name="storageListener"  
      type="System.Diagnostics.TextWriterTraceListener"  
      initializeData="C:\logs\WebRole.log"
      traceOutputOptions="DateTime" />  
  </sharedListeners>  
</system.diagnostics>

Observação

.NET Framework usuários nas versões 4.6.1-4.7.1 (inclusive) podem enfrentar problemas de registro em log ao usar os artefatos do .NET Standard 2.0 das bibliotecas do Armazenamento do Azure, que podem ser selecionados automaticamente pelo gerenciador de pacotes NuGet do Visual Studio. As bibliotecas também são publicadas como .NET Framework artefatos 4.5.2, que não enfrentam esses problemas. Para obter mais informações, leia sobre o suporte à versão do .NET Standard.

Este exemplo configura a biblioteca de clientes para gravar mensagens de log no arquivo C:\logs\WebRole.logfísico . Você também pode usar outros ouvintes de rastreamento, como EventLogTraceListener , para gravar no log de eventos do Windows ou EventProviderTraceListener para gravar dados de rastreamento no subsistema ETW.

Importante

O caminho completo da pasta para o arquivo de log deve existir no sistema de arquivos local. Neste exemplo, isso significa que você deve primeiro criar a C:\logs pasta antes de gravar logs em um arquivo nessa pasta.

Além disso, você pode definir autoflush como true para gravar as entradas de log no arquivo imediatamente em vez de armatá-las em buffer. Essa configuração pode ser útil em um ambiente de desenvolvimento/teste com baixos volumes de mensagens de rastreamento, mas em um ambiente de produção, talvez você queira definir a eliminação automática como false. Use as definições de configuração para habilitar o rastreamento de cliente (e especificar o nível, como Detalhado, para todas as mensagens) para todas as operações de armazenamento no cliente.

Id	Nível de log	Eventos
0	Desativado	Nenhum item é registrado em log.
1	Erro	Se uma exceção não puder ser tratada internamente e for gerada para o usuário, ela será registrada como um erro.
2	Aviso	Se uma exceção for capturada e tratada internamente, ela será registrada como um aviso. O principal caso de uso para esse nível de log é o cenário de repetição, em que uma exceção não é lançada novamente para o usuário tentar novamente. Esse comportamento também pode ocorrer em operações como CreateIfNotExists, em que o erro 404 é tratado silenciosamente.
3	Informativo	As seguintes informações são registradas em log: •Logo após o usuário chamar um método para iniciar uma operação, os detalhes da solicitação, como URI e ID de solicitação do cliente, são registrados. •Marcos importantes, como Início/Término da Solicitação de Envio, Início/Término de Dados de Upload, Início/Término da Resposta de Recebimento, Início/Término de Dados de Download são registrados para marcar os carimbos de data/hora. •Logo após o recebimento dos cabeçalhos, os detalhes da resposta, como ID da solicitação e código de status HTTP, são registrados. •Se uma operação falhar e o cliente de armazenamento decidir tentar novamente, o motivo dessa decisão será registrado junto com informações sobre quando a próxima repetição ocorrerá. •Todos os tempos limite do lado do cliente são registrados quando um cliente de armazenamento decide anular uma solicitação pendente.
4	Detalhado	As seguintes informações são registradas em log: •Cadeia de caracteres para assinar para cada solicitação. •Quaisquer detalhes adicionais específicos para operações (até cada operação a ser definida e usada).

Por padrão, a biblioteca de clientes registra detalhes de todas as operações de armazenamento no nível de detalhamento especificado no arquivo de configuração. Você também pode limitar o registro em log a áreas específicas do seu aplicativo cliente para reduzir a quantidade de dados registrados e para ajudá-lo a encontrar as informações necessárias. Para limitar a quantidade de dados gravados nos logs, você deve adicionar algum código ao aplicativo cliente. Normalmente, depois de habilitar o rastreamento do lado do cliente no arquivo de configuração, você o desativa globalmente no código usando a classe OperationContext . Por exemplo, você pode fazer isso em um aplicativo MVC ASP.NET no método Application_Start antes que seu aplicativo execute qualquer operação de armazenamento:

protected void Application_Start()  
{  
    ...  
  
    // Disable Default Logging for Windows Azure Storage  
    OperationContext.DefaultLogLevel = LogLevel.Off;  
  
    // Verify that all of the tables, queues, and blob containers used in this application  
    // exist, and create any that don't already exist.  
    CreateTablesQueuesBlobContainers();  
}

Em seguida, você pode habilitar o rastreamento para as operações específicas em que está interessado criando um objeto OperationContext personalizado que define o nível de log. Em seguida, passe o objeto OperationContext como um parâmetro para o método Execute que você usa para invocar uma operação de armazenamento, como no exemplo a seguir:

[HttpPost]  
[ValidateAntiForgeryToken]  
public ActionResult Create(Subscriber subscriber)  
{  
    if (ModelState.IsValid)  
    {  
       ...  
        var insertOperation = TableOperation.Insert(subscriber);  
        OperationContext verboseLoggingContext = new OperationContext() { LogLevel = LogLevel.Verbose };  
        mailingListTable.Execute(insertOperation, null, verboseLoggingContext);  
        return RedirectToAction("Index");  
    }  
  
    ...  
    return View(subscriber);  
}

Esquema de registro em log no lado do cliente e exemplo

O exemplo a seguir é um extrato do log do lado do cliente gerado pela biblioteca de clientes para uma operação com uma ID de solicitação de cliente que inclui c3aa328b. A ID de solicitação do cliente é um identificador de correlação que permite que as mensagens registradas no lado do cliente sejam correlacionadas com rastreamentos de rede e logs de armazenamento. Para obter mais informações sobre correlação, consulte Monitorar, diagnosticar e solucionar problemas do Armazenamento do Azure. O extrato inclui comentários (recuados e em itálico) sobre algumas informações-chave que podem ser observadas nos arquivos de log.

Para ilustrar essa funcionalidade usando a primeira linha do seguinte arquivo de log, os campos são:

Campo log	Valor
Origem	Microsoft.Azure.Storage
Verbosidade	Informações
Nº de Detalhamento	3
ID da solicitação do cliente	c3aa328b...
Texto da Operação	Inicialização da operação com o local principal por modo de local PrimaryOnly.

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
A mensagem de rastreamento anterior mostra que o modo de localização é definido apenas como primário, o que significa que uma solicitação com falha não será enviada para um local secundário.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
A mensagem de rastreamento anterior mostra que a solicitação é síncrona.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
A mensagem de rastreamento anterior mostra que a resposta deve ser retornada formatada como JSON.
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
A mensagem de rastreamento anterior inclui as informações stringToSign, que são úteis para depurar falhas de autenticação. As mensagens detalhadas também contêm detalhes completos da solicitação, incluindo o tipo de operação e os parâmetros de solicitação.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
A mensagem de rastreamento anterior mostra que a solicitação foi enviada e o cliente está aguardando uma resposta.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
A mensagem de rastreamento anterior mostra que a resposta foi recebida e seu código http status.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response headers were processed successfully, proceeding with the rest of the operation.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Processing response body.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Retrieved '8' results with continuation token ''.
A mensagem de rastreamento anterior mostra que oito resultados foram recuperados e nenhum token de continuação foi fornecido, o que significa que não há mais resultados para essa consulta.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
A mensagem de rastreamento anterior mostra que a operação foi concluída com êxito.

As duas entradas de log detalhadas (nível 4) a seguir mostram um HEAD e uma solicitação DELETE e ilustram as informações detalhadas no campo Texto da Operação:
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = HEAD............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:11 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = DELETE............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:12 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
A mensagem de rastreamento anterior mostra o campo OperationText dentro de mensagens de rastreamento detalhadas, incluindo informações detalhadas relacionadas a uma solicitação específica. Esses detalhes incluem o tipo de operação HTTP (por exemplo, HEAD, DELETE, POST), a ID de solicitação do cliente, o carimbo de data/hora, a versão do SDK e dados adicionais específicos da operação.

Compartilhar via

Log do lado do cliente com a biblioteca de clientes para .NET

Como habilitar o log da biblioteca de clientes

Esquema de registro em log no lado do cliente e exemplo

Recursos adicionais