dotTrace 2024.3 ヘルプ

API を使用したプロファイリングセッションの制御

プロファイリング API(英語) は、プロファイリングプロセスを制御できるようにする多数のクラスを提供します。例: アプリケーションのコードから、次のことができます。

  • プロファイリングデータの収集を開始する: MeasureProfiler.StartCollectingData() ,

  • データ収集を停止する: MeasureProfiler.StopCollectingData() ,

  • データをディスクに保存する: MeasureProfiler.SaveData() ,

  • その他

API クラスの詳細については、API 参照を参照してください。

プロファイリング API を使用する必要がある主なシナリオは 2 つあります。

コードの特定の部分をプロファイリングする

API を使用すると、分析範囲を絞り込み、関心のあるコードのみをプロファイルすることができます。たとえば、適切なタイミングでスナップショットを取得するボタンをクリックするのはそれほど簡単ではありません。プロファイリング API を使用すると、コードの正確な時点で「スナップショットを取得する」呼び出しを実行できます。

dotTrace 2018.3 以前では、別のバージョンのプロファイリング API が使用されていたことに注意してください (この API の詳細については、dotTrace 2018.3 のドキュメントを参照してください)。この API は引き続きサポートされていますが、このセクションで説明する最新の API バージョンを使用することを強くお勧めします。

主な概念

  • API のソースコードは GitHub(英語) で入手できます。コードは Apache ライセンスで配布されています。

  • プロファイリング API は、プロジェクトで参照する必要がある JetBrains.Profiler.API(英語) NuGet パッケージとして配布されています。

  • API を有効にするには、プロファイラーオプションで有効なプロファイリングを制御する方法 | API の使用パラメーターを使用してプロファイリングセッションを開始する必要があります。

  • API を使用する場合、通常のプロファイリングセッションと比較した場合の唯一の違いは、セッションの制御方法です。プロファイリングコントローラーのボタンをクリックする代わりに、対応する API メソッドを呼び出します。

  • プロファイリングなしでアプリケーションを実行すると、API メソッドの呼び出しは無視されます。API はエラーをスローしません。

  • プロファイリングセッションを制御するために使用する必要がある主なクラスは MeasureProfiler 静的クラスです。

  • プロファイリングデータの収集を開始するには、MeasureProfiler.StartCollectingData() を呼び出します。これは、プロファイリングコントローラーの開始ボタンを押すのと同じです。

  • データの収集を中止してディスクに保存するには、MeasureProfiler.SaveData() を呼び出します。これは、スナップショットを取得して待機するボタンを押すのと同じことです。

  • 保存せずにデータを削除するには、MeasureProfiler.DropData() を呼び出します。これは、ドロップボタンを押すのと同じです。

  • データをディスクに保存せずにプロファイリングデータの収集を中止するには、MeasureProfiler.StopCollectingData() を呼び出します。通常、この方法を使用する必要はありません。この方法はタイムラインプロファイリングタイプには適用されず、プロファイラによって無視されることに注意してください。

  • Windows では、タイムラインプロファイリングには ETW サービスをバックグラウンドで実行する必要があります。このサービスを開始するには、管理者権限が必要です。このため、プロファイリングセッションを開始するたびに、dotTrace は権限の昇格を求めます。これを回避するには、<dotTrace_installation_directory>\x64\JetBrains.ETW.Collector.Host.exe ファイルを使用してサービスを手動で実行します。別のオプションとして、<dotTrace_installation_directory>\Msi.x64\EtwService.msi インストールファイルを使用してサービスをインストールすることもできます。この場合、サービスは Windows の起動時に実行されます。

    macOS および Linux では、タイムラインプロファイリングに外部サービスは必要ありません。

