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

O coletor autônomo 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 na máquina de destino e sem alterar o ambiente do sistema de destino. O coletor autônomo IntelliTrace funciona em aplicativos Web, SharePoint, WPF e Windows Forms. Quando terminar de coletar dados, basta excluir o coletor para desinstalá-lo.

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 as edições Professional ou Community) num computador de desenvolvimento ou noutro computador para abrir arquivos .iTrace

Observação

Certifique-se de salvar seus arquivos de símbolo (.pdb). Para depurar com o IntelliTrace e percorrer o código, 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 posso começar?
Como posso obter o máximo de dados sem tornar a minha aplicação mais lenta?
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 Windows Presentation Foundation (WPF) e Windows Forms.

Como é que chego começo?

Instalar o coletor
Configurar permissões para o diretório do coletor
Instalar cmdlets do IntelliTrace PowerShell para coletar dados para aplicativos Web ou aplicativos do SharePoint
Configurar permissões para o diretório do arquivo .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 onde 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 da aplicação, abra uma janela de linha de comandos como administrador.
2. Navegue até o diretório do coletor, por exemplo: C:\IntelliTraceCollector
3. Use o comando expandir , incluindo o ponto (.) 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 da aplicação, abra uma janela de linha de comandos como administrador.
Use o comando icacls do Windows para conceder ao administrador do servidor permissões totais para o diretório do coletor. Por exemplo:

icacls "C:\IntelliTraceCollector" /grant " <Domínio\ID do Administrador>":F
Para coletar dados para um aplicativo Web ou aplicativo do SharePoint:
1. Conceda à pessoa que executará os cmdlets do IntelliTrace PowerShell permissões totais para o diretório do coletor.
  
  Por exemplo:
  
  icacls "C:\IntelliTraceCollector" /grant " <Domínio\UserID>":F
2. Dê permissões de leitura e execução ao pool de aplicações para a aplicação Web ou aplicação do SharePoint no 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 IntelliTrace PowerShell para coletar dados para aplicativos Web ou aplicativos do SharePoint

No servidor do seu aplicativo, verifique se o PowerShell está habilitado. Na maioria das versões do Windows Server, você pode adicionar esse recurso na ferramenta administrativa Gerenciador do Servidor .
Instale os cmdlets do IntelliTrace PowerShell.
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 do arquivo .iTrace

No servidor do aplicativo, crie o diretório de arquivo .iTrace, por exemplo: C:\IntelliTraceLogFiles
Observação
- Para evitar tornar seu aplicativo lento, escolha um local em um disco de alta velocidade local que não esteja muito ativo.
  - Você pode colocar os arquivos .iTrace e os arquivos do coletor no mesmo lugar. No entanto, se você tiver um aplicativo Web ou um aplicativo do SharePoint, verifique se esse local está fora do diretório que hospeda o aplicativo.
Importante
- Restrinja o diretório do arquivo .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 quaisquer dados que passam para parâmetros de método ou como valores de retorno.
  - Certifique-se de que aqueles que podem abrir arquivos .iTrace tenham autoridade para visualizar 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 totais para o diretório do arquivo .iTrace. Pode utilizar o comando icacls do Windows ou utilizar o Explorador do Windows (ou Explorador de Ficheiros).

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 Explorador do Windows (ou Explorador de Ficheiros):
  1. Abra as Propriedades do diretório do arquivo .iTrace.
  2. Na guia Segurança , escolha Editar, Adicionar.
  3. Verifique se Entidades de segurança integradas aparece na caixa de seleção Selecionar este tipo de objeto. Se não estiver lá, escolha Tipos de objeto para adicioná-lo.
  4. Verifique se o computador local aparece na caixa de De este local. Se não estiver lá, escolha Locais para alterá-lo.
  5. Na caixa Digite os nomes dos objetos a serem selecionados , adicione o pool de aplicativos para o aplicativo Web ou 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 que 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 onde o aplicativo é executado
PathToCollectionPlan	O caminho para um plano de coleção, um arquivo de .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 do servidor Web. - collection_plan.ASP.NET.trace.xml Coleta chamadas de função e todos os dados em collection_plan.ASP.NET.default.xml. Esse plano é bom para análises detalhadas, mas pode tornar seu aplicativo mais lento do que collection_plan.ASP.NET.default.xml. Para evitar tornar seu aplicativo lento, personalize esses planos ou crie seu próprio plano. Por segurança, coloque todos os planos personalizados no mesmo local seguro que os arquivos do coletor. Consulte Criação e personalização de planos de coleta do IntelliTrace e Como obter o máximo de dados sem tornar meu aplicativo lento?Observação: 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 este limite, edite o atributo `MaximumLogFileSize` do plano de coleção. Onde posso encontrar versões localizadas destes planos de recolha? Você pode encontrar planos localizados nas subpastas do coletor.
FullPathToITraceFileDirectory	O caminho completo para o diretório do arquivo .iTrace. Nota 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 neste momento? Não, o ficheiro está bloqueado durante a recolha 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 parar de coletar dados, use esta sintaxe:

