IntelliTrace スタンドアロン コレクターの使用 (C#、Visual Basic)
IntelliTrace スタンドアロン コレクター を使用すると、対象コンピューターに Visual Studio をインストールしたり、対象システムの環境を変更したりすることなく、運用サーバーまたは他の環境でアプリの IntelliTrace 診断データを収集できます。 IntelliTrace スタンドアロン コレクターは、Web、SharePoint、WPF、および Windows フォーム アプリで動作します。 データを収集したら、コレクターを削除して、アンインストールします。
注意
運用サーバーの問題を診断するための推奨される方法については、「配置後の問題の診断」を参照してください。
必要条件
.NET Framework 3.5 以降
.iTrace ファイルを開くための、開発用コンピューターまたは別のコンピューター上の Visual Studio Enterprise (Professional Edition でも Community Edition でもなく)
注意
必ずシンボル (.pdb) ファイルを保存してください。 IntelliTrace でデバッグおよびコードのステップ実行を行うには、対応するソース ファイルとシンボル ファイルが必要です。 「配置後の問題の診断」を参照してください。
FAQ
コレクターで使用できるアプリ
インターネット インフォメーション サービス (IIS) バージョン 7.0、7.5、8.0、12.0、および 16.0 上でホストされる ASP.NET Web アプリ
SharePoint 2010 アプリケーションと SharePoint 2013 アプリケーション
Windows Presentation Foundation (WPF) および Windows フォーム アプリ。
開始するには?
Web アプリまたは SharePoint アプリケーションのデータを収集するための IntelliTrace PowerShell コマンドレットをインストールする
Web アプリまたは SharePoint アプリケーションからデータを収集する
\- または -
コレクターのインストール
アプリのサーバーで、コレクター ディレクトリ (たとえば、C:\IntelliTraceCollector) を参照します。
Visual Studio インストール フォルダーからコレクターを取得します。
次のようにコレクターがインストールされているフォルダーから IntelliTraceCollection.cab をコピーします。
..\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
または、以前のバージョンの Visual Studio の場合:
..\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0
IntelliTraceCollection.cab をコレクター ディレクトリ (たとえば、C:\IntelliTraceCollector) にプットします。
IntelliTraceCollection.cab を展開します。
ご利用のアプリのサーバーで、管理者としてコマンド プロンプト ウィンドウを開きます。
コレクター ディレクトリ (たとえば、C:\IntelliTraceCollector) を参照します。
末尾のピリオド ( . ) も含めてexpandコマンドを使用して、IntelliTraceCollection.cab を展開します。
expand /f:* IntelliTraceCollection.cab .注意
ピリオド ( . ) を指定することにより、ローカライズされた収集計画を含むサブフォルダーが保持されます。
コレクター ディレクトリのアクセス許可を設定する
ご利用のアプリのサーバーで、管理者としてコマンド プロンプト ウィンドウを開きます。
Windows の icacls コマンドを使用して、サーバー管理者に、コレクター ディレクトリに対する完全なアクセス許可を与えます。 次に例を示します。
icacls "C:\IntelliTraceCollector" /grant "<Domain\AdministratorID>":FWeb アプリまたは SharePoint アプリケーションのデータを収集するには:
IntelliTrace PowerShell コマンドレットを実行するユーザーに、コレクター ディレクトリに対する完全なアクセス許可を与えます。
次に例を示します。
icacls "C:\IntelliTraceCollector" /grant "<Domain\UserID>":FWeb アプリまたは SharePoint アプリケーションのアプリケーション プールに、コレクター ディレクトリに対する読み取りおよび実行アクセス許可を与えます。
次に例を示します。
DefaultAppPool アプリケーション プールの Web アプリの場合:
icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RXSharePoint - 80 アプリケーション プールの SharePoint アプリケーションの場合:
icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX
Web アプリまたは SharePoint アプリケーションのデータを収集するための IntelliTrace PowerShell コマンドレットをインストールする
ご利用のアプリのサーバー上で、PowerShell が有効になっていることを確認します。 Windows Server のほとんどのバージョンでは、 サーバー マネージャー 管理ツールを使用してこの機能を追加できます。
IntelliTrace PowerShell コマンドレットをインストールします。
管理者として PowerShell コマンド ウィンドウを開きます。
[スタート] 、 [すべてのプログラム] 、 [アクセサリ] 、 [Windows PowerShell] の順に選択します。
次のいずれかの操作を実行します。
64 ビット オペレーティング システムでは、 [Windows PowerShell] のショートカット メニューを開きます。 [管理者として実行] を選択します。
32 ビット オペレーティング システムでは、 [Windows PowerShell (x86)] のショートカット メニューを開きます。 [管理者として実行] を選択します。
PowerShell コマンド ウィンドウで、 Import-Module コマンドを使用して Microsoft.VisualStudio.IntelliTrace.PowerShell.dllをインポートします。
次に例を示します。
Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"
.iTrace ファイル ディレクトリのアクセス許可を設定する
アプリのサーバーで、.iTrace ファイル ディレクトリ (たとえば、C:\IntelliTraceLogFiles) を作成します。
注意
- ご利用のアプリの処理が低下するのを回避するには、あまりアクティブではないローカルの高速なディスク上の場所を選択してください。
- .iTrace ファイルとコレクター ファイルは同じ場所に配置できます。 ただし、Web アプリまたは SharePoint アプリケーションがある場合は、この場所がアプリケーションをホストするディレクトリの外部にあることを確認します。
重要
- .iTrace ファイル ディレクトリへのアクセスを、コレクターを使用する必要がある ID のみに制限します。 IntelliTrace はメソッド パラメーターに渡されるデータや戻り値として渡されるデータを記録できるため、ユーザー、データベース、その他のソースの場所、および接続文字列のデータなどの重要情報が .iTrace ファイルに含まれることがあります。
- .iTrace ファイルを開くことができるユーザーが、重要情報を表示する権限が与えられているユーザーであることを確認します。 .iTrace ファイルを共有する場合は注意してください。 他のユーザーがアクセスを必要とするときは、安全な共有の場所にファイルをコピーします。
- ご利用のアプリの処理が低下するのを回避するには、あまりアクティブではないローカルの高速なディスク上の場所を選択してください。
Web アプリまたは SharePoint アプリケーションのアプリケーション プールに、.iTrace ファイル ディレクトリに対する完全なアクセス許可を与えます。 Windows の icacls コマンドまたはエクスプローラー (またはファイル エクスプローラー) を使用できます。
次に例を示します。
Windows の icacls コマンドを使用してアクセス許可を設定するには:
DefaultAppPool アプリケーション プールの Web アプリの場合:
icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":FSharePoint - 80 アプリケーション プールの SharePoint アプリケーションの場合:
icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F\- または -
エクスプローラー (またはファイル エクスプローラー) を使用してアクセス許可を設定するには:
.iTrace ファイル ディレクトリの [プロパティ] を開きます。
[セキュリティ] タブで、 [編集] 、 [追加] を順に選択します。
[オブジェクトの種類を選択してください] ボックスに [ビルトイン セキュリティ プリンシパル] が表示されることを確認します。 表示されない場合は、 [オブジェクトの種類] を選択してこれを追加します。
ローカル コンピューターが [場所の指定] ボックスに表示されることを確認します。 表示されない場合は、 [場所] を選択してこれを追加します。
[選択するオブジェクト名を入力してください] ボックスに、Web アプリまたは SharePoint アプリケーションのアプリケーション プールを追加します。
[名前の確認] を選択して名前を解決します。 [OK] をクリックします。
アプリケーション プールに対して フル コントロールのアクセス許可が設定されていることを確認します。
Web アプリまたは SharePoint アプリケーションからデータを収集する
データの収集を開始するには、PowerShell のコマンド ウィンドウを管理者として開き、次のコマンドを実行します。
Start-IntelliTraceCollection"<ApplicationPool>"<PathToCollectionPlan> <FullPathToITraceFileDirectory>重要
このコマンドを実行した後、「 Y 」と入力してデータ収集を開始することを確認します。
たとえば、 SharePoint - 80 アプリケーション プールの SharePoint アプリケーションからデータを収集するには、次のように入力します。
Start-IntelliTraceCollection "SharePoint - 80" "C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogFiles"名前 説明 ApplicationPool アプリケーションが実行されるアプリケーション プールの名前 PathToCollectionPlan 収集計画 (コレクターの設定を構成する .xml ファイル) へのパス。
コレクターに付属する計画を指定できます。 次の計画は、Web アプリと SharePoint アプリケーションに対して動作します。
- collection_plan.ASP.NET.default.xml
例外、データベース呼び出し、および Web サーバー要求を含む IntelliTrace イベントと SharePoint イベントのみを収集します。
- collection_plan.ASP.NET.trace.xml
関数呼び出しと、collection_plan.ASP.NET.default.xml のすべてのデータを収集します。 この計画は詳細な分析に適していますが、collection_plan.ASP.NET.default.xml よりもアプリの速度が低下する場合があります。
アプリの速度が低下するのを回避するには、これらの計画をカスタマイズするか、独自に計画を作成します。 セキュリティのために、コレクター ファイルと同じ安全な場所にカスタム計画を配置します。 IntelliTrace 収集計画の作成およびカスタマイズに関する記事と、「アプリのパフォーマンスの低下なしにほとんどのデータを取得する方法」を参照してください。注: 既定では、.iTrace ファイルの最大サイズは 100 MB です。 .iTrace ファイルがこの制限に達すると、ファイル中の最も古いエントリが削除され、新しいエントリを記録する場所が確保されます。 この制限を変更するには、収集計画のMaximumLogFileSize属性を編集します。
これらの収集計画のローカライズ バージョンはどこで見つけられますか。
ローカライズされた計画は、コレクターのサブフォルダーに格納されています。FullPathToITraceFileDirectory .iTrace ファイル ディレクトリへの完全パス。 セキュリティに関する注意: 相対パスではなく、完全なパスを指定します。 コレクターがアプリケーション プールにアタッチされ、データ収集が開始されます。
この時点で .iTrace ファイルを表示できますか。 いいえ。データ収集中はファイルがロックされます。
問題を再現します。
.iTrace ファイルのチェックポイントを作成するには、次の構文を使用します。
Checkpoint-IntelliTraceCollection"<ApplicationPool>"コレクションの実行状態を確認するには、次の構文を使用します。
Get-IntelliTraceCollectionStatusデータ収集を停止するには、次の構文を使用します。
Stop-IntelliTraceCollection"<ApplicationPool>"重要
このコマンドを実行した後、「 Y 」と入力してデータ収集を停止することを確認します。 この操作を行わないと、コレクターはデータを収集し続けます。iTrace ファイルはロックされたままになり、ファイルに有用なデータが含まれなくなる可能性があります。
マネージド アプリからのデータの収集
アプリを起動すると同時にデータの収集を開始するには、次の構文を使用します。
<FullPathToIntelliTraceCollectorExecutable>
\IntelliTraceSC.exe launch /cp:<PathToCollectionPlan>/f:<FullPathToITraceFileDirectoryAndFileName> <PathToAppExecutableFileAndFileName>たとえば、 MyAppという名前のアプリからデータを収集するには、次のように入力します。
C:IntelliTraceCollectorIntelliTraceSC.exe launch /cp:"C:IntelliTraceCollectorcollection_plan.ASP.NET.default.xml" /f:"C:IntelliTraceLogFilesMyApp.itrace" "C:MyAppMyApp.exe"名前 説明 FullPathToIntelliTraceCollectorExecutable コレクターの実行可能ファイルである IntelliTraceSC.exe への完全パス。 PathToCollectionPlan 収集計画 (コレクターの設定を構成する .xml ファイル) へのパス。
コレクターに付属する計画を指定できます。 次の計画は、マネージド アプリに対して動作します。
- collection_plan.ASP.NET.default.xml
例外、データベース呼び出し、および Web サーバー要求を含む IntelliTrace イベントのみを収集します。
- collection_plan.ASP.NET.trace.xml
関数呼び出しと、collection_plan.ASP.NET.default.xml のすべてのデータを収集します。 この計画は詳細な分析に適していますが、collection_plan.ASP.NET.default.xml よりもアプリの速度が低下する場合があります。
アプリの速度が低下するのを回避するには、これらの計画をカスタマイズするか、独自に計画を作成します。 セキュリティのために、コレクター ファイルと同じ安全な場所にカスタム計画を配置します。 IntelliTrace 収集計画の作成およびカスタマイズに関する記事と、「アプリのパフォーマンスの低下なしにほとんどのデータを取得する方法」を参照してください。注: 既定では、.iTrace ファイルの最大サイズは 100 MB です。 .iTrace ファイルがこの制限に達すると、ファイル中の最も古いエントリが削除され、新しいエントリを記録する場所が確保されます。 この制限を変更するには、収集計画のMaximumLogFileSize属性を編集します。
これらの収集計画のローカライズ バージョンはどこで見つけられますか。
ローカライズされた計画は、コレクターのサブフォルダーに格納されています。FullPathToITraceFileDirectoryAndFileName .iTrace ファイル ディレクトリへの完全パスと、拡張子 .itrace を含む .iTrace ファイル名。 セキュリティに関する注意: 相対パスではなく、完全なパスを指定します。 PathToAppExecutableFileAndFileName マネージド アプリのパスとファイル名。 アプリを終了し、データ収集を停止します。
Visual Studio Enterprise で .iTrace ファイルを開く
Note
IntelliTrace でデバッグおよびコードのステップ実行を行うには、対応するソース ファイルとシンボル ファイルが必要です。 「配置後の問題の診断」を参照してください。
Visual Studio Enterprise (Professional Edition でも Community Edition でもなく) がインストールされたコンピューターに、.iTrace ファイルを移動またはコピーします。
Visual Studio の外部で .iTrace ファイルをダブルクリックするか、Visual Studio 内からファイルを開きます。
Visual Studio に [IntelliTrace の概要] ページが表示されます。 ほとんどのセクションにおいて、イベントまたは他の項目を確認したうえで項目を選択し、イベントが発生したポイントで IntelliTrace を使用してデバッグを開始できます。 「保存された IntelliTrace データの使用」を参照してください。
Note
IntelliTrace でデバッグおよびコードのステップ実行を行うには、対応するソース ファイルとシンボル ファイルが開発コンピューターに必要です。 「配置後の問題の診断」を参照してください。
アプリのパフォーマンスの低下なしにほとんどのデータを取得する方法
IntelliTrace では大量のデータを収集できます。そのため、アプリのパフォーマンスへの影響は、IntelliTrace で収集するデータの種類、および分析するコードの種類によって決まります。 「 運用サーバーでの IntelliTrace 収集の最適化」を参照してください。
アプリのパフォーマンスが低下することなく、ほとんどのデータを取得する方法を次に示します。
問題があると思われる場合や、問題を再現できる場合にのみ、コレクターを実行します。
収集を開始し、問題を再現し、収集を停止します。 Visual Studio Enterprise で .iTrace ファイルを開き、データを確認します。 「 Visual Studio Enterprise で .iTrace ファイルを開くよりもパフォーマンスに及ぼす影響が少なくなります。
Web アプリおよび SharePoint アプリケーションの場合、コレクターは、指定されたアプリケーション プールを共有するすべてのアプリのデータを記録します。 そのため、収集計画で指定できるのは 1 つのアプリのモジュールのみであるにもかかわらず、同じアプリケーション プールを共有するすべてのアプリの速度が低下する可能性があります。
コレクターによって他のアプリの速度が低下するのを回避するためには、それぞれのアプリを専用のアプリケーション プールでホストします。
IntelliTrace がデータを収集する計画のイベントを確認します。 関連性のない、または希望しないイベントを無効にするよう、収集計画を編集します。
イベントを無効にするには、次のように
enabled要素の<DiagnosticEventSpecification>属性をfalseに設定します。<DiagnosticEventSpecification enabled="false">enabled属性がない場合、イベントが有効になります。これにより、どのようにパフォーマンスが向上しますか。
アプリに関連しないイベントを無効にすると、起動時間を短縮できます。 たとえば、Windows Workflow を使用しないアプリの Windows Workflow イベントを無効にします。
レジストリにアクセスするアプリのレジストリ イベントを無効にすると、起動およびランタイムのパフォーマンスは向上し、レジストリ設定に関する問題は見られません。
IntelliTrace がデータを収集する収集計画のモジュールを確認します。 目的のモジュールのみ含めるように収集計画を編集します。
収集計画を開きます。
<ModuleList>要素を検索します。<ModuleList>で、isExclusionList属性をfalseに設定します。<Name>要素を使用して、ファイル名、文字列が名前を含まれるモジュールを含む文字列値、または公開キーのいずれかで各モジュールを指定します。たとえば、Fabrikam Fiber Web アプリの通常のメイン Web モジュールからデータを収集するには、次のようなリストを作成します。
<ModuleList isExclusionList="false"> <Name>FabrikamFiber.Web.dll</Name> </ModuleList>名前に "Fabrikam" が含まれるモジュールからデータを収集するには、次のようなリストを作成します。
<ModuleList isExclusionList="false"> <Name>Fabrikam</Name> </ModuleList>公開キー トークンを指定してモジュールからデータを収集するには、次のようなリストを作成します。
<ModuleList isExclusionList="false"> <Name>PublicKeyToken:B77A5C561934E089</Name> <Name>PublicKeyToken:B03F5F7F11D50A3A</Name> <Name>PublicKeyToken:31BF3856AD364E35</Name> <Name>PublicKeyToken:89845DCD8080CC91</Name> <Name>PublicKeyToken:71E9BCE111E9429C</Name> </ModuleList>これにより、どのようにパフォーマンスが向上しますか。
これにより、メソッド呼び出し情報、およびアプリの開始時と実行時に IntelliTrace が収集するその他のインストルメンテーション データの量が減少します。 このデータにより、次のことができます。
データ収集後にコードをステップ実行します。
関数呼び出しとの間で受け渡しされる値を確認します。
なぜ代わりにモジュールを除外しないのですか。
既定では、収集計画は
isExclusionList属性をtrueに設定してモジュールを除外します。 ただし、モジュールを除外しても、リストの条件を満たさないモジュール、必要がない可能性があるサードパーティまたはオープン ソース モジュールなどのモジュールからのデータを収集してしまう可能性があります。
IntelliTrace が収集しないデータはありますか。
はい。パフォーマンスへの影響を抑えるために、IntelliTrace は、データ収集を、メソッドと受け渡しをするプリミティブ データ型の値、およびメソッドと受け渡しをする最上位レベルのオブジェクトのフィールドのプリミティブ データ型の値に制限しています。
たとえば、次のように整数の
AlterEmployeeとidオブジェクトのEmployeeを受け取るoldemployeeメソッド シグネチャがあるとします。public Employee AlterEmployee(int id, Employee oldemployee)Employeeの型には、Id、Name、およびHomeAddressの各属性が含まれます。Employeeの型とAddressの型との間に、アソシエーション リレーションシップの関係が存在します。
コレクターは、
idメソッドから返された、Employee.Id、Employee.Name、Employee、およびAlterEmployeeの各オブジェクトの値を記録します。 ただし、null であるかどうかの情報を除き、Addressオブジェクトについての情報は記録しません。 コレクターは、メソッド パラメーターとして記録される時点のパラメーターとしてそれらのローカル変数を他のメソッドが使用する場合を除き、AlterEmployeeメソッドのローカル変数に関するデータは記録しません。
IntelliTrace データを取得できるその他の場所
Visual Studio Enterprise で IntelliTrace デバッグ セッションから IntelliTrace データを取得できます。 「IntelliTrace の機能」を参照してください。
情報の入手方法
ブログ
Using the IntelliTrace Standalone Collector Remotely (リモートで IntelliTrace スタンドアロン コレクターを使用する)