Configurando registros de mensagens em log

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

Como habilitar o registro em log de mensagens

O Windows Communication Foundation (WCF) 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 obter mais informações sobre as configurações de log de mensagens, consulte 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 o nome do arquivo de log. Caso contrário, o sistema gerará uma exceção. Você também pode implementar um ouvinte personalizado que emite logs para um arquivo padrão.

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 switchValue atributo de um source só é válido para rastreamento. Se você especificar um switchValue atributo para a fonte System.ServiceModel.MessageLogging de rastreamento da seguinte maneira, ele não terá efeito.

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

Se você quiser desabilitar a origem do rastreamento, deverá usar os atributos logMessagesAtServiceLevel, logMalformedMessages e logMessagesAtTransportLevel do elemento messageLogging em vez disso. 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 da interface do usuário do Editor de Configuração ou usando o WMI. Para obter mais informações sobre a ferramenta Editor de Configuração, consulte Configuration Editor Tool (SvcConfigEditor.exe). Para obter mais informações sobre o WMI, consulte Usando a Instrumentação de Gerenciamento do Windows para Diagnóstico.

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

Para 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 do 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 em log. As três categorias são independentes umas das outras e podem ser ativadas separadamente na configuração.

Você pode controlar o nível de 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 neste nível.

Nível de transporte

As mensagens registradas nessa camada estão prontas para serem codificadas ou decodificadas para ou após o transporte na transmissã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 K. Para obter mais informações sobre esse atributo, consulte a seção Outras Opções.

Outras opções

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

• Registrar Mensagem Inteira (atributo logEntireMessage): esse valor especifica se a mensagem inteira (cabeçalho e corpo da mensagem) está registrada no log. O valor padrão é false, o que significa que somente o cabeçalho é registrado. Essa configuração afeta os níveis de registro em log de mensagens de serviço e transporte.

• Máximo de mensagens para log (atributo maxMessagesToLog): Esse valor especifica o número máximo de mensagens a serem registradas. 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 (atributomaxSizeOfMessageToLog ): esse valor especifica o tamanho máximo das mensagens em bytes para registro em log. Mensagens que excedem o limite de tamanho não são registradas e nenhuma outra atividade é executada para essa mensagem. Essa configuração afeta todos os níveis de rastreamento. Se o rastreamento do ServiceModel estiver ativado, será emitido um rastreamento no nível de aviso no primeiro ponto de registro (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 é 256 KB, enquanto o valor padrão para mensagens malformadas é 4 KB.

  Cuidado

  O tamanho da mensagem que é computado para ser comparado com maxSizeOfMessageToLog é o tamanho da mensagem na memória antes da serialização. Esse tamanho pode ser diferente do comprimento real da cadeia de caracteres de mensagem que está sendo registrada e, em muitas ocasiões, é maior que o tamanho real. Como resultado, as mensagens podem não ser registradas. Você pode considerar esse fato especificando que o maxSizeOfMessageToLog atributo seja 10% maior 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 mensagens poderá ter até 5 vezes o tamanho do valor especificado por maxSizeOfMessageToLog.

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

As opções de registro em log de mensagens, como os atributos descritos nesta seção, podem ser alteradas em runtime usando a Instrumentação de Gerenciamento do Windows (WMI). Isso pode ser feito acessando a instância appDomainInfo , que expõe essas propriedades boolianas: LogMessagesAtServiceLevel, LogMessagesAtTransportLevele LogMalformedMessages. Portanto, se você configurar um ouvinte de rastreamento para o registro em 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 runtime. Da mesma forma, se você habilitar o registro em log de mensagens no arquivo de configuração, poderá desabilitá-lo em runtime usando o WMI. Para obter mais informações, consulte Como usar a Instrumentação de Gerenciamento do Windows para Diagnóstico.

O source campo 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 camada de transporte, ou no caso de uma mensagem malformada.

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

Para solicitação/resposta:

Para solicitação unidirecional:

Filtros de Mensagem

Os filtros de mensagem são definidos no messageLogging elemento de configuração da diagnostics seção de configuração. Eles são aplicados no nível de serviço e 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 dão 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 nodeQuota atributo, que limita o número máximo de nós no DOM XPath que podem ser examinados para corresponder ao filtro.

O exemplo a seguir mostra como configurar um filtro que registra 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 filtro.

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

Configurando 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 personalizada.

<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.

Consulte também

• <log de mensagens>
• Registro em log de mensagens
• Configurações recomendadas para registro de rastreamento e mensagens