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 を使用するには
プロジェクトで
JetBrains.Profiler.APINuGet パッケージを参照してください。ユースケースに応じて、
MeasureProfilerクラスのメソッドへの呼び出しをコードに挿入します。 例えば:private void SomeMethod() { MeasureProfiler.StartCollectingData(); ... // Here goes some code that I want to profile MeasureProfiler.SaveData(); }dotTrace、JetBrains Rider または Visual Studio からアプリケーションのプロファイリングを開始し、 プロファイラーオプションで プロファイリングを制御する方法 | API の使用 パラメーターを選択します。 *
自己プロファイルアプリケーションを作成する
名前が示すように、このシナリオでは、アプリケーションが自身をプロファイルします。 前のシナリオとの主な違いは、プロファイリングを開始する方法です。 プロファイリング APIを使用してコードの特定部分をプロファイルする場合は、セッションを手動で開始します (例えば、dotTrace UI を使用)。 自己プロファイルされたアプリケーションの場合、セッションはアプリケーションコードから直接開始されます。
主な概念
セルフプロファイリング API は、プロジェクトで参照する必要がある別個の JetBrains.Profiler.SelfApi(英語) NuGet パッケージです。
プロファイリングセッションを制御するために、API は dotTrace コマンドラインツールを使用します。
コマンドラインツールはパッケージの一部ではありません。
DotTrace.Init()メソッドを使用して API を初期化すると、API は最新バージョンの JetBrains.dotTrace.CommandLineTools NuGet パッケージ(Windows(英語)、 Linux(英語)、 macOS(英語) )をダウンロードします。デフォルトでは、パッケージのツールは %LOCALAPPDATA%\JetBrains\Profiler フォルダーに保存されます。 別の場所を指定するには、
DotTrace.Init()メソッドの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 と同時に使用できます。
アプリケーションに自己プロファイリングを追加するには
プロジェクトで
JetBrains.Profiler.SelfApiNuGet パッケージを参照してください。DotTrace.Init()メソッドを呼び出して、自己プロファイル API を初期化します。 API が dotTrace コマンドラインツールをダウンロードする必要があるため、最初の初期化には時間がかかる場合があります。 ダウンロードプロセスを追跡し、それをキャンセルする機能がある場合は、DotTrace.InitAsync()メソッドを直接使用します。CancellationTokenを使用し、コールバック変数を使用して進行状況を追跡できます。ユースケースの必要に応じて API 呼び出しを追加します。
スナップショットが必要な場合:
static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.Init(); // 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.Init(); // 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(); } }