Configurando registros de mensagens em log

Artigo
05/09/2023

Este tópico descreve como configurar o registro em log de mensagens para cenários diferentes.

Como habilitar o registro em log de mensagens

O WCF (Windows Communication Foundation) não registra mensagens por padrão. Para ativar o registro em log de mensagens, você deve adicionar um ouvinte de rastreamento à origem do rastreamento System.ServiceModel.MessageLogging e definir atributos para o elemento <messagelogging> no arquivo de configuração.

O exemplo a seguir mostra como habilitar o registro em log e especificar opções adicionais.

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel.MessageLogging">
      <listeners>
         <add name="messages"
              type="System.Diagnostics.XmlWriterTraceListener"
              initializeData="c:\logs\messages.svclog" />
        </listeners>
    </source>
  </sources>
</system.diagnostics>

<system.serviceModel>
  <diagnostics>
    <messageLogging
         logEntireMessage="true"
         logMalformedMessages="false"
         logMessagesAtServiceLevel="true"
         logMessagesAtTransportLevel="false"
         maxMessagesToLog="3000"
         maxSizeOfMessageToLog="2000"/>
  </diagnostics>
</system.serviceModel>

Para saber mais sobre configurações de log de mensagens, confira Configurações recomendadas para rastreamento e registro em log de mensagens.

Você pode usar add para especificar o nome e o tipo do ouvinte que deseja usar. No exemplo de configuração, o Ouvinte é chamado de "mensagens" e adiciona o ouvinte de rastreamento do .NET Framework padrão (System.Diagnostics.XmlWriterTraceListener) como o tipo a ser usado. Se você usar System.Diagnostics.XmlWriterTraceListener, deverá especificar o local e o nome do arquivo de saída no arquivo de configuração. Isso é feito definindo initializeData como o nome do arquivo de log. Caso contrário, o sistema gera uma exceção. Você também pode implementar um ouvinte personalizado que emite logs em um arquivo padrão.

Observação

Como o registro em log de mensagens acessa o espaço em disco, você deve limitar o número de mensagens gravadas em disco para um serviço específico. Quando o limite de mensagens é atingido, um rastreamento no nível de informações é produzido e todas as atividades de registro em log de mensagens param.

O nível de registros em log, bem como as opções adicionais, são discutidos na seção Níveis e opções de registros em log.

O atributo switchValue de um source só é válido para rastreamento. Se você especificar um atributo switchValue para a fonte de rastreamento System.ServiceModel.MessageLogging da seguinte maneira, ele não terá efeito.

<source name="System.ServiceModel.MessageLogging" switchValue="Verbose">
</source>

Se você quiser desabilitar a fonte de rastreamento, deverá usar, em vez disso, os atributos logMessagesAtServiceLevel, logMalformedMessages e logMessagesAtTransportLevel do elemento messageLogging. Você deve definir todos esses atributos como false. Isso pode ser feito usando o arquivo de configuração no exemplo de código anterior, por meio da interface do usuário do Editor de Configuração ou usando o WMI. Para saber mais sobre a ferramenta Editor de Configuração, confira Ferramenta do Editor de Configuração (SvcConfigEditor.exe). Para saber mais sobre o WMI, confira Como usar a Instrumentação de Gerenciamento do Windows para diagnóstico.

Níveis e opções de registro em log

Para as mensagens de entrada, o registro em log ocorre imediatamente após a formação da mensagem, imediatamente antes de a mensagem chegar ao código do usuário no nível de serviço e quando mensagens malformadas são detectadas.

Para mensagens de saída, o registro em log ocorre imediatamente depois que a mensagem deixa o código do usuário e imediatamente antes de a mensagem ser exibida.

O WCF registra mensagens em dois níveis diferentes, serviço e transporte. Mensagens malformadas também são registradas. As três categorias são independentes umas das outras e podem ser ativadas separadamente na configuração.

Você pode controlar o nível do registro em log definindo os atributos logMessagesAtServiceLevel, logMalformedMessages e logMessagesAtTransportLevel do elemento messageLogging.

Nível de serviço

