Configurando o log de mensagens

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

Ativando o log de mensagens

Windows Communication Foundation (WCF) não registra mensagens por padrão. Para ativar o log de mensagens, você deve adicionar um ouvinte de rastreamento à fonte de System.ServiceModel.MessageLogging rastreamento e definir atributos para o <messagelogging> elemento 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 de mensagens.

Você pode usar add para especificar o nome e o tipo do ouvinte que deseja usar. Na configuração de exemplo, o ouvinte é chamado "mensagens" e adiciona o ouvinte de rastreamento padrão do .NET Framework (System.Diagnostics.XmlWriterTraceListener) como o tipo a ser usado. Se você usar System.Diagnostics.XmlWriterTraceListenero , 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 lança uma exceção. Você também pode implementar um ouvinte personalizado que emite logs para um arquivo padrão.

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

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

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

Se quiser desabilitar a fonte de rastreamento, use os logMessagesAtServiceLevelatributos , logMalformedMessagese logMessagesAtTransportLevel do messageLogging elemento 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 WMI. Para obter mais informações sobre a ferramenta Editor de configuração, consulte Ferramenta do Editor de configuração (SvcConfigEditor.exe). Para obter mais informações sobre 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 acontece imediatamente após a mensagem ser formada, imediatamente antes de a mensagem chegar ao código do usuário no nível de serviço e quando mensagens malformadas são detetadas.

Para mensagens enviadas, o registro acontece imediatamente após a mensagem deixar o código do usuário e imediatamente antes da mensagem ir para o fio.

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 entre si e podem ser ativadas separadamente na configuração.

Você pode controlar o nível de log definindo o logMessagesAtServiceLevellogMalformedMessages, e logMessagesAtTransportLevel atributos do messageLogging elemento.

Nível de Serviço

As mensagens registradas nessa camada estão prestes a inserir (ao receber) ou deixar (ao enviar) o código do usuário. Se os filtros tiverem sido definidos, apenas as mensagens que corresponderem aos filtros serão registradas. Caso contrário, todas as mensagens no nível de serviço serão registradas. As mensagens de infraestrutura (transações, canal de mesmo nível e segurança) também são registradas nesse nível, exceto as mensagens de mensagens confiáveis. Nas mensagens transmitidas, apenas os cabeçalhos são registrados. Além disso, as mensagens seguras são registadas desencriptadas a este 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 no fio. Se os filtros tiverem sido definidos, apenas as mensagens que corresponderem 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 confiáveis. Nas mensagens transmitidas, apenas 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 no estado em que se encontram: criptografadas se assim for, 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 256K. 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 (logEntireMessage atributo): esse valor especifica se a mensagem inteira (cabeçalho e corpo da mensagem) é registrada. O valor padrão é false, o que significa que apenas o cabeçalho é registrado. Essa configuração afeta os níveis de log de mensagens de serviço e transporte..

• Max messages to log (maxMessagesToLog attribute): Este valor especifica o número máximo de mensagens a serem registradas. Todas as mensagens (serviço, transporte e mensagens malformadas) são contabilizadas para esta quota. Quando a cota é atingida, um rastreamento é emitido e nenhuma mensagem adicional é registrada. O valor padrão é 10000.

• Tamanho máximo da mensagem a registar (maxSizeOfMessageToLog atributo): Este valor especifica o tamanho máximo das mensagens para iniciar sessão em bytes. As 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 ServiceModel estiver ativado, um rastreamento de nível de aviso será emitido 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 é 256K, enquanto o valor padrão para mensagens malformadas é 4K.

  Atenção

  O tamanho da mensagem que é calculado para comparar é 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, as mensagens podem não ser registradas. Você pode explicar esse fato especificando que o maxSizeOfMessageToLog atributo seja 10% maior do que o tamanho esperado da mensagem. Além disso, se mensagens malformadas forem registradas, o espaço em disco real utilizado pelos logs de mensagens pode ser de até 5 vezes o tamanho do valor especificado pelo 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 log de mensagens, como os atributos descritos nesta seção, podem ser alteradas em tempo de execução usando o WMI (Instrumentação de Gerenciamento do Windows). Isso pode ser feito acessando a instância AppDomainInfo , que expõe estas propriedades booleanas: LogMessagesAtServiceLevel, LogMessagesAtTransportLevel, e LogMalformedMessages. Portanto, se você configurar um ouvinte de rastreamento para log de mensagens, mas definir essas opções como false em configuração, poderá alterá-las posteriormente para true quando o aplicativo estiver em execução. Isso permite efetivamente o registro de mensagens em tempo de execução. Da mesma forma, se você habilitar o log de mensagens em seu arquivo de configuração, poderá desativá-lo em tempo de execução usando WMI. Para obter mais informações, consulte Usando a Instrumentação de Gerenciamento do Windows para diagnóstico.

O source campo em um log de mensagens especifica em que contexto a mensagem é registrada: ao enviar/receber uma mensagem de solicitação, para uma solicitação-resposta ou solicitação de 1 via, 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, source tem os seguintes valores com base no contexto.

Para Pedido/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. São aplicados ao nível dos serviços e dos transportes. Quando um ou mais filtros são definidos, apenas 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 suportam a 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 XPath DOM que podem ser examinados para corresponder ao filtro.

O exemplo a seguir mostra como configurar um filtro que registra apenas 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. Também é emitido um evento que indica 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>

Configurando um ouvinte personalizado

Você também pode configurar um ouvinte personalizado com opções adicionais. Um ouvinte personalizado pode ser útil para filtrar elementos PII específicos do aplicativo de mensagens antes do registro. 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 type atributo deve ser definido como um nome de assembly qualificado do tipo.

Consulte também

• <messageLogging>
• Registo de Mensagens
• Configurações recomendadas para rastreamento e registro de mensagens