Configurando o rastreamento

Este tópico descreve como você pode habilitar o rastreamento, configurar fontes de rastreamento para emitir rastreamentos e definir níveis de rastreamento, definir rastreamento de atividade e propagação para dar suporte à correlação de rastreamento de ponta a ponta e definir ouvintes de rastreamento para acessar rastreamentos.

Para obter recomendações de configurações de rastreamento no ambiente de produção ou depuração, consulte as Configurações recomendadas para rastreamento e registro em log de mensagens.

Habilitando o rastreamento

O WCF (Windows Communication Foundation) gera os seguintes dados para rastreamento de diagnóstico:

• Rastreia marcos de processo em todos os componentes dos aplicativos, como chamadas de operação, exceções de código, avisos e outros eventos de processamento significativos.

• Eventos de erro do Windows quando o recurso de rastreamento não funciona. Veja Registro de Eventos.

O rastreamento do WCF é construído em cima do System.Diagnostics. Para usar o rastreamento, você deve definir fontes de rastreamento no arquivo de configuração ou no código. O WCF define uma origem de rastreamento para cada assembly do WCF. A origem do rastreamento System.ServiceModel é a origem de rastreamento do WCF mais geral e registra os marcos de processamento na pilha de comunicação do WCF, desde o transporte de entrada/saída até o código do usuário de entrada/saída. A fonte System.ServiceModel.MessageLogging de rastreamento registra todas as mensagens que fluem pelo sistema.

O rastreamento não está habilitado por padrão. Para ativar o rastreamento, você deve criar um ouvinte de rastreamento e definir um nível de rastreamento diferente de "Desativado" para a origem de rastreamento selecionada na configuração; caso contrário, o WCF não gera nenhum rastreamento. Se você não especificar um ouvinte, o rastreamento será desabilitado automaticamente. Se um ouvinte for definido, mas nenhum nível for especificado, o nível será definido como "Desativado" por padrão, o que significa que nenhum rastreamento é emitido.

Se você usar pontos de extensibilidade do WCF, como invocadores de operação personalizados, deverá emitir seus próprios rastreamentos. Isso ocorre porque, se você implementar um ponto de extensibilidade, o WCF não poderá mais emitir os rastreamentos padrão no caminho padrão. Se você não implementar o suporte ao rastreamento manual emitindo rastreamentos, talvez não veja os rastreamentos esperados.

Você pode configurar o rastreamento editando o arquivo de configuração do aplicativo, Web.config para aplicativos hospedados na Web ou Appname.exe.config para aplicativos auto-hospedados. Veja a seguir um exemplo dessa edição. Para obter mais informações sobre essas configurações, consulte a seção "Configurando ouvintes de rastreamento para consumir rastreamentos".

<configuration>
   <system.diagnostics>
      <sources>
         <source name="System.ServiceModel"
                    switchValue="Information, ActivityTracing"
                    propagateActivity="true">
            <listeners>
               <add name="traceListener"
                   type="System.Diagnostics.XmlWriterTraceListener"
                   initializeData= "c:\log\Traces.svclog" />
            </listeners>
         </source>
      </sources>
   </system.diagnostics>
</configuration>

Configurando fontes de rastreamento para emitir traces

O WCF define uma fonte de rastreamento para cada assembly. Os rastreamentos gerados em um assembly são acessados pelos ouvintes definidos para essa origem. As seguintes fontes de rastreamento são definidas:

• System.ServiceModel: registra todos os estágios do processamento do WCF, sempre que a configuração é lida, uma mensagem é processada em transporte, processamento de segurança, uma mensagem é expedida no código do usuário e assim por diante.

• System.ServiceModel.MessageLogging: registra todas as mensagens que fluem pelo sistema.

• System.IdentityModel.

• System.ServiceModel.Activation.

• System.IO.Log: registro para a interface do .NET Framework para o Sistema de Arquivos de Log Comum (CLFS).

• System.Runtime.Serialization: registra quando os objetos são lidos ou gravados.

• CardSpace.

Você pode configurar cada fonte de rastreamento para usar o mesmo ouvinte (compartilhado), conforme indicado no exemplo de configuração a seguir.

<configuration>
    <system.diagnostics>
        <sources>
            <source name="System.ServiceModel"
                    switchValue="Information, ActivityTracing"
                    propagateActivity="true">
                <listeners>
                    <add name="xml" />
                </listeners>
            </source>
            <source name="CardSpace">
                <listeners>
                    <add name="xml" />
                </listeners>
            </source>
            <source name="System.IO.Log">
                <listeners>
                    <add name="xml" />
                </listeners>
            </source>
            <source name="System.Runtime.Serialization">
                <listeners>
                    <add name="xml" />
                </listeners>
            </source>
            <source name="System.IdentityModel">
                <listeners>
                    <add name="xml" />
                </listeners>
            </source>
        </sources>

        <sharedListeners>
            <add name="xml"
                 type="System.Diagnostics.XmlWriterTraceListener"
                 initializeData="c:\log\Traces.svclog" />
        </sharedListeners>
    </system.diagnostics>