As mensagens registradas nessa camada estão prestes a entrar (no recebimento) ou sair (no envio) do código de usuário. Se os filtros tiverem sido definidos, somente as mensagens que correspondem aos filtros serão registradas. Caso contrário, todas as mensagens no nível do serviço serão registradas. As mensagens de infraestrutura (transações, canal par e segurança) também são registradas nesse nível, exceto para mensagens de Mensagens Confiáveis. Em mensagens transmitidas, somente os cabeçalhos são registrados. Além disso, as mensagens seguras são registradas descriptografadas nesse nível.

Nível de transporte

As mensagens registradas nessa camada estão prontas para serem codificadas ou decodificadas para transporte no fio ou após essa ação. Se os filtros tiverem sido definidos, somente as mensagens que correspondem aos filtros serão registradas. Caso contrário, todas as mensagens na camada de transporte serão registradas. Todas as mensagens de infraestrutura são registradas nessa camada, incluindo mensagens de Mensagens Confiáveis. Em mensagens transmitidas, somente os cabeçalhos são registrados. Além disso, as mensagens seguras são registradas como criptografadas nesse nível, exceto se um transporte seguro, como HTTPS, for usado.

Nível malformado

Mensagens malformadas são mensagens rejeitadas pela pilha WCF em qualquer estágio de processamento. As mensagens malformadas são registradas como estão: criptografadas se assim estiverem, com XML não adequado e assim por diante. maxSizeOfMessageToLog definiu o tamanho da mensagem a ser registrada como CDATA. Por padrão, maxSizeOfMessageToLog é igual a 256 mil. Para saber mais sobre esse atributo, confira a seção Outras opções.

Outras opções

Além dos níveis de registro em log, o usuário pode especificar as seguintes opções:

Registrar em log a mensagem inteira (atributo logEntireMessage): esse valor especifica se a mensagem inteira (cabeçalho e corpo da mensagem) está registrada. O valor padrão é false, o que significa que apenas o cabeçalho está registrado. Essa configuração afeta os níveis de registro em log de mensagens de serviço e transporte.
Quantidade máxima de mensagens para registro (atributo maxMessagesToLog): esse valor especifica o número máximo de mensagens a ser registrado em log. Todas as mensagens (serviço, transporte e mensagens malformadas) contam para essa cota. Quando a cota é atingida, um rastreamento é emitido e nenhuma mensagem adicional é registrada. O valor padrão é 10000.
Tamanho máximo da mensagem para registro em log (atributo maxSizeOfMessageToLog): esse valor especifica o tamanho máximo das mensagens em bytes para registro em log. Mensagens que ultrapassam o limite de tamanho não são registradas e nenhuma outra atividade é executada nessa mensagem. Essa configuração afeta todos os níveis de rastreamento. Se o rastreamento ServiceModel estiver ativado, um rastreamento de Nível de aviso será emitido no primeiro ponto de registro em log (ServiceModelSend* ou TransportReceive) para notificar o usuário. O valor padrão para mensagens de nível de serviço e nível de transporte é de 256 mil, enquanto o valor padrão para mensagens malformadas é quatro mil.

Cuidado

O tamanho da mensagem calculado para comparar com maxSizeOfMessageToLog é o tamanho da mensagem na memória antes da serialização. Esse tamanho pode diferir do comprimento real da cadeia de caracteres de mensagem que está sendo registrada e, em muitas ocasiões, é maior do que o tamanho real. Como resultado, talvez as mensagens não sejam registradas. Você pode considerar esse fato especificando que o atributo maxSizeOfMessageToLog seja 10% maior do que o tamanho esperado da mensagem. Além disso, se as mensagens malformadas forem registradas, o espaço real em disco utilizado pelos logs de mensagem poderá ter até cinco vezes o tamanho do valor especificado por maxSizeOfMessageToLog.

Se nenhum ouvinte de rastreamento for definido no arquivo de configuração, nenhuma saída de registro em log será gerada, independentemente do nível de registro em log especificado.

