Usando o coletor autônomo do IntelliTrace (C#, Visual Basic)

O coletor autônomo do IntelliTrace permite coletar dados de diagnóstico do IntelliTrace para seus aplicativos em servidores de produção ou outros ambientes sem instalar o Visual Studio no computador de destino e sem alterar o ambiente do sistema de destino. O coletor autônomo do IntelliTrace funciona em aplicativos Web, SharePoint, WPF e Windows Forms. Quando terminar de coletar dados, basta excluir o coletor para desinstalá-los.

Observação

Para obter abordagens recomendadas para diagnosticar problemas em servidores de produção, consulte Diagnosticar problemas após a implantação.

Requisitos

.NET Framework 3.5 ou superior
Visual Studio Enterprise (mas não edições profissionais ou de comunidade) em um computador de desenvolvimento ou outro computador para abrir arquivos .iTrace

Observação

Certifique-se de salvar os arquivos de símbolos (.pdb). Para depurar com o IntelliTrace e percorrer o código passo a passo, você deve ter os arquivos de origem e os arquivos de símbolo correspondentes. Consulte Diagnosticar problemas após a implantação.

perguntas frequentes
Quais aplicativos funcionam com o coletor?
Como faço para começar?
Como posso obter o máximo de dados sem diminuir a velocidade do meu aplicativo?
Onde mais posso obter dados do IntelliTrace?

Quais aplicativos funcionam com o coletor?

ASP.NET aplicativos Web hospedados no IIS (Serviços de Informações da Internet) versão 7.0, 7.5, 8.0, 12.0 e 16.0
Aplicativos do SharePoint 2010 e do SharePoint 2013
Aplicativos WPF (Windows Presentation Foundation) e Windows Forms.

Como começar?

Instalar o coletor
Configurar permissões para o diretório do coletor
Instalar cmdlets do PowerShell do IntelliTrace para coletar dados para aplicativos Web ou aplicativos do SharePoint
Configurar permissões para o diretório de arquivos .iTrace
Coletar dados de um aplicativo Web ou aplicativo do SharePoint

- ou -

Coletar dados de um aplicativo gerenciado
Abra o arquivo .iTrace no Visual Studio Enterprise

Instalar o coletor

No servidor do aplicativo, crie o diretório do coletor, por exemplo: C:\IntelliTraceCollector
Obtenha o coletor da pasta de instalação do Visual Studio.
1. Copie IntelliTraceCollection.cab da pasta em que o coletor está instalado, por exemplo:
  
  .. \Microsoft Visual Studio\18\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  .. \Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  ou, para versões anteriores do Visual Studio:
  
  .. \Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0
2. Coloque IntelliTraceCollection.cab no diretório do coletor, por exemplo: C:\IntelliTraceCollector
Expandir IntelliTraceCollection.cab:
1. No servidor do aplicativo, abra uma janela do prompt de comando como administrador.
2. Navegue até o diretório do coletor, por exemplo: C:\IntelliTraceCollector
3. Use o comando expanda , incluindo o período (.) no final, para expandir IntelliTraceCollection.cab:
  
  expand /f:* IntelliTraceCollection.cab .
  
  Observação
  
  O período (.) preserva as subpastas que contêm planos de coleta localizados.

Configurar permissões para o diretório do coletor

No servidor do aplicativo, abra uma janela do prompt de comando como administrador.
Use o comando icacls do Windows para conceder ao administrador do servidor permissões completas para o diretório do coletor. Por exemplo:

icacls "C:\IntelliTraceCollector" /grant " <Domain\AdministratorID>":F
Para coletar dados para um aplicativo Web ou aplicativo do SharePoint:
1. Forneça à pessoa que executará os cmdlets do PowerShell do IntelliTrace permissões completas para o diretório do coletor.
  
  Por exemplo:
  
  icacls "C:\IntelliTraceCollector" /grant " <Domain\UserID>":F
2. Forneça ao pool de aplicativos para o aplicativo Web ou o aplicativo do SharePoint permissões de leitura e execução para o diretório do coletor.
  
  Por exemplo:
  - Para um aplicativo Web no pool de aplicativos DefaultAppPool :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX
  - Para um aplicativo do SharePoint no pool de aplicativos do SharePoint – 80 :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

Instalar cmdlets do PowerShell do IntelliTrace para coletar dados para aplicativos Web ou aplicativos do SharePoint

No servidor do aplicativo, verifique se o PowerShell está habilitado. Na maioria das versões do Windows Server, você pode adicionar esse recurso na ferramenta administrativa do Gerenciador de Servidores .
Instale os cmdlets do PowerShell do IntelliTrace.
1. Abra uma janela de comando do PowerShell como administrador.
  1. Escolha Iniciar, Todos os Programas, Acessórios, Windows PowerShell.
  2. Escolha uma das seguintes etapas:
    - Em sistemas operacionais de 64 bits, abra o menu de atalho do Windows PowerShell. Escolha Executar como administrador.
    - Em sistemas operacionais de 32 bits, abra o menu de atalho do Windows PowerShell (x86). Escolha Executar como administrador.
2. Na janela de comando do PowerShell, use o comando Import-Module para importar Microsoft.VisualStudio.IntelliTrace.PowerShell.dll.
  
  Por exemplo:
  
  Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

Configurar permissões para o diretório de arquivos .iTrace

No servidor do aplicativo, crie o diretório de arquivos .iTrace, por exemplo: C:\IntelliTraceLogFiles
Observação
- Para evitar a lentidão do aplicativo, escolha um local em um disco de alta velocidade local que não esteja muito ativo.
  - Você pode colocar arquivos .iTrace e os arquivos do coletor no mesmo lugar. No entanto, se você tiver um aplicativo Web ou aplicativo do SharePoint, verifique se esse local está fora do diretório que hospeda o aplicativo.
Importante
- Restrinja o diretório de arquivos .iTrace somente às identidades que devem funcionar com o coletor. Um arquivo .iTrace pode conter informações confidenciais, como dados de usuários, bancos de dados, outros locais de origem e cadeias de conexão, pois o IntelliTrace pode registrar todos os dados que passam para parâmetros de método ou como valores retornados.
  - Verifique se aqueles que podem abrir arquivos .iTrace têm autoridade para exibir dados confidenciais. Tenha cuidado ao compartilhar arquivos .iTrace. Se outras pessoas precisarem ter acesso, copie os arquivos para um local compartilhado seguro.
Para um aplicativo Web ou aplicativo do SharePoint, conceda ao pool de aplicativos permissões completas para o diretório de arquivos .iTrace. Você pode usar o comando icacls do Windows ou usar o Windows Explorer (ou Explorador de Arquivos).

Por exemplo:
- Para configurar permissões com o comando icacls do Windows:
  - Para um aplicativo Web no pool de aplicativos DefaultAppPool :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F
  - Para um aplicativo do SharePoint no pool de aplicativos do SharePoint – 80 :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F
    
    - ou -
- Para configurar permissões com o Windows Explorer (ou Explorador de Arquivos):
  1. Abra Propriedades para o diretório de arquivos .iTrace.
  2. Na guia Segurança , escolha Editar, Adicionar.
  3. Verifique se principais de segurança integrados esteja selecionado na caixa Selecionar este tipo de objeto. Se ele não estiver lá, escolha Tipos de Objeto para adicioná-lo.
  4. Verifique se o computador local aparece na caixa A partir dessa localização . Se ele não estiver lá, escolha Locais para alterá-lo.
  5. Na caixa Inserir os nomes de objeto a serem selecionados , adicione o pool de aplicativos para o aplicativo Web ou o aplicativo do SharePoint.
  6. Escolha Verificar Nomes para resolver o nome. Escolha OK.
  7. Verifique se o pool de aplicativos tem controle total.

Coletar dados de um aplicativo Web ou aplicativo do SharePoint

Para começar a coletar dados, abra uma janela de comando do PowerShell como administrador e execute este comando:

Start-IntelliTraceCollection " <ApplicationPool>"<PathToCollectionPlan><FullPathToITraceFileDirectory>

Importante

Depois de executar esse comando, digite Y para confirmar se deseja começar a coletar dados.

Por exemplo, para coletar dados de um aplicativo do SharePoint no Pool de aplicativos do SharePoint – 80 :

Start-IntelliTraceCollection "SharePoint - 80" "C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogFiles"

Nome	Description
ApplicationPool	O nome do pool de aplicativos em que o aplicativo é executado
PathToCollectionPlan	O caminho para um plano de coleção, um arquivo .xml que define as configurações para o coletor. Você pode especificar um plano que vem com o coletor. Os planos a seguir funcionam para aplicativos Web e aplicativos do SharePoint: - collection_plan.ASP.NET.default.xml Coleta apenas eventos do IntelliTrace e eventos do SharePoint, incluindo exceções, chamadas de banco de dados e solicitações de servidor Web. - collection_plan.ASP.NET.trace.xml Coleta chamadas de funções e todos os dados dentro de collection_plan.ASP.NET.default.xml. Esse plano é bom para análise detalhada, mas pode diminuir a velocidade do aplicativo mais do que collection_plan.ASP.NET.default.xml. Para evitar a lentidão do aplicativo, personalize esses planos ou crie seu próprio plano. Para segurança, coloque todos os planos personalizados no mesmo local seguro que os arquivos do coletor. Veja Como criar e personalizar planos de coleção do IntelliTrace e como obter o máximo de dados sem diminuir a velocidade do meu aplicativo?Nota: Por padrão, o tamanho máximo do arquivo .iTrace é de 100 MB. Quando o arquivo .iTrace atinge esse limite, o coletor exclui as entradas mais antigas do arquivo para abrir espaço para entradas mais recentes. Para alterar esse limite, edite o atributo de coleção do plano `MaximumLogFileSize`. Onde posso encontrar versões localizadas desses planos de coleção? Você pode encontrar planos adaptados localmente nas subpastas do coletor.
FullPathToITraceFileDirectory	O caminho completo para o diretório de arquivos .iTrace. Observação de segurança: Forneça o caminho completo, não um caminho relativo.

O coletor é anexado ao pool de aplicativos e começa a coletar dados.

Posso abrir o arquivo .iTrace no momento? Não, o arquivo é bloqueado durante a coleta de dados.

Reproduza o problema.
Para criar um ponto de verificação do arquivo .iTrace, use esta sintaxe:

Checkpoint-IntelliTraceCollection " <ApplicationPool>"
Para verificar o status da coleção, use esta sintaxe:

Get-IntelliTraceCollectionStatus
Para interromper a coleta de dados, use esta sintaxe:

Stop-IntelliTraceCollection " <ApplicationPool>"

Importante

Depois de executar esse comando, digite Y para confirmar se deseja parar de coletar dados. Caso contrário, o coletor poderá continuar coletando dados, o arquivo iTrace permanecerá bloqueado ou o arquivo poderá não conter dados úteis.
Abra o arquivo .iTrace no Visual Studio Enterprise

Coletar dados de um aplicativo gerenciado

Para iniciar seu aplicativo e coletar dados ao mesmo tempo, use esta sintaxe:

<FullPathToIntelliTraceCollectorExecutable>\IntelliTraceSC.exe launch /cp:<PathToCollectionPlan>/f:<FullPathToITraceFileDirectoryAndFileName><PathToAppExecutableFileAndFileName>

Por exemplo, para coletar dados de um aplicativo chamado MyApp:

C:IntelliTraceCollectorIntelliTraceSC.exe launch /cp:"C:IntelliTraceCollectorcollection_plan.ASP.NET.default.xml" /f:"C:IntelliTraceLogFilesMyApp.itrace" "C:MyAppMyApp.exe"

Nome	Description
FullPathToIntelliTraceCollectorExecutable	O caminho completo para o executável do coletor, IntelliTraceSC.exe
PathToCollectionPlan	O caminho para um plano de coleção, um arquivo .xml que define as configurações para o coletor. Você pode especificar um plano que vem com o coletor. Os planos a seguir funcionam para aplicativos gerenciados: - collection_plan.ASP.NET.default.xml Coleta somente eventos do IntelliTrace, incluindo exceções, chamadas de banco de dados e solicitações de servidor Web. - collection_plan.ASP.NET.trace.xml Coleta chamadas de funções e todos os dados dentro de collection_plan.ASP.NET.default.xml. Esse plano é bom para análise detalhada, mas pode diminuir a velocidade do aplicativo mais do que collection_plan.ASP.NET.default.xml. Para evitar a lentidão do aplicativo, personalize esses planos ou crie seu próprio plano. Para segurança, coloque todos os planos personalizados no mesmo local seguro que os arquivos do coletor. Veja Como criar e personalizar planos de coleção do IntelliTrace e como obter o máximo de dados sem diminuir a velocidade do meu aplicativo?Nota: Por padrão, o tamanho máximo do arquivo .iTrace é de 100 MB. Quando o arquivo .iTrace atinge esse limite, o coletor exclui as entradas mais antigas do arquivo para abrir espaço para entradas mais recentes. Para alterar esse limite, edite o atributo de coleção do plano `MaximumLogFileSize`. Onde posso encontrar versões localizadas desses planos de coleção? Você pode encontrar planos adaptados localmente nas subpastas do coletor.
FullPathToITraceFileDirectoryAndFileName	O caminho completo para o diretório de arquivos .iTrace e o nome do arquivo .iTrace com a extensão .itrace . Observação de segurança: Forneça o caminho completo, não um caminho relativo.
PathToAppExecutableFileAndFileName	O caminho e o nome do arquivo do aplicativo gerenciado

Interrompa a coleta de dados saindo do aplicativo.
Abra o arquivo .iTrace no Visual Studio Enterprise

Abra o arquivo .iTrace no Visual Studio Enterprise

Observação

Para depurar com o IntelliTrace e percorrer o código passo a passo, você deve ter os arquivos de origem e os arquivos de símbolo correspondentes. Consulte Diagnosticar problemas após a implantação.

Mova o arquivo .iTrace ou copie-o para um computador com o Visual Studio Enterprise (mas não as edições Professional ou Community).
Clique duas vezes no arquivo .iTrace fora do Visual Studio ou abra o arquivo de dentro do Visual Studio.

O Visual Studio mostra a página Resumo do IntelliTrace . Na maioria das seções, você pode examinar eventos ou outros itens, escolher um item e iniciar a depuração com o IntelliTrace no ponto em que e quando um evento aconteceu. Consulte Usando dados do IntelliTrace salvos.

Observação

Para depurar com o IntelliTrace e executar passo a passo o código, você deve ter os arquivos de código-fonte e os arquivos de símbolo correspondentes em sua máquina de desenvolvimento. Consulte Diagnosticar problemas após a implantação.

Como faço para obter o máximo de dados sem diminuir a velocidade do meu aplicativo?

O IntelliTrace pode coletar muitos dados, portanto, o impacto no desempenho do aplicativo depende dos dados coletados pelo IntelliTrace e do tipo de código que ele analisa. Consulte Otimizando a coleção IntelliTrace em servidores de produção.

Aqui estão algumas maneiras de obter o máximo de dados sem diminuir a velocidade do aplicativo:

Execute o coletor somente quando você achar que há um problema ou quando puder reproduzir o problema.

Inicie a coleção, reproduza o problema e, em seguida, interrompa a coleta. Abra o arquivo .iTrace no Visual Studio Enterprise e examine os dados. Consulte Abrir o arquivo .iTrace no Visual Studio Enterprise.
Para aplicativos Web e aplicativos do SharePoint, o coletor registra dados para cada aplicativo que compartilha o pool de aplicativos especificado. Isso pode diminuir a velocidade de qualquer aplicativo que compartilhe o mesmo pool de aplicativos, embora você só possa especificar módulos para um único aplicativo em um plano de coleção.

Para impedir que o coletor reduza o desempenho de outros aplicativos, hospede cada aplicativo em seu próprio pool de aplicação.
Examine os eventos no plano de coleta para o qual o IntelliTrace coleta dados. Edite o plano de coleção para desabilitar eventos que não são relevantes ou não lhe interessam.

Para desabilitar um evento, defina o enabled atributo do elemento como <DiagnosticEventSpecification>false:

<DiagnosticEventSpecification enabled="false">

Se o enabled atributo não existir, o evento será habilitado.

Como isso melhora o desempenho?
- Você pode reduzir o tempo de inicialização desabilitando eventos que não são relevantes para o aplicativo. Por exemplo, desabilite eventos do Fluxo de Trabalho do Windows para aplicativos que não usam o Fluxo de Trabalho do Windows.
- Você pode melhorar o desempenho de inicialização e de tempo de execução desabilitando eventos do Registro para aplicativos que acessam o registro, mas não mostram problemas com as configurações do Registro.
Examine os módulos no plano de coleta para o qual o IntelliTrace coleta dados. Edite o plano de coleção para incluir apenas os módulos que lhe interessam:
1. Abra o plano de coleção. Localize o elemento <ModuleList>.
2. Em <ModuleList>, defina o isExclusionList atributo como false.
3. Use o <Name> elemento para especificar cada módulo com um dos seguintes: nome do arquivo, valor da cadeia de caracteres para incluir qualquer módulo cujo nome contenha essa cadeia de caracteres ou chave pública.
  
  Por exemplo, para coletar dados apenas do módulo Web principal do aplicativo Web Fabrikam Fiber, crie uma lista como esta:
```
<ModuleList isExclusionList="false">
   <Name>FabrikamFiber.Web.dll</Name>
</ModuleList>
```
Para coletar dados de qualquer módulo cujo nome inclua "Fabrikam", crie uma lista como esta:
```
<ModuleList isExclusionList="false">
   <Name>Fabrikam</Name>
</ModuleList>
```
Para coletar dados de módulos especificando seus tokens de chave pública, crie uma lista como esta:
```
<ModuleList isExclusionList="false">
   <Name>PublicKeyToken:B77A5C561934E089</Name>
   <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
   <Name>PublicKeyToken:31BF3856AD364E35</Name>
   <Name>PublicKeyToken:89845DCD8080CC91</Name>
   <Name>PublicKeyToken:71E9BCE111E9429C</Name>
</ModuleList>
```
Como isso melhora o desempenho?

Isso reduz a quantidade de informações de chamada de método e outros dados de instrumentação coletados pelo IntelliTrace quando o aplicativo é iniciado e executado. Esses dados permitem:
- Percorra o código depois de coletar os dados.
- Examine os valores passados e retornados das chamadas de funções.
  
  Por que não excluir módulos em vez disso?
  
  Por padrão, os planos de coleção excluem módulos definindo o isExclusionList atributo como true. No entanto, a exclusão de módulos ainda pode resultar na coleta de dados de módulos que não atendem aos critérios da lista e podem não interessar a você, como módulos de terceiros ou de software livre.
Há dados que o IntelliTrace não coleta?

Sim, para reduzir o impacto no desempenho, o IntelliTrace restringe a coleta de dados a valores de tipos de dados primitivos passados e retornados de métodos e a valores de tipos de dados primitivos em campos em objetos de nível superior passados e retornados de métodos.

Por exemplo, suponha que você tenha uma AlterEmployee assinatura de método que aceite um inteiro id e um Employee objeto oldemployee:

public Employee AlterEmployee(int id, Employee oldemployee)

O Employee tipo tem os seguintes atributos: Id, Namee HomeAddress. Existe uma relação de associação entre Employee e o Address tipo.

O coletor registra valores para id, Employee.Id, Employee.Name e o objeto Employee retornado do método AlterEmployee. No entanto, o coletor não registra informações sobre o Address objeto que não sejam se ele foi nulo ou não. O coletor também não registra dados sobre variáveis locais no método AlterEmployee, a menos que outros métodos usem essas variáveis locais como parâmetros, caso em que são registradas como parâmetros de método.

Onde mais posso obter dados do IntelliTrace?

Você pode obter dados do IntelliTrace de uma sessão de depuração do IntelliTrace no Visual Studio Enterprise. Consulte os recursos do IntelliTrace.

Onde posso obter mais informações?

Usando dados salvos do IntelliTrace

IntelliTrace

Blogs

Usando o Coletor Autônomo do IntelliTrace remotamente

Criando e personalizando planos de coleção do IntelliTrace

Otimizando a coleção IntelliTrace em servidores de produção

Microsoft DevOps

Fóruns

Depurador do Visual Studio

Comentários

Esta página foi útil?

Last updated on 2025-12-12