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 que seu aplicativo gere logs 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 do System.DiagnosticsWCF é construído sobre o . 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 rastreamento é a fonte de rastreamento WCF mais geral e registra marcos de processamento em toda a pilha de comunicação do WCF, desde a entrada/saída do transporte até a entrada/saída do código do usuário. 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 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. 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>
Nota
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.
Configurando fontes de rastreamento para emitir rastreamentos
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: Registro em log da interface do .NET Framework para o Common Log File System (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 tempo de execução, o WCF alimenta dados de rastreamento para os ouvintes, que processam os dados. WCF fornece vários ouvintes predefinidos para System.Diagnostics, que diferem no formato que eles usam 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 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 implantador de aplicativos, você deve impor o controle de acesso adequado nos logs de rastreamento 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 Criando 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 muitos threads de saída rastreiam 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 é 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 |
|---|---|---|---|---|
| Inativo | 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 - ThreadAbortException (o CLR invoca qualquer ThreadAbortExceptionHandler) - StackOverflowException (não pode ser capturado) - ConfigurationErrorsException - SEHException - Erros de início de aplicação - Eventos Failfast - O sistema trava - 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 |
| 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, pode não continuar a funcionar corretamente. | - O aplicativo está recebendo mais solicitações do que suas configurações de limitação permitem. - A fila de recebimento está perto de sua capacidade máxima configurada. - O tempo limite excedeu. - 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. |
| Verboso | Eventos "positivos": eventos que marcam marcos de sucesso. | Eventos de baixo nível para código de usuário e manutenção são emitidos. | 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. |
| ActivityTracing | 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: - Rastreamentos para limites de atividade, como start/stop. - 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 Crítico são empilhados uns sobre os outros, ou seja, cada nível de traço 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 Detalhados a Críticos e 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 é usado para habilitar o switchValue rastreamento de atividade, que emite rastreamentos para limites de atividade e transferências dentro de pontos de extremidade.
Nota
Quando você usa determinados recursos de extensibilidade no WCF, você pode obter um quando o NullReferenceException rastreamento de atividade está habilitado. 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.
Ambos os propagateActivity valores e ActivityTracing Boolean se aplicam ao System.ServiceModel TraceSource. O ActivityTracing valor também se aplica a qualquer fonte de rastreamento, incluindo WCF ou definidas pelo usuário.
Não é possível usar o atributo com fontes de rastreamento definidas pelo propagateActivity 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.