</configuration>

Além disso, você pode adicionar fontes de rastreamento definidas pelo usuário, conforme demonstrado pelo exemplo a seguir, para emitir rastreamentos de código do usuário.

<system.diagnostics>
   <sources>
       <source name="UserTraceSource" switchValue="Warning, ActivityTracing" >
          <listeners>
              <add name="xml"
                 type="System.Diagnostics.XmlWriterTraceListener"
                 initializeData="C:\logs\UserTraces.svclog" />
          </listeners>
       </source>
   </sources>
   <trace autoflush="true" />
</system.diagnostics>

Para obter mais informações sobre como criar fontes de rastreamento definidas pelo usuário, consulte Estendendo o rastreamento.

Configurando ouvintes de rastreamento para consumir rastreamentos

Em runtime, o WCF alimenta os dados de rastreamento para os ouvintes, que processam os dados. O WCF fornece vários ouvintes predefinidos para System.Diagnostics, que diferem no formato usado para saída. Você também pode adicionar tipos de ouvinte personalizados.

Você pode usar add para especificar o nome e o tipo do ouvinte de rastreamento que deseja usar. Em nossa configuração de exemplo, nomeamos o Ouvinte traceListener e adicionamos o ouvinte de rastreamento padrão do .NET Framework (System.Diagnostics.XmlWriterTraceListener) como o tipo que desejamos usar. Você pode adicionar qualquer número de ouvintes de rastreamento para cada fonte. Se o ouvinte de rastreamento emitir o rastreamento para um arquivo, você 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 para esse ouvinte. Se você não especificar um nome de arquivo, um nome de arquivo aleatório será gerado com base no tipo de ouvinte usado. Se XmlWriterTraceListener for usado, um nome de arquivo sem extensão será gerado. Se você implementar um ouvinte personalizado, também poderá usar esse atributo para receber dados de inicialização diferentes de um nome de arquivo. Por exemplo, você pode especificar um identificador de banco de dados para esse atributo.

Você pode configurar um ouvinte de rastreamento personalizado para enviar rastreamentos no fio, por exemplo, para um banco de dados remoto. Como um implantador de aplicativos, você deve impor o controle de acesso adequado nos logs de rastreamento no computador remoto.

Você também pode configurar um ouvinte de rastreamento programaticamente. Para obter mais informações, consulte Como criar e inicializar ouvintes de rastreamento e Como criar um TraceListener personalizado.

Nível de rastreamento:

O nível de rastreamento é controlado pela configuração switchValue da origem do rastreamento. Os níveis de rastreamento disponíveis são descritos na tabela a seguir.

Os níveis de Verbose a Crítico são empilhados uns sobre os outros, ou seja, cada nível de rastreamento inclui todos os níveis acima dele, exceto o nível Desativado. Por exemplo, um ouvinte escutando no nível de aviso recebe rastreamentos críticos, de erro e de aviso. O nível Tudo inclui eventos de eventos de rastreamento de Verbose a Crítico e de Atividades.

Configurando o rastreamento de atividades e a propagação para correlação

O valor especificado activityTracing para o atributo switchValue é usado para habilitar o rastreamento de atividades, que emite rastreamentos para limites de atividade e transferências dentro de pontos de extremidade.

O propagateActivity atributo indica se a atividade deve ser propagada para outros pontos de extremidade que participam da troca de mensagens. Ao definir esse valor como true, você pode pegar arquivos de rastreamento gerados por dois pontos de extremidade e observar como um conjunto de rastreamentos em um ponto de extremidade fluiu para um conjunto de rastreamentos em outro ponto de extremidade.

Para obter mais informações sobre rastreamento e propagação de atividades, consulte Propagação.

Tanto propagateActivity como ActivityTracing valores booleanos se aplicam ao TraceSource do System.ServiceModel. O valor ActivityTracing também se aplica a qualquer fonte de rastreamento, incluindo WCF ou definidas pelo próprio usuário.

Você não pode usar o propagateActivity atributo com fontes de rastreamento definidas pelo usuário. Para a propagação da ID da atividade de código do usuário, verifique se você não definiu ServiceModel ActivityTracing, enquanto ainda tem o atributo ServiceModel propagateActivity definido como true.

Consulte também

• Rastreamento
• Administração e diagnóstico
• Como: criar e inicializar ouvintes de rastreamento
• Criando um TraceListener personalizado