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 e propagação de atividades para oferecer 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 Configurações recomendadas para rastreamento e registro de mensagens.

Importante

No Windows 8, você deve executar seu aplicativo elevado (Executar como administrador) para permitir que seu aplicativo gere registos de rastreamento.

Ativando o rastreamento

O Windows Communication Foundation (WCF) produz 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. Consulte Registo de Eventos.

O rastreamento WCF é construído em cima de 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 fonte de rastreamento para cada assembly do WCF. A System.ServiceModel fonte de rastreio é a fonte de rastreio WCF mais abrangente e regista etapas de processamento em toda a estrutura de comunicação do WCF, desde a entrada/saída no transporte até à entrada/saída no código do utilizador. A System.ServiceModel.MessageLogging origem 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 fonte de rastreamento selecionada na configuração; caso contrário, o WCF não gerará rastreamentos. Se você não especificar um ouvinte, o rastreamento será desativado 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 traço é emitido.

Caso utilize pontos de extensibilidade do WCF, como invocadores de operação personalizados, deverá emitir os seus próprios registos. 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. Segue-se 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>

Observação

Para editar o arquivo de configuração de um projeto de serviço WCF no Visual Studio, clique com o botão direito do mouse no arquivo de configuração do aplicativo — Web.config para aplicativos hospedados na Web ou Appname.exe.config para aplicativo auto-hospedado no Gerenciador de Soluções. Em seguida, escolha o item de menu de contexto Editar configuração do WCF . Isso inicia a Ferramenta do Editor de Configuração (SvcConfigEditor.exe), que permite modificar as definições de configuração para serviços WCF usando uma interface gráfica do usuário.

Configurar fontes de rastreamento para gerar traços

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

System.ServiceModel: Registra todos os estágios de processamento do WCF, sempre que a configuração é lida, uma mensagem é processada no transporte, o processamento de segurança, uma mensagem é enviada 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: Registo de logs da interface do .NET Framework para o sistema de ficheiros 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.

Configuração de ouvintes de rastreio para consumir rastreios

Em tempo de execução, o WCF envia dados de rastreio aos ouvintes, que processam os dados. WCF fornece vários ouvintes predefinidos para System.Diagnostics, que diferem no formato utilizado para a 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 Listener traceListener e adicionamos o ouvinte de rastreamento padrão do .NET Framework (System.Diagnostics.XmlWriterTraceListener) como o tipo que queremos 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 é 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 implementador de aplicações, deve assegurar o controlo de acesso adequado aos registos de rastreio na máquina remota.

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

Atenção

Como System.Diagnostics.XmlWriterTraceListener não é thread-safe, a fonte de rastreamento pode bloquear recursos exclusivamente ao enviar rastreamentos. Quando várias threads exportam traços para uma fonte de rastreio configurada para usar este ouvinte, pode ocorrer contenção de recursos, resultando num problema de desempenho significativo. Para resolver esse problema, você deve implementar um ouvinte personalizado que é thread-safe.

Nível de rastreio

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

Nível de rastreio	Natureza dos Eventos Rastreados	Conteúdo dos Eventos Rastreados	Eventos Rastreados	Público-alvo
Desativado	N/A	N/A	Não são emitidos vestígios.	N/A
Crítico	Eventos "negativos": eventos que indicam um processamento inesperado ou uma condição de erro.		As exceções não tratadas, incluindo as seguintes, são registradas: - OutOfMemoryException (Exceção de Falta de Memória) - ThreadAbortException (o CLR invoca qualquer ThreadAbortExceptionHandler) - StackOverflowException (não pode ser interceptado) - ConfigurationErrorsException (Exceção de Erros de Configuração) - SEHException - Erros de início de aplicação - Eventos de Falha Rápida - O sistema bloqueia - Mensagens suspeitas: rastreamentos de mensagens que fazem com que o aplicativo falhe.	Administradores Programadores de aplicações
Erro	Eventos "negativos": eventos que indicam um processamento inesperado ou uma condição de erro.	Ocorreu um processamento inesperado. O aplicativo não foi capaz de executar uma tarefa conforme o esperado. No entanto, o aplicativo ainda está em execução.	Todas as exceções são registradas.	Administradores Programadores de aplicações
Advertência	Eventos "negativos": eventos que indicam um processamento inesperado ou uma condição de erro.	Um possível problema ocorreu ou pode ocorrer, mas o aplicativo ainda funciona corretamente. No entanto, pode não continuar a funcionar corretamente.	- A aplicação está recebendo mais solicitações do que as suas definições de restrição permitem. - A fila de recebimento está perto de sua capacidade máxima configurada. O tempo limite foi excedido. - As credenciais são rejeitadas.	Administradores Programadores de aplicações
Informação	Eventos "positivos": eventos que marcam marcos de sucesso	Marcos importantes e bem-sucedidos da execução do aplicativo, independentemente de o aplicativo estar funcionando corretamente ou não.	Em geral, são geradas mensagens úteis para monitorar e diagnosticar o status do sistema, medir o desempenho ou criar perfis. Você pode usar essas informações para planejamento de capacidade e gerenciamento de desempenho: - Canais são criados. - São criados ouvintes de ponto final. - Mensagem entra/sai do transporte. - O token de segurança é recuperado. - A definição de configuração é lida.	Administradores Programadores de aplicações Desenvolvedores de produtos.
Verbose	Eventos "positivos": eventos que marcam marcos de sucesso.	Eventos de baixo nível são emitidos tanto para o código do usuário quanto para manutenção.	Em geral, você pode usar esse nível para depuração ou otimização de aplicativos. - Entendido cabeçalho da mensagem.	Administradores Programadores de aplicações Desenvolvedores de produtos.
Rastreamento de atividades		Eventos de fluxo entre atividades de processamento e componentes.	Esse nível permite que administradores e desenvolvedores correlacionem aplicativos no mesmo domínio de aplicativo: - Delimitações para limites de atividade, como início/paragem. - Rastreios para transferências.	Todos
Todos		O aplicativo pode funcionar corretamente. Todos os eventos são emitidos.	Todos os eventos anteriores.	Todos

Os níveis de Verbose a Critical 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 Off. Por exemplo, um ouvinte ouvindo no nível de Aviso recebe rastreamentos Crítico, Erro e Aviso. O nível Todos inclui eventos de Verbosidade a Críticos, bem como eventos de rastreamento de atividades.

Atenção

Os níveis Information, Verbose e ActivityTracing geram muitos rastreamentos, o que pode afetar negativamente a taxa de transferência de mensagens se você tiver usado todos os recursos disponíveis na máquina.

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

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

Observação

Quando se utilizam determinados recursos de extensibilidade no WCF, pode surgir um NullReferenceException quando o rastreamento de atividade está ativado. Para corrigir esse problema, verifique o arquivo de configuração do aplicativo e verifique se o atributo para sua switchValue fonte de rastreamento não está definido como activityTracing.

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 obter arquivos de rastreamento gerados por quaisquer 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.

Os valores de propagateActivity e ActivityTracing Boolean aplicam-se ao System.ServiceModel TraceSource. O valor de ActivityTracing também se aplica a qualquer fonte de rastreio, incluindo WCF ou aquelas definidas pelo utilizador.

Não é possível usar o atributo propagateActivity com fontes de rastreamento definidas pelo usuário. Para a propagação do ID de atividade do código do usuário, certifique-se de não definir ServiceModel ActivityTracing, enquanto ainda tem o atributo ServiceModel propagateActivity definido como true.

Ver também

Last updated on 2025-06-17

Partilhar via