As opções de registro em log de mensagens, como os atributos descritos nesta seção, podem ser alteradas em tempo de execução usando WMI (Instrumentação de Gerenciamento do Windows). Isso pode ser feito acessando a instância de AppDomainInfo, que expõe estas propriedades boolianas: LogMessagesAtServiceLevel,LogMessagesAtTransportLevel, LogMalformedMessages. Portanto, se você configurar um ouvinte de rastreamento para o log de mensagens, mas definir essas opções como false na configuração, poderá alterá-las posteriormente para true quando o aplicativo estiver em execução. Isso habilita efetivamente o registro em log de mensagens em tempo de execução. Da mesma forma, se você habilitar o log de mensagens no arquivo de configuração, poderá desabilitá-lo em tempo de execução usando o WMI. Para saber mais, confira Como usar a Instrumentação de Gerenciamento do Windows para diagnóstico.

O campo source em um log de mensagens especifica em qual contexto a mensagem é registrada: ao enviar/receber uma mensagem de solicitação, para uma solicitação-resposta ou solicitação unidirecional, no modelo de serviço ou na camada de transporte, ou no caso de uma mensagem malformada.

Para mensagens malformadas, source é igual a Malformed. Caso contrário, a origem terá os seguintes valores com base no contexto.

Para Solicitação/resposta:

Camada	Enviar solicitação	Receber solicitação	Enviar resposta	Receber resposta
Camada do modelo de serviço	Serviço Nível Enviar Solicitação	Serviço Nível Receber Solicitação	Serviço Nível Enviar Responder	Serviço Nível Receber Responder
Camada de transporte	Transport Enviar	Transport Receber	Transport Enviar	Transport Receber

Para solicitações unidirecionais:

Camada	Enviar solicitação	Receber solicitação
Camada do modelo de serviço	Serviço Nível Enviar Datagrama	Serviço Nível Receber Datagrama
Camada de transporte	Transport Enviar	Transport Receber

Filtros de mensagem

Os filtros de mensagem são definidos no elemento de configuração messageLogging da seção de configuração diagnostics. Eles são aplicados no nível de serviço e de transporte. Quando um ou mais filtros são definidos, somente as mensagens que correspondem a pelo menos um dos filtros são registradas. Se nenhum filtro for definido, todas as mensagens passarão.

Os filtros oferecem suporte à sintaxe XPath completa e são aplicados na ordem em que aparecem no arquivo de configuração. Um filtro sintaticamente incorreto resulta em uma exceção de configuração.

Os filtros também fornecem um recurso de segurança usando o atributo nodeQuota, que limita o número máximo de nós no XPath DOM que pode ser examinado para corresponder ao filtro.

Veja a seguir um exemplo de como configurar um filtro que registre apenas as mensagens que têm uma seção de cabeçalho SOAP.

<messageLogging logEntireMessage="true"
    logMalformedMessages="true"
    logMessagesAtServiceLevel="true"
    logMessagesAtTransportLevel="true"
    maxMessagesToLog="420">
    <filters>
        <add nodeQuota="10" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
                 /soap:Envelope/soap:Header
        </add>
     </filters>
</messageLogging>

Os filtros não podem ser aplicados ao corpo de uma mensagem. Os filtros que tentam manipular o corpo de uma mensagem são removidos da lista de filtros. Um evento também é emitido indicando isso. Por exemplo, o filtro a seguir seria removido da tabela de filtros.

<add xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">/s:Envelope/s:Body[contains(text(), "Hello")]</add>

Configuração de um ouvinte personalizado

Você também pode configurar um ouvinte personalizado com opções adicionais. Um ouvinte personalizado pode ser útil na filtragem de elementos PII específicos ao aplicativo das mensagens antes do registro em log. O exemplo a seguir demonstra uma configuração de ouvinte personalizado.

<system.diagnostics>
   <sources>
     <source name="System.ServiceModel.MessageLogging">
           <listeners>
             <add name="MyListener"
                    type="YourCustomListener"
                    initializeData="c:\logs\messages.svclog"
                    maxDiskSpace="1000"/>
           </listeners>
     </source>
   </sources>
</system.diagnostics>

Você deve estar ciente de que o atributo type deve ser definido como um nome de assembly qualificado do tipo.

Compartilhar via