コードの特定部分のプロファイリングに API を使用するには

  1. プロジェクトで JetBrains.Profiler.API NuGet パッケージを参照してください。

  2. ユースケースに応じて、MeasureProfiler クラスのメソッドへの呼び出しをコードに挿入します。例:

    private void SomeMethod() { MeasureProfiler.StartCollectingData(); ... // Here goes some code that I want to profile MeasureProfiler.SaveData(); }
  3. dotTrace、JetBrains Rider、または Visual Studio 内からアプリケーションのプロファイリングを開始し、プロファイラーオプションプロファイリングを制御する方法 | API の使用パラメーターを選択します。*

自己プロファイルアプリケーションを作成する

名前が示すように、このシナリオでは、アプリケーションが自身をプロファイルします。前のシナリオとの主な違いは、プロファイリングを開始する方法です。プロファイリング API を使用してコードの特定の部分をプロファイルする場合は、セッションを手動で開始します (たとえば、dotTrace UI を使用)。自己プロファイルされたアプリケーションの場合、セッションはアプリケーションコードから直接開始されます。

主な概念

  • セルフプロファイリング API は、プロジェクトで参照する必要がある別個の JetBrains.Profiler.SelfApi(英語) NuGet パッケージです。

  • プロファイリングセッションを制御するために、API は dotTrace コマンドラインツールを使用します。

  • コマンドラインツールはパッケージの一部ではありません。 DotTrace.EnsurePrerequisite() メソッドを使用して API を初期化すると、API は最新バージョンの JetBrains.dotTrace.CommandLineTools NuGet パッケージ(Windows(英語)Linux(英語)macOS(英語))をダウンロードします。

  • デフォルトでは、パッケージのツールは %LOCALAPPDATA%\JetBrains\Profiler フォルダーに保存されます。別の場所を指定するには、 DotTrace.EnsurePrerequisite() メソッドの downloadTo 引数を使用します。

  • ツールを含むパッケージがすでに存在する場合、新しいパッケージはダウンロードされません。

  • たとえば、保存されたスナップショットのパスを指定するなど、プロファイリングセッションを構成するには、 DotTrace.Config クラスのインスタンスを使用する必要があります。

  • プロファイリングセッションを開始するには、 DotTrace.Attach() メソッドを呼び出して、プロファイラーをアプリケーションプロセスにアタッチする必要があります。プロファイリング構成(DotTrace.Config のインスタンス)がある場合は、それを引数として指定する必要があります: DotTrace.Attach(config)

  • DotTrace.Attach() はプロファイリングデータの収集を開始しません。これを行うには、 DotTrace.StartCollectingData() メソッドを呼び出す必要があります。

  • セルフプロファイリング API はプロセスにアタッチされるため、使用可能なプロファイリングタイプに制限があります。デフォルトでは、API はサンプリングプロファイリングタイプを使用します。または、タイムラインプロファイリングタイプを使用することもできます。これを行うには、 DotTrace.Config クラスの UseTimelineProfilingType() メソッドを使用する必要があります。

  • パフォーマンスのスナップショットを取得するには、 DotTrace.SaveData() メソッドを呼び出します。スナップショットは、DotTrace.Config で指定されたディレクトリに保存されます。プロファイリング構成がない場合、スナップショットはアプリケーションの作業ディレクトリに保存されます。

  • DotTrace.SaveData() を呼び出した後、プロファイラーはデータの収集を停止することに注意してください。データの収集を再開するには、DotTrace.StartCollectingData() をもう一度呼び出す必要があります。

  • プロファイリングセッションを終了するには、 DotTrace.Detach() メソッドを呼び出します。

  • セルフプロファイリング API は、プロファイリング API と同時に使用できます。

アプリケーションに自己プロファイリングを追加するには

  1. プロジェクトで JetBrains.Profiler.SelfApi NuGet パッケージを参照してください。

  2. DotTrace.EnsurePrerequisite() メソッドを呼び出して、セルフプロファイリング API を初期化します。API が dotTrace コマンドラインツールをダウンロードする必要があるため、最初の初期化には時間がかかる場合があります。ダウンロードプロセスを追跡し、それをキャンセルする機能がある場合は、DotTrace.EnsurePrerequisitesAsync() メソッドを直接使用します。CancellationToken を使用し、コールバック変数を使用して進行状況を追跡できます。

  3. ユースケースの必要に応じて API 呼び出しを追加します。

    • スナップショットが 1 つだけ必要な場合:

      static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.EnsurePrerequisite(); // config that sets the save directory var config = new DotTrace.Config(); config.SaveToDir("C:\\Temp\\Snapshot"); // start profiling session DotTrace.Attach(config); // start collecting data DotTrace.StartCollectingData(); SomeMethod(); // end session DotTrace.Detach(); } private void SomeMethod() { ... // here goes some code that I want to profile // get a snapshot and save it DotTrace.SaveData(); }
    • 複数のスナップショットが必要な場合:

      static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.EnsurePrerequisite(); // config that sets the save directory var config = new DotTrace.Config(); config.SaveToDir("C:\\Temp\\Snapshot"); // start profiling session DotTrace.Attach(config); // start collecting data DotTrace.StartCollectingData(); SomeMethod(); // end session DotTrace.Detach(); } private void SomeMethod(IEnumerable<String> collection) { foreach (var item in collection) { ... // here goes some code that I want to profile // get a snapshot and save it DotTrace.SaveData(); // start collecting data again DotTrace.StartCollectingData(); } }