Stop-IntelliTraceCollection " <ApplicationPool>"

Importante

Depois de executar esse comando, digite Y para confirmar que 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:

<FullPathToIntelliTraceCollectorExecutável>\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
FullPathToIntelliTraceCollectorExecutável	O caminho completo para o executável do coletor, IntelliTraceSC.exe
PathToCollectionPlan	O caminho para um plano de coleção, um arquivo de .xml que define as configurações para o coletor. Você pode especificar um plano que vem com o coletor. Os seguintes planos 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ção e todos os dados em collection_plan.ASP.NET.default.xml. Esse plano é bom para análises detalhadas, mas pode tornar seu aplicativo mais lento do que collection_plan.ASP.NET.default.xml. Para evitar tornar seu aplicativo lento, personalize esses planos ou crie seu próprio plano. Por segurança, coloque todos os planos personalizados no mesmo local seguro que os arquivos do coletor. Consulte Criação e personalização de planos de coleta do IntelliTrace e Como obter o máximo de dados sem tornar meu aplicativo lento?Observação: 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 este limite, edite o atributo `MaximumLogFileSize` do plano de coleção. Onde posso encontrar versões localizadas destes planos de recolha? Você pode encontrar planos localizados nas subpastas do coletor.
FullPathToITraceFileDirectoryAndFileName	O caminho completo para o diretório do arquivo .iTrace e o nome do arquivo .iTrace com a extensão .itrace . Nota de segurança: Forneça o caminho completo, não um caminho relativo.
PathToAppExecutableFileAndFileName	O caminho e o nome do arquivo do seu aplicativo gerenciado

Pare 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, 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 revisar 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 salvos do IntelliTrace.

Observação

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

Como posso obter o máximo de dados sem tornar a minha aplicação lenta?

O IntelliTrace pode recolher muitos dados, pelo que o impacto no desempenho da sua aplicação depende dos dados que o IntelliTrace recolhe e do tipo de código que analisa. Consulte Otimizando a coleta do IntelliTrace em servidores de produção.

Eis algumas formas de obter o máximo de dados sem tornar a sua aplicação mais lenta:

Execute o coletor somente quando achar que há um problema ou quando puder reproduzi-lo.

Inicie a recolha, reproduza o problema e, em seguida, pare a recolha. 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 tornar mais lento qualquer aplicativo que compartilhe o mesmo pool de aplicativos, mesmo que você só possa especificar módulos para um único aplicativo em um plano de coleta.

Para evitar que o coletor de lixo torne outros aplicativos lentos, hospede cada aplicativo em seu próprio pool de aplicativos.
Analise os eventos no plano de coleta para os quais o IntelliTrace coleta dados. Edite o plano de recolha para desativar eventos que não são relevantes ou que não lhe interessam.

Para desativar um evento, defina o enabled atributo para o <DiagnosticEventSpecification> elemento como false:

<DiagnosticEventSpecification enabled="false">

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

Como isso melhora o desempenho?
- Pode reduzir o tempo de arranque desativando eventos que não são relevantes para a aplicação. Por exemplo, desative os 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 em 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.
Analise os módulos no plano de coleta para os quais o IntelliTrace coleta dados. Edite o plano de recolha para incluir apenas os módulos que lhe interessam:
1. Abra o plano de cobrança. Encontre 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 Fibra, 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 que o IntelliTrace coleta quando o aplicativo é iniciado e executado. Estes dados permitem-lhe:
- Analise o código depois de recolher os dados.
- Examine os valores passados e retornados de chamadas de função.
  
  Por que não excluir módulos?
  
  Por padrão, os planos de coleta 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 lhe interessar, como módulos de terceiros ou de código aberto.
Existem dados que o IntelliTrace não recolhe?

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 assinatura de método AlterEmployee que aceita um id inteiro e um objeto Employeeoldemployee.

public Employee AlterEmployee(int id, Employee oldemployee)

O Employee tipo tem os seguintes atributos: Id, Name, e 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 pelo método AlterEmployee. No entanto, o coletor não registra informações sobre o Address objeto além de se ele era nulo ou não. O coletor também não registra dados sobre variáveis locais no método, a menos que outros métodos usem essas variáveis locais como parâmetros, momento em que elas são registradas como parâmetros do AlterEmployee método.