Configurando o rastreamento
O tópico descreve como você pode ativar o rastreamento, configurar fontes de rastreamento para emitir rastreamentos e definir níveis de rastreamento, definir o rastreamento de atividades e propagação para oferecer suporte à correlação de rastreamento ponta a ponta, além de 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.
Importante
No Windows 8 você deve executar seu aplicativo com privilégios elevados (Executar como Administrador) para que seu aplicativo gere logs de rastreamento.
Habilitar o rastreamento
O Windows Communication Foundation (WCF) gera os seguintes dados para rastreamento de diagnóstico:
Rastreamentos de 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 Log 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 origem do rastreamento System.ServiceModel.MessageLogging 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 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.
É possível configurar o rastreamento editando o arquivo de configuração do aplicativo — o Web.config, para aplicativos hospedados na Web ou Appname.exe.config para aplicativos auto-hospedados. O seguinte é um exemplo de tal 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 configurações dos serviços WCF usando uma interface gráfica do usuário.
Configurando fontes de rastreamento para emitir rastreamentos
O WCF define uma origem 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 todas as etapas de processamento do WCF, sempre que a configuração é lida, uma mensagem é processada no transporte, no 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 rastreamento.
Configurando ouvintes de rastreamento para consumir rastreamentos
Em tempo de execução, 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 nosso exemplo de configuração, 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 como 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 na transmissão, 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.
Cuidado
Como System.Diagnostics.XmlWriterTraceListener não é thread-safe, a fonte de rastreamento pode bloquear recursos exclusivamente ao gerar rastreamentos. Quando muitos threads geram rastreamentos para uma fonte de rastreamento configurada para usar esse ouvinte, a contenção de recursos pode ocorrer, o que resulta em um problema de desempenho significativo. Para resolver esse problema, você deve implementar um ouvinte personalizado que seja thread-safe.
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.
| Nível de rastreamento: | Natureza dos eventos rastreados | Conteúdo dos eventos rastreados | Eventos rastreados | Destino do usuário |
|---|---|---|---|---|
| Desativado | N/D | N/D | Nenhum rastreamento é emitido. | N/D |
| Crítico | Eventos "negativos": eventos que indicam um processamento inesperado ou uma condição de erro. | Exceções sem tratamento, incluindo as seguintes, são registradas: - OutOfMemoryException - ThreadAbortException (o CLR invoca qualquer ThreadAbortExceptionHandler) - StackOverflowException (não pode ser capturado) - ConfigurationErrorsException - SEHException - Erros inicias do aplicativo - Eventos failfast - Paradas do sistema - Mensagens suspeitas: rastreamentos de mensagem que fazem com que o aplicativo falhe. |
Administradores Desenvolvedores de aplicativos |
|
| Erro | Eventos "negativos": eventos que indicam um processamento inesperado ou uma condição de erro. | O processamento inesperado aconteceu. O aplicativo não conseguiu executar uma tarefa conforme o esperado. No entanto, o aplicativo ainda está em execução. | Todas as exceções são registradas. | Administradores Desenvolvedores de aplicativos |
| Aviso | 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, ele pode não continuar funcionando corretamente. | - O aplicativo está recebendo mais solicitações do que suas configurações de limitação permitem. - A fila de recebimento está perto da sua capacidade máxima configurada. - O tempo limite foi excedido. - As credenciais são rejeitadas. |
Administradores Desenvolvedores de aplicativos |
| Informações | Eventos "positivos": eventos que marcam marcos bem-sucedidos | Marcos importantes e bem-sucedidos da execução do aplicativo, independentemente se o aplicativo está funcionando corretamente ou não. | Em geral, mensagens úteis para monitorar e diagnosticar o status do sistema, medir o desempenho ou criar perfis são geradas. É possível utilizar essas informações para o planejamento de capacidade e o gerenciamento de desempenho: - Os canais são criados. - Os ouvintes de ponto de extremidade são criados. - Transporte de entrada/saída de mensagem. - O token de segurança é recuperado. - A definição de configuração é lida. |
Administradores Desenvolvedores de aplicativos Desenvolvedores de produtos. |
| Detalhado | Eventos "positivos": eventos que marcam marcos bem-sucedidos. | Eventos de baixo nível para código do usuário e manutenção são emitidos. | Em geral, você pode usar esse nível para depuração ou otimização de aplicativo. - Reconheceu o cabeçalho da mensagem. |
Administradores Desenvolvedores de aplicativos Desenvolvedores de produtos. |
| ActivityTracing | Eventos de fluxo entre atividades de processamento e componentes. | Este nível permite que os administradores e desenvolvedores correlacionem aplicativos no mesmo domínio de aplicativos: - Rastreamentos de limites de atividades, como início/parada. - Rastreamentos de transferências. |
Tudo | |
| Tudo | O aplicativo pode funcionar corretamente. Todos os eventos são emitidos. | Todos os eventos anteriores. | Tudo |
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.
Cuidado
Os níveis de Informações, 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 no computador.
Configurando o rastreamento e a propagação de atividades 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.
Observação
Ao usar determinados recursos de extensibilidade no WCF, você poderá obter um NullReferenceException quando o rastreamento de atividades estiver habilitado. Para corrigir esse problema, verifique o arquivo de configuração do aplicativo e verifique se o atributo switchValue da fonte de rastreamento não está definido como activityTracing.
O atributo propagateActivity indica se a atividade deve ser propagada para outros pontos de extremidade que participam da troca de mensagens. Definindo 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.
Os valores boolianos propagateActivity e ActivityTracing se aplicam ao System.ServiceModel TraceSource. O valor ActivityTracing também se aplica a qualquer fonte de rastreamento, incluindo WCF ou definidas pelo usuário.
Você não pode usar o atributo propagateActivity com fontes de rastreamento definidas pelo usuário. Para 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.