Utilisation du collecteur autonome IntelliTrace (C#, Visual Basic)

Article
10/14/2023

Le collecteur autonome IntelliTrace vous permet de collecter des données de diagnostic IntelliTrace pour vos applications exécutées sur des serveurs de production ou d’autres environnements, sans avoir à installer Visual Studio sur l’ordinateur cible ni à modifier l’environnement du système cible. Ce collecteur fonctionne avec les applications web, SharePoint, WPF et Windows Forms. Quand vous avez terminé la collecte des données, supprimez simplement le collecteur pour le désinstaller.

Notes

Pour connaître les approches recommandées en vue de diagnostiquer les problèmes sur les serveurs de production, consultez Diagnostiquer les problèmes après le déploiement.

Configuration requise

.NET Framework 3.5 ou version ultérieure
Visual Studio Enterprise (mais pas les éditions Professional ou Community) sur un ordinateur de développement ou autre pour ouvrir les fichiers .iTrace

Remarque

Assurez-vous d’enregistrer vos fichiers de symboles (.pdb). Pour déboguer avec IntelliTrace et exécuter le code pas à pas, vous devez disposer des fichiers sources et des fichiers de symboles correspondants. Consultez Diagnostiquer des problèmes après le déploiement.

FORUM AUX QUESTIONS
Quelles applications fonctionnent avec le collecteur ?
Comment faire pour démarrer ?
Comment puis-je obtenir le maximum de données sans ralentir mon application ?
À quel autre endroit puis-je trouver des données IntelliTrace ?

Quelles applications fonctionnent avec le collecteur ?

Applications web ASP.NET hébergées sur Internet Information Services (IIS) version 7.0, 7.5, 8.0, 12.0 ou 16.0
Applications SharePoint 2010 et SharePoint 2013
Applications Windows Presentation Foundation (WPF) et Windows Forms.

Comment faire pour démarrer ?

Installer le collecteur
Définir les autorisations pour le répertoire du collecteur
Installer les applets de commande PowerShell IntelliTrace pour collecter les données pour les applications web ou les applications SharePoint
Définir les autorisations du répertoire de fichiers .iTrace
Collecter les données d’une application web ou d’une application SharePoint

-ou-

Collecter les données d’une application managée
Ouvrez le fichier .iTrace dans Visual Studio Enterprise

Installer le collecteur

Sur le serveur de votre application, créez le répertoire du collecteur, par exemple : C:\IntelliTraceCollector
Récupérez le collecteur à partir du dossier d’installation de Visual Studio.
1. Copiez IntelliTraceCollection.cab à partir du dossier où le collecteur est installé, par exemple :
  
  ..\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  ou, pour les versions précédentes de Visual Studio :
  
  ..\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0
2. Placez IntelliTraceCollection.cab dans le répertoire du collecteur, par exemple C:\IntelliTraceCollector
Développez IntelliTraceCollection.cab :
1. Sur le serveur de votre application, ouvrez une fenêtre d’invite de commandes en tant qu’administrateur.
2. Accédez au répertoire du collecteur, par exemple C:\IntelliTraceCollector
3. Exécutez la commande expand suivante, avec le point (.) à la fin, pour développer IntelliTraceCollection.cab :
  
  expand /f:* IntelliTraceCollection.cab .
  
  Notes
  
  Le point (.) permet de conserver les sous-dossiers qui contiennent les plans de collecte localisés.

Définir les autorisations pour le répertoire du collecteur

Sur le serveur de votre application, ouvrez une fenêtre d’invite de commandes en tant qu’administrateur.
Utilisez la commande Windows icacls pour accorder à l’administrateur du serveur toutes les autorisations d’accès au répertoire du collecteur. Par exemple :

icacls "C:\IntelliTraceCollector" /grant " <Domain\AdministratorID> ":F
Pour collecter les données d’une application web ou SharePoint :
1. Accordez à l’utilisateur qui exécutera les applets de commande PowerShell IntelliTrace toutes les autorisations d’accès au répertoire du collecteur.
  
  Par exemple :
  
  icacls "C:\IntelliTraceCollector" /grant " <Domain\UserID>> ":F
2. Accordez au pool d’applications hébergeant l’application web ou SharePoint les autorisations de lecture et d’exécution pour le répertoire du collecteur.
  
  Par exemple :
  - Pour une application web du pool d’applications DefaultAppPool :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX
  - Pour une application SharePoint du pool d’applications SharePoint – 80 :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

Installer les applets de commande PowerShell IntelliTrace pour collecter les données pour les applications web ou les applications SharePoint

Sur le serveur de votre application, vérifiez que PowerShell est activé. Dans la plupart des versions de Windows Server, vous pouvez ajouter cette fonctionnalité dans l’outil d’administration Gestionnaire de serveur .
Installez les applets de commande PowerShell IntelliTrace.
1. Ouvrez une fenêtre de commande PowerShell en tant qu’administrateur.
  1. Choisissez Démarrer, Tous les programmes, Accessoires, Windows PowerShell.
  2. Choisissez l’une des étapes suivantes :
    - Sur les systèmes d’exploitation 64 bits, ouvrez le menu contextuel de Windows PowerShell. Sélectionnez Exécuter en tant qu’administrateur.
    - Sur les systèmes d’exploitation 32 bits, ouvrez le menu contextuel de Windows PowerShell (x86). Sélectionnez Exécuter en tant qu’administrateur.
2. Dans la fenêtre Commande PowerShell, utilisez la commande Import-Module pour importer Microsoft.VisualStudio.IntelliTrace.PowerShell.dll.
  
  Par exemple :
  
  Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

Définir les autorisations du répertoire de fichiers .iTrace

Sur le serveur de votre application, créez le répertoire de fichiers .iTrace, par exemple : C:\IntelliTraceLogFiles
Remarque
- Pour éviter de ralentir votre application, choisissez un emplacement sur un disque local rapide et qui n’est pas très actif.
  - Vous pouvez placer les fichiers .iTrace et ceux du collecteur dans le même emplacement. Dans le cas d’une application web ou SharePoint, cet emplacement doit se trouver en dehors du répertoire qui héberge cette application.
Important
- Limitez l’accès au répertoire de fichiers .iTrace uniquement aux identités qui ont besoin d’utiliser le collecteur. Un fichier .iTrace peut contenir des informations sensibles, telles que les données provenant d’utilisateurs, de bases de données ou d’autres emplacements sources, ainsi que des chaînes de connexion. En effet, IntelliTrace est susceptible d’enregistrer toutes les données passées dans les paramètres de méthode ou en tant que valeurs de retour.
  - Assurez-vous que les utilisateurs qui peuvent ouvrir les fichiers .iTrace ont l’autorité pour afficher des données sensibles. Partagez les fichiers .iTrace avec précaution. Si d’autres utilisateurs doivent accéder aux fichiers, copiez ces fichiers dans un emplacement partagé sécurisé.
Pour une application web ou SharePoint, accordez au pool d’applications correspondant toutes les autorisations d’accès au répertoire de fichiers .iTrace. Pour cela, utilisez au choix la commande Windows icacls ou l’Explorateur Windows (ou l’Explorateur de fichiers).

Par exemple :
- Pour définir des autorisations avec la commande Windows icacls :
  - Pour une application web du pool d’applications DefaultAppPool :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F
  - Pour une application SharePoint du pool d’applications SharePoint – 80 :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F
    
    -ou-
- Pour définir des autorisations avec l’Explorateur Windows (ou l’Explorateur de fichiers) :
  1. Ouvrez Propriétés pour le répertoire de fichiers .iTrace.
  2. Sous l’onglet Sécurité , choisissez Modifier, puis Ajouter.
  3. Vérifiez que l’élément Principaux de sécurité intégrés est affiché dans la zone Sélectionnez le type de cet objet . S’il n’y est pas, choisissez Types d’objets pour l’ajouter.
  4. Vérifiez que votre ordinateur local apparaît dans la zone À partir de cet emplacement . S’il n’est pas présent, choisissez Emplacements pour le modifier.
  5. Dans la zone Entrez les noms des objets à sélectionner , ajoutez le pool d’applications de l’application web ou SharePoint.
  6. Choisissez Vérifier les noms pour résoudre le nom. Choisissez OK.
  7. Vérifiez que le pool d’applications dispose des autorisations Contrôle total.

Collecter les données d’une application web ou d’une application SharePoint

Pour démarrer la collecte des données, ouvrez une fenêtre Commande PowerShell en tant qu’administrateur, puis exécutez la commande suivante :

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

Important

Après avoir exécuté cette commande, tapez Y pour confirmer que vous souhaitez démarrer la collecte des données.

Par exemple, pour collecter des données d’une application SharePoint exécutée dans le pool d’applications SharePoint - 80 , exécutez :

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

Nom	Description
ApplicationPool	Nom du pool d’applications dans lequel votre application s’exécute.
PathToCollectionPlan	Chemin d’accès à un plan de collecte, un fichier .xml qui configure les paramètres du collecteur. Vous pouvez spécifier un plan qui est fourni avec le collecteur. Les plans suivants fonctionnent avec les applications web et SharePoint : - collection_plan.ASP.NET.default.xml Collecte uniquement les événements IntelliTrace et les événements SharePoint, y compris les exceptions, les appels de base de données et les demandes de serveur web. - collection_plan.ASP.NET.trace.xml Collecte les appels de fonction et toutes les données du plan collection_plan.ASP.NET.default.xml. Ce plan est approprié pour une analyse détaillée, mais il risque de ralentir votre application davantage que le plan collection_plan.ASP.NET.default.xml. Pour éviter de ralentir votre application, personnalisez ces plans ou créez votre propre plan. Pour des raisons de sécurité, placez tous les plans personnalisés dans le même emplacement sécurisé que les fichiers du collecteur. Consultez la section Créer et personnaliser des plans de collecte IntelliTrace et Comment puis-je obtenir le maximum de données sans ralentir mon application ? Remarque : Par défaut, la taille maximale du fichier .iTrace est de 100 Mo. Quand le fichier .iTrace atteint cette limite, le collecteur supprime les entrées les plus anciennes du fichier pour faire de la place aux nouvelles entrées. Pour changer cette limite, modifiez l’attribut `MaximumLogFileSize` du plan de collecte. Où puis-je trouver des versions localisées de ces plans de collecte ? Les plans de collecte localisés sont situés dans les sous-dossiers du collecteur.
FullPathToITraceFileDirectory	Chemin d’accès complet au répertoire de fichiers .iTrace. Note de sécurité : Spécifiez le chemin complet et non pas un chemin relatif.

Le collecteur se connecte au pool d’applications et commence la collecte de données.

Puis-je ouvrir le fichier .iTrace en même temps ? Non. Le fichier est verrouillé pendant la collecte des données.

Reproduisez le problème.
Pour créer un point de contrôle du fichier .iTrace, utilisez la syntaxe suivante :

Checkpoint-IntelliTraceCollection " <ApplicationPool> "
Pour vérifier l’état de la collecte, utilisez la syntaxe suivante :

Get-IntelliTraceCollectionStatus
Pour arrêter la collecte de données, utilisez la syntaxe suivante :

Stop-IntelliTraceCollection " <ApplicationPool> "

Important

Après avoir exécuté cette commande, tapez Y pour confirmer que vous souhaitez arrêter la collecte de données. Sinon, le collecteur risque de continuer la collecte des données, le fichier iTrace restera verrouillé ou le fichier ne contiendra peut-être aucunes données utiles.
Ouvrez le fichier .iTrace dans Visual Studio Enterprise

Collecter les données d’une application managée

Pour démarrer votre application et collecter des données en même temps, utilisez la syntaxe suivante :

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

Par exemple, pour collecter des données d’une application nommée MyApp, exécutez :

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

Nom	Description
FullPathToIntelliTraceCollectorExecutable	Chemin d’accès complet à l’exécutable du collecteur (IntelliTraceSC.exe).
PathToCollectionPlan	Chemin d’accès à un plan de collecte, un fichier .xml qui configure les paramètres du collecteur. Vous pouvez spécifier un plan qui est fourni avec le collecteur. Les plans suivants fonctionnent avec les applications managées : - collection_plan.ASP.NET.default.xml Collecte uniquement les événements IntelliTrace, y compris les exceptions, les appels de base de données et les demandes de serveur web. - collection_plan.ASP.NET.trace.xml Collecte les appels de fonction et toutes les données du plan collection_plan.ASP.NET.default.xml. Ce plan est approprié pour une analyse détaillée, mais il risque de ralentir votre application davantage que le plan collection_plan.ASP.NET.default.xml. Pour éviter de ralentir votre application, personnalisez ces plans ou créez votre propre plan. Pour des raisons de sécurité, placez tous les plans personnalisés dans le même emplacement sécurisé que les fichiers du collecteur. Consultez la section Créer et personnaliser des plans de collecte IntelliTrace et Comment puis-je obtenir le maximum de données sans ralentir mon application ? Remarque : Par défaut, la taille maximale du fichier .iTrace est de 100 Mo. Quand le fichier .iTrace atteint cette limite, le collecteur supprime les entrées les plus anciennes du fichier pour faire de la place aux nouvelles entrées. Pour changer cette limite, modifiez l’attribut `MaximumLogFileSize` du plan de collecte. Où puis-je trouver des versions localisées de ces plans de collecte ? Les plans de collecte localisés sont situés dans les sous-dossiers du collecteur.
FullPathToITraceFileDirectoryAndFileName	Chemin d’accès complet au répertoire du fichier .iTrace et nom du fichier .iTrace avec l’extension .itrace . Note de sécurité : Spécifiez le chemin complet et non pas un chemin relatif.
PathToAppExecutableFileAndFileName	Chemin d’accès et nom de fichier de votre application managée.

Arrêtez la collecte de données en quittant l’application.
Ouvrez le fichier .iTrace dans Visual Studio Enterprise

Ouvrez le fichier .iTrace dans Visual Studio Enterprise

Notes

Pour déboguer avec IntelliTrace et exécuter le code pas à pas, vous devez disposer des fichiers sources et des fichiers de symboles correspondants. Consultez Diagnostiquer des problèmes après le déploiement.

Déplacez le fichier .iTrace ou copiez-le sur un ordinateur équipé de Visual Studio Enterprise (mais pas les éditions Professional ou Community).
Double-cliquez sur le fichier .iTrace en dehors de Visual Studio ou ouvrez le fichier à partir de Visual Studio.

Visual Studio affiche la page Résumé IntelliTrace . Dans la plupart des sections, vous pouvez passer en revue les événements ou autres éléments enregistrés, choisir un élément, puis commencer le débogage avec IntelliTrace à partir de l’endroit et du moment où l’événement s’est produit. Consultez Utilisation des données IntelliTrace enregistrées.

Notes

Pour déboguer avec IntelliTrace et exécuter le code pas à pas, vous devez disposer des fichiers sources et des fichiers de symboles correspondants sur votre ordinateur de développement. Consultez Diagnostiquer des problèmes après le déploiement.

Comment puis-je obtenir le maximum de données sans ralentir mon application ?

IntelliTrace peut collecter beaucoup de données. L’impact de la collecte sur les performances de votre application dépend donc de la quantité de données collectées et du type de code analysé par IntelliTrace. Consultez Optimisation de la collecte IntelliTrace sur les serveurs de production.

Voici quelques méthodes permettant d’obtenir le maximum de données sans ralentir votre application :

Exécutez le collecteur uniquement si vous soupçonnez un problème ou si vous pouvez reproduire le problème.

Démarrez la collecte, reproduisez le problème, puis arrêtez la collecte. Ouvrez le fichier .iTrace dans Visual Studio Enterprise et examinez les données. Consultez Ouvrez le fichier .iTrace dans Visual Studio Enterprise.
Pour les applications web et SharePoint, le collecteur enregistre les données pour chaque application partageant le pool d’applications spécifié. La collecte peut donc ralentir n’importe quelle application partageant le même pool d’applications, même si vous choisissez de limiter la collecte aux modules d’une seule application dans un plan de collecte.

Pour empêcher le collecteur de ralentir d’autres applications, hébergez chaque application dans son propre pool d’applications.
Passez en revue les événements du plan de collecte pour lesquels IntelliTrace collecte des données. Modifiez le plan de collecte en y désactivant les événements qui ne sont pas pertinents ou qui ne vous intéressent pas.

Pour désactiver un événement, définissez l’attribut enabled pour l’élément <DiagnosticEventSpecification> avec la valeur false:

<DiagnosticEventSpecification enabled="false">

Si l’attribut enabled n’existe pas, l’événement est activé.

Comment cela améliore-t-il les performances ?
- Réduisez le temps de démarrage en désactivant les événements qui ne sont pas pertinents pour l’application. Par exemple, désactivez les événements Windows Workflow pour les applications qui n’utilisent pas Windows Workflow.
- Vous pouvez améliorer les performances de démarrage et d’exécution en désactivant les événements de Registre pour les applications qui accèdent au Registre, mais qui n’affichent pas les problèmes liés aux paramètres du Registre.
Passez en revue les modules du plan de collecte pour lesquels IntelliTrace collecte des données. Modifiez le plan de collecte en y incluant seulement les modules qui vous intéressent :
1. Ouvrez le plan de collecte. Recherchez l’élément <ModuleList>.
2. Dans <ModuleList>, définissez l’attribut isExclusionList avec la valeur false.
3. Utilisez l’élément <Name> pour spécifier chaque module avec un des éléments suivants : nom de fichier, valeur de chaîne pour inclure un module dont le nom contient cette chaîne, ou clé publique.
  
  Par exemple, pour collecter uniquement des données du module web principal pour l’application web Fabrikam Fiber, créez une liste comme celle-ci :
```
<ModuleList isExclusionList="false">
   <Name>FabrikamFiber.Web.dll</Name>
</ModuleList>
```
Pour collecter des données d’un module dont le nom inclut « Fabrikam », créez une liste comme celle-ci :
```
<ModuleList isExclusionList="false">
   <Name>Fabrikam</Name>
</ModuleList>
```
Pour collecter des données de modules en spécifiant leurs jetons de clé publique, créez une liste comme celle-ci :
```
<ModuleList isExclusionList="false">
   <Name>PublicKeyToken:B77A5C561934E089</Name>
   <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
   <Name>PublicKeyToken:31BF3856AD364E35</Name>
   <Name>PublicKeyToken:89845DCD8080CC91</Name>
   <Name>PublicKeyToken:71E9BCE111E9429C</Name>
</ModuleList>
```
Comment cela améliore-t-il les performances ?

Cela réduit la quantité d’informations sur les appels de méthode et autres données d’instrumentation qu’IntelliTrace collecte quand l’application démarre et s’exécute. Avec ces données, vous pouvez :
- parcourir le code après la collecte des données ;
- examiner les valeurs passées aux appels de fonction et les valeurs de retour correspondantes.
  
  Pourquoi ne pas exclure des modules à la place ?
  
  Par défaut, les plans de collecte excluent les modules en définissant l’attribut isExclusionList avec la valeur true. Toutefois, malgré l’exclusion des modules, il est possible que des données soient collectées dans des modules qui ne répondent pas aux critères de la liste d’exclusion ou qui ne vous intéressent pas (par exemple, les modules tiers ou open source).
Y a-t-il des données qu’IntelliTrace ne collecte pas ?

Oui. Pour réduire l’impact sur les performances, IntelliTrace limite la collecte des données aux valeurs de types de données primitives qui sont passées à et retournées par les méthodes ainsi qu’aux valeurs de types de données primitives dans les champs sur les objets de niveau supérieur qui sont passés à et retournés par les méthodes.

Par exemple, supposons que vous avez une signature de méthode AlterEmployee qui accepte un id entier et un objet Employeeoldemployee:

public Employee AlterEmployee(int id, Employee oldemployee)

Le type Employee a les attributs suivants : Id, Nameet HomeAddress. Une relation d’association existe entre Employee et le type Address .

Le collecteur enregistre les valeurs pour id, Employee.Id, Employee.Name et l’objet Employee retourné par la méthode AlterEmployee . Toutefois, le collecteur n’enregistre pas d’informations sur l’objet Address (il indique seulement si cet objet a ou non une valeur null). Le collecteur n’enregistre pas non plus de données sur les variables locales de la méthode AlterEmployee , sauf si d’autres méthodes utilisent ces variables locales en tant que paramètres (elles sont alors enregistrées en tant que paramètres de méthode).

À quel autre endroit puis-je trouver des données IntelliTrace ?

Vous pouvez obtenir des données IntelliTrace à partir d’une session de débogage IntelliTrace dans Visual Studio Enterprise. Consultez Fonctionnalités IntelliTrace.