Uso dell'agente di raccolta autonomo IntelliTrace (C#, Visual Basic)

Articolo
10/14/2023

L' agente di raccolta autonomo IntelliTrace consente di raccogliere i dati diagnostici di IntelliTrace per le app nei server di produzione o in altri ambienti senza installare Visual Studio nel computer di destinazione e senza cambiare l'ambiente del sistema di destinazione. L'agente di raccolta autonomo IntelliTrace funziona nelle app Web, SharePoint, WPF e Windows Form. Al termine della raccolta dei dati, eliminare semplicemente l'agente di raccolta per disinstallarlo.

Nota

Per gli approcci consigliati per la diagnosi dei problemi nei server di produzione, vedere Diagnosticare i problemi dopo la distribuzione.

Requisiti

.NET Framework 3.5 o versione successiva
Visual Studio Enterprise (ma non edizioni Professional o Community) in un computer di sviluppo o in un altro computer per aprire i file .iTrace

Nota

Assicurarsi di salvare i file di simboli (PDB). Per eseguire il debug con IntelliTrace ed eseguire il codice seguendo un'istruzione alla volta sono necessari i file di origine corrispondenti e i file di simboli. Vedere Diagnosticare i problemi dopo la distribuzione.

Domande frequenti
Quali app funzionano con l'agente di raccolta?
Come iniziare
Come è possibile ottenere il maggior numero possibile di dati senza rallentare l'applicazione?
In quali altre posizioni è possibile ottenere i dati IntelliTrace?

Quali app funzionano con l'agente di raccolta?

ASP.NET app Web ospitate in Internet Information Services (IIS) versione 7.0, 7.5, 8.0, 12.0 e 16.0
Applicazioni SharePoint 2010 e SharePoint 2013
App Windows Presentation Foundation (WPF) e Windows Form.

Come posso iniziare a utilizzare il prodotto?

Installare l'agente di raccolta
Impostare autorizzazioni per la directory dell'agente di raccolta
Installare i cmdlet di PowerShell IntelliTrace per raccogliere dati per le applicazioni Web o le applicazioni di SharePoint
Impostare autorizzazioni per la directory di file con estensione iTrace
Raccogliere i dati da un'applicazione Web o da un'applicazione SharePoint

-o-

Raccogliere i dati da un'app gestita
Aprire il file .iTrace in Visual Studio Enterprise

Installare l'agente di raccolta

Nel server dell'app creare la directory dell'agente di raccolta, ad esempio C:\IntelliTraceCollector
Ottenere l'agente di raccolta dalla cartella di installazione di Visual Studio.
1. Copiare IntelliTraceCollection.cab dalla cartella in cui è installato l'agente di raccolta, ad esempio:
  
  .. \Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  oppure, per le versioni precedenti di Visual Studio:
  
  .. \Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0
2. Inserire IntelliTraceCollection.cab nella directory dell'agente di raccolta, ad esempio: C:\IntelliTraceCollector
Espandere IntelliTraceCollection.cab:
1. Nel server dell'app aprire una finestra del prompt dei comandi come amministratore.
2. Cercare la directory dell'agente di raccolta, ad esempio: C:\IntelliTraceCollector
3. Usare il comando expand , incluso il punto (.) alla fine, per espandere IntelliTraceCollection.cab:
  
  expand /f:* IntelliTraceCollection.cab .
  
  Nota
  
  Il punto (.) lascia inalterate le sottocartelle che contengono i piani di raccolta localizzati.

Impostare autorizzazioni per la directory dell'agente di raccolta

Nel server dell'app aprire una finestra del prompt dei comandi come amministratore.
Usare il comando di Windows icacls per concedere all'amministratore del server le autorizzazioni complete per la directory dell'agente di raccolta. Ad esempio:

icacls "C:\IntelliTraceCollector" /grant "<Domain\Amministrazione istratorID>":F
Per raccogliere dati per un'app Web o un'applicazione SharePoint:
1. Concedere alla persona che esegue i cmdlet PowerShell di IntelliTrace le autorizzazioni complete per la directory dell'agente di raccolta.
  
  Ad esempio:
  
  icacls "C:\IntelliTraceCollector" /grant "<Domain\UserID>":F
2. Concedere al pool di applicazioni per l'app Web o l'applicazione SharePoint le autorizzazioni di lettura ed esecuzione per la directory dell'agente di raccolta.
  
  Ad esempio:
  - Per un'app Web nel pool di applicazioni DefaultAppPool :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX
  - Per un'applicazione SharePoint nel pool di applicazioni SharePoint - 80 :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

Installare i cmdlet di PowerShell IntelliTrace per raccogliere dati per le applicazioni Web o le applicazioni di SharePoint

Nel server dell'app, verificare che PowerShell sia abilitato. Nella maggior parte delle versioni di Windows Server, è possibile aggiungere questa funzionalità nello strumento di amministrazione Server Manager .
Installare i cmdlet PowerShell di IntelliTrace.
1. Aprire una finestra di comando di PowerShell come amministratore.
  1. Scegliere Start, Tutti i programmi, Accessori, Windows PowerShell.
  2. Scegliere uno dei passaggi seguenti:
    - Nei sistemi operativi a 64 bit, aprire il menu di scelta rapida per Windows PowerShell. Scegliere Esegui come amministratore.
    - Nei sistemi operativi a 32 bit, aprire il menu di scelta rapida per Windows PowerShell (x86). Scegliere Esegui come amministratore.
2. Nella finestra di comando PowerShell, usare il comando Import-Module per importare Microsoft.VisualStudio.IntelliTrace.PowerShell.dll.
  
  Ad esempio:
  
  Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

Impostare autorizzazioni per la directory di file con estensione iTrace

Nel server dell'app creare la directory di file .iTrace, ad esempio: C:\IntelliTraceLogFiles
Nota
- Per evitare il rallentamento dell'app, scegliere una posizione in un disco ad alta velocità locale non troppo attivo.
  - I file .iTrace e quelli dell'agente di raccolta possono essere inseriti nella stessa posizione. Tuttavia, se si ha un'app Web o un'applicazione SharePoint, verificare che questa posizione non sia all'interno della directory che ospita l'applicazione.
Importante
- Limitare la directory di file .iTrace solo alle identità che devono lavorare con l'agente di raccolta. Un file .iTrace può contenere informazioni riservate, ad esempio dati degli utenti, database, altri percorsi di origine e stringhe di connessione, perché IntelliTrace è in grado di registrare tutti i dati che passano nei parametri del metodo o come valori restituiti.
  - Assicurarsi che le persone che possono aprire i file .iTrace dispongano delle autorizzazioni per la visualizzazione dei dati riservati. Usare prudenza quando si condividono file .iTrace. Se è necessario concedere l'accesso ad altri, copiare i file in un percorso condiviso sicuro.
Per un'app Web o un'applicazione SharePoint, concedere al pool di applicazioni le autorizzazioni complete per la directory di file .iTrace. È possibile usare il comando Windows icacls oppure Esplora risorse (o Esplora file).

Ad esempio:
- Per configurare le autorizzazioni con il comando Windows icacls :
  - Per un'app Web nel pool di applicazioni DefaultAppPool :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F
  - Per un'applicazione SharePoint nel pool di applicazioni SharePoint - 80 :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F
    
    -o-
- Per configurare le autorizzazioni con Esplora risorse (o Esplora file):
  1. Aprire Proprietà per directory di file .iTrace.
  2. Nella scheda Sicurezza , scegliere Modifica, Aggiungi.
  3. Verificare che Entità di sicurezza predefinite sia visualizzato nella casella Selezionare questo tipo di oggetto . Se non è disponibile, scegliere Tipi di oggetto per aggiungerlo.
  4. Verificare che il computer locale sia visualizzato nella casella Da questo percorso . Se non è disponibile, scegliere Percorsi per modificarlo.
  5. Nella casella Immettere i nomi degli oggetti da selezionare aggiungere il pool di applicazioni per l'app Web o l'applicazione SharePoint.
  6. Scegliere Controlla nomi per risolvere il nome. Scegliere OK.
  7. Verificare che il pool di applicazioni abbia il Controllo completo.

Raccogliere i dati da un'applicazione Web o da un'applicazione SharePoint

Per avviare la raccolta dei dati, aprire una finestra di comando PowerShell come amministratore, quindi eseguire il comando:

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

Importante

Dopo aver eseguito il comando, digitare Y per confermare che si vuole iniziare la raccolta dei dati.

Ad esempio, per raccogliere i dati da un'applicazione SharePoint nel pool di applicazioni SharePoint - 80 :

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

Nome	Descrizione
ApplicationPool	Il nome del pool di applicazioni in cui viene eseguita l'applicazione
PathToCollectionPlan	Il percorso di un piano di raccolta, un file XML che configura le impostazioni per l'agente di raccolta. È possibile specificare un piano fornito insieme all'agente di raccolta. I seguenti piani si applicano alle app Web e alle applicazioni: - collection_plan.ASP.NET.default.xml Raccoglie solo gli eventi IntelliTrace e SharePoint, incluse le eccezioni, le chiamate al database e le richieste del server Web. - collection_plan.ASP.NET.trace.xml Raccoglie le chiamate di funzione e tutti i dati in collection_plan.ASP.NET.default.xml. Questo piano è utile per un'analisi dettagliata, ma può causare un rallentamento dell'app maggiore rispetto a collection_plan.ASP.NET.default.xml. Per evitare il rallentamento dell'app, personalizzare i piani o creare proprio piano. Per garantire la sicurezza, inserire i piani personalizzati nello stesso percorso sicuro in cui si trovano i file dell'agente di raccolta. Vedi Creazione e personalizzazione di piani di raccolta IntelliTrace e Ricerca per categorie ottenere il maggior numero di dati senza rallentare l'app?Nota: per impostazione predefinita, la dimensione massima del file con estensione iTrace è 100 MB. Quando il file .iTrace raggiunge il limite, l'agente di raccolta elimina le voci meno recenti del file per liberare spazio per le nuove voci. Per modificare questo limite, modificare l'attributo `MaximumLogFileSize` del piano di raccolta. Dove si possono trovare le versioni localizzate di questi piani di raccolta? I piani localizzati sono disponibili nelle sottocartelle dell'agente di raccolta.
FullPathToITraceFileDirectory	Il percorso completo alla directory di file .iTrace. Nota sulla sicurezza: specificare il percorso completo, non un percorso relativo.

L'agente di raccolta si collega al pool di applicazioni e avvia la raccolta dei dati.

È possibile aprire il file .iTrace in questo momento? No, il file è bloccato durante la raccolta dei dati.

Riprodurre il problema.
Per creare un checkpoint del file con estensione iTrace, usare questa sintassi:

Checkpoint-IntelliTraceCollection"<ApplicationPool>"
Per controllare lo stato della raccolta, usare questa sintassi:

Get-IntelliTraceCollectionStatus
Per arrestare la raccolta dei dati, usare questa sintassi:

Stop-IntelliTraceCollection"<ApplicationPool>"

Importante

Dopo aver eseguito il comando, digitare Y per confermare che si vuole arrestare la raccolta dei dati. In caso contrario, l'agente di raccolta potrebbe continuare la raccolta dei dati, il file iTrace resta bloccato o il file potrebbe non contenere dati utili.
Aprire il file .iTrace in Visual Studio Enterprise

Raccogliere i dati da un'app gestita

Per avviare l'app e raccogliere i dati allo stesso tempo, usare questa sintassi:

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

Ad esempio, per raccogliere i dati da un'app denominata MyApp:

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

Nome	Descrizione
FullPathToIntelliTraceCollectorExecutable	Il percorso completo al file eseguibile dell'agente di raccolta, IntelliTraceSC.exe
PathToCollectionPlan	Il percorso di un piano di raccolta, un file XML che configura le impostazioni per l'agente di raccolta. È possibile specificare un piano fornito insieme all'agente di raccolta. I seguenti piani si applicano alle app gestite: - collection_plan.ASP.NET.default.xml Raccoglie solo gli eventi IntelliTrace, incluse le eccezioni, le chiamate al database e le richieste del server Web. - collection_plan.ASP.NET.trace.xml Raccoglie le chiamate di funzione e tutti i dati in collection_plan.ASP.NET.default.xml. Questo piano è utile per un'analisi dettagliata, ma può causare un rallentamento dell'app maggiore rispetto a collection_plan.ASP.NET.default.xml. Per evitare il rallentamento dell'app, personalizzare i piani o creare proprio piano. Per garantire la sicurezza, inserire i piani personalizzati nello stesso percorso sicuro in cui si trovano i file dell'agente di raccolta. Vedi Creazione e personalizzazione di piani di raccolta IntelliTrace e Ricerca per categorie ottenere il maggior numero di dati senza rallentare l'app?Nota: per impostazione predefinita, la dimensione massima del file con estensione iTrace è 100 MB. Quando il file .iTrace raggiunge il limite, l'agente di raccolta elimina le voci meno recenti del file per liberare spazio per le nuove voci. Per modificare questo limite, modificare l'attributo `MaximumLogFileSize` del piano di raccolta. Dove si possono trovare le versioni localizzate di questi piani di raccolta? I piani localizzati sono disponibili nelle sottocartelle dell'agente di raccolta.
FullPathToITraceFileDirectoryAndFileName	Il percorso completo alla directory di file .iTrace e il nome del file .iTrace con estensione .itrace . Nota sulla sicurezza: specificare il percorso completo, non un percorso relativo.
PathToAppExecutableFileAndFileName	Il percorso e il nome file dell'app gestita

Arrestare la raccolta dei dati uscendo dall'app.
Aprire il file .iTrace in Visual Studio Enterprise

Aprire il file .iTrace in Visual Studio Enterprise

Nota

Per eseguire il debug con IntelliTrace ed eseguire il codice seguendo un'istruzione alla volta sono necessari i file di origine corrispondenti e i file di simboli. Vedere Diagnosticare i problemi dopo la distribuzione.

Spostare il file .iTrace o copiarlo in un computer con Visual Studio Enterprise (ma non edizioni Professional o Community).
Fare doppio clic sul file .iTrace all'esterno di Visual Studio oppure aprire il file da Visual Studio.

Visual Studio visualizza la pagina Riepilogo di IntelliTrace . Nella maggior parte delle sezioni è possibile esaminare gli eventi o altri elementi, scegliere un elemento e avviare il debug con IntelliTrace nel punto e nell'ora in cui si è verificato l'evento. Vedere Uso dei dati IntelliTrace salvati.

Nota

Per eseguire il debug con IntelliTrace ed eseguire il codice seguendo un'istruzione alla volta sono necessari i file di origine corrispondenti e i file di simboli nel computer di sviluppo. Vedere Diagnosticare i problemi dopo la distribuzione.

Come è possibile ottenere il maggior numero possibile di dati senza rallentare l'applicazione?

IntelliTrace può raccogliere grandi quantità di dati: l'impatto sulle prestazioni dell'app dipende dai dati raccolti da IntelliTrace e dal tipo di codice analizzato. Vedere Ottimizzazione della raccolta IntelliTrace nei server di produzione.

Esistono dei metodi per ottenere la maggior quantità di dati possibile senza rallentare l'app:

Eseguire l'agente di raccolta solo quando si ritiene ci sia un problema o quando è possibile riprodurre il problema.

Avviare la raccolta, riprodurre il problema, quindi arrestare la raccolta. Aprire il file .iTrace in Visual Studio Enterprise ed esaminare i dati. Vedere Aprire il file .iTrace in Visual Studio Enterprise.
Per le app Web e le applicazioni SharePoint, l'agente di raccolta registra i dati per ciascuna app che condivide il pool di applicazioni specificato. Questo potrebbe rallentare le app che condividono lo stesso pool di applicazioni, anche se è possibile specificare solo i mobili per una singola app in un piano di raccolta.

Per impedire che l'agente di raccolta rallenti le altre app, ospitare ciascuna app nel proprio pool di applicazioni.
Esaminare gli eventi nel piano di raccolta per il quale IntelliTrace raccoglie i dati. Modificare il piano di raccolta per disabilitare gli eventi non rilevanti o interessanti.

Per disabilitare un evento, impostare l'attributo enabled per l'elemento <DiagnosticEventSpecification> su false:

<DiagnosticEventSpecification enabled="false">

Se l'attributo enabled non esiste, l'evento è abilitato.

In che modo queste funzionalità migliorano le prestazioni?
- È possibile ridurre il tempo di avvio disabilitando gli eventi non rilevanti per l'app. Ad esempio, disabilitare gli eventi di Windows Workflow nelle app che non lo usano.
- È possibile migliorare le prestazioni di avvio e di runtime disabilitando gli eventi del Registro di sistema per le app che accedono al Registro di sistema, ma non mostrano problemi con le impostazioni del Registro di sistema.
Esaminare i moduli nel piano di raccolta per il quale IntelliTrace raccoglie i dati. Modificare il piano di raccolta per includere solo i moduli desiderati:
1. Aprire il piano di raccolta. Trovare l'elemento <ModuleList>.
2. In <ModuleList>, impostare l'attributo isExclusionList su false.
3. Usare l'elemento <Name> per specificare i singoli moduli con uno degli elementi seguenti: nome file, valore della stringa per includere tutti i moduli il cui nome contiene la stringa specificata oppure chiave pubblica.
  
  Ad esempio, per raccogliere i dati solo dal modulo Web principale dell'app Web Fabrikam Fiber, creare un elenco come questo visualizzato di seguito:
```
<ModuleList isExclusionList="false">
   <Name>FabrikamFiber.Web.dll</Name>
</ModuleList>
```
Per raccogliere i dati dai moduli il cui nome include "Fabrikam", creare un elenco come questo visualizzato di seguito:
```
<ModuleList isExclusionList="false">
   <Name>Fabrikam</Name>
</ModuleList>
```
Per raccogliere i dati dai moduli specificando i relativi token della chiave pubblica, creare un elenco come questo visualizzato di seguito:
```
<ModuleList isExclusionList="false">
   <Name>PublicKeyToken:B77A5C561934E089</Name>
   <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
   <Name>PublicKeyToken:31BF3856AD364E35</Name>
   <Name>PublicKeyToken:89845DCD8080CC91</Name>
   <Name>PublicKeyToken:71E9BCE111E9429C</Name>
</ModuleList>
```
In che modo queste funzionalità migliorano le prestazioni?

Viene ridotta la quantità di informazioni relativa alla chiamata al metodo e gli altri dati di strumentazione raccolti da IntelliTrace quando l'app viene avviata ed eseguita. Questi dati consentono di:
- Eseguire il codice seguendo un'istruzione alla volta dopo aver raccolto i dati.
- Esaminare i valori passati e restituiti dalle chiamate di funzione.
  
  Perché non si sceglie di escludere i moduli, invece?
  
  Per impostazione predefinita, i piani di raccolta escludono i moduli impostando l'attributo isExclusionList su true. Tuttavia, anche escludendo i moduli, è possibile che i dati vengano raccolti da moduli che non corrispondono ai criteri dell'elenco e che potrebbero quindi essere poco rilevanti, ad esempio moduli di terze parti o open source.
Ci sono dati che IntelliTrace non raccoglie?

Sì. Per ridurre l'impatto sulle prestazioni, IntelliTrace limita la raccolta dei dati ai valori dei tipi di dati primitivi passati e restituiti dai metodi e ai valori dei tipi di dati primitivi nei campi degli oggetti di primo livello passati e restituiti dai metodi.

Ad esempio, si supponga di avere una firma del metodo AlterEmployee che accetta un numero intero id e un oggetto Employeeoldemployee:

public Employee AlterEmployee(int id, Employee oldemployee)

Il tipo Employee ha i seguenti attributi: Id, Namee HomeAddress. Esiste una relazione di associazione tra Employee e il tipo Address .

L'agente di raccolta registra i valori per id, Employee.Id, Employee.Name e l'oggetto Employee restituito dal metodo AlterEmployee . Tuttavia, l'agente di raccolta non registra le informazioni sull'oggetto Address , tranne quelle relative allo stato null o non null. L'agente di raccolta non registra neanche i dati relativi alle variabili locali nel metodo AlterEmployee a meno che altri metodi non usino tali variabili come parametri; in questo caso, vengono registrate come parametri del metodo.