dotTrace 2020.2 ヘルプ

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

The profiling API(英語) provides a number of classes which allow you to control the profiling process. For example, right from the code of your application, you can:

  • start collecting profiling data: MeasureProfiler.StartCollectingData(),

  • stop collecting the data: MeasureProfiler.StopCollectingData(),

  • save the data to the disk: MeasureProfiler.SaveData(),

  • and more.

For the detailed information about the API classes, refer to API Reference.

There are two main scenarios that require using the profiling API:

Profiling a specific part of the code

The API allows you to narrow the analysis scope and profile only the code you are interested in. For example, sometimes, it is not that easy to click the Get Snapshot button at the right moment. With the profiling API, you can do a "get a snapshot" call at an exact point of your code.

Note that dotTrace 2018.3 and earlier used another version of the profiling API (for the details on this API, refer to the dotTrace 2018.3 documentation). This API is still supported but we strongly recommend that you use the latest API version described in this section.

Main concepts:

  • The source code of the API is available on GitHub(英語). The code is distributed under Apache license.

  • The profiling API is distributed as a JetBrains.Profiler.API(英語) NuGet package which you should reference in your project.

  • To enable the API, you must start a profiling session with the enabled Use profiler API option. It is located in the advanced Profiler Options.

  • When using the API, the only difference comparing to a normal profiling session is in how you control the session: instead of clicking the buttons in the profiling controller, you call the corresponding API methods.

  • If you run your application with profiling disabled, the calls to the API methods will be simply ignored. The API will not throw any errors.

  • The main class you should use to control a profiling session is the MeasureProfiler static class.

  • To start collecting profiling data, call MeasureProfiler.StartCollectingData(). This is equivalent to pressing the Start button in the profiling controller.

  • To stop collecting the data and save them to the disk, call MeasureProfiler.SaveData() – an equivalent to pressing the Get Snapshot and Wait button.

  • To drop the data without saving, call MeasureProfiler.DropData() – an equivalent to pressing the Drop button.

  • To stop collecting profiling data without saving them to the disk, call MeasureProfiler.StopCollectingData(). Typically, you do not need to use this method. Note that this method is not applicable to the Timeline profiling type and will be ignored by the profiler.

  • Timeline profiling requires the ETW service to be run in the background. To start this service, administrator rights are required. For this reason, each time you start a profiling session, dotTrace prompts you for rights elevation. To avoid this, run the service manually using the <dotTrace_installation_directory>\x64\JetBrains.ETW.Collector.Host.exe file. Another option is to install the service using the <dotTrace_installation_directory>\Msi.x64\EtwService.msi installation file. In this case, the service will be run on Windows startup.

To use the API for profiling a specific part of the code

  1. Reference the JetBrains.Profiler.API NuGet package in your project.

  2. Insert calls to methods of the MeasureProfiler class into your code as required by your use case. For example:

    private void SomeMethod() { MeasureProfiler.StartCollectingData(); ... // Here goes some code that I want to profile MeasureProfiler.SaveData(); }

  3. Start profiling the application from within dotTrace, JetBrains Rider, or Visual Studio, and select the Use profiler API checkbox in the profiler options. *

Self-profiled applications

As the name suggests, in this scenario, an application profiles itself. The main difference comparing to the previous scenario is in how you initiate profiling. If you profile a specific part of the code using the profiling API, you initiate a session manually (for example, using the dotMemory UI). In case of a self-profiled application, the session is initiated right from the application code.

For example, ReSharper uses this API to collect statistics about how it behaves on end-user desktops. When a user faces a performance or memory issue, the support team asks the user to run ReSharper with a special option (it enables the self-profiling feature) and reproduce the issue. The collected snapshot is then sent to the development team.

Main concepts:

  • The self-profiling API is a separate JetBrains.Profiler.SelfApi(英語) NuGet package that you should reference in your project.

  • To control the profiling session, the API uses the dotTrace command-line tool.

  • The command-line tool is not a part of the package. When you initialize the API using the DotTrace.EnsurePrerequisite() メソッドの場合、API は JetBrains.dotTrace.CommandLineTools NuGet パッケージの最新バージョン(Windows(英語)Linux(英語)macOS(英語))をダウンロードします。

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

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

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

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

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

  • パフォーマンスのスナップショットを取得するには、 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(); } }

最終更新日 : 2020 年 8 月 06 日

関連ページ:

API 参照

プロファイリングAPI:MeasureProfilerクラスのメソッドプロファイラで現在アクティブな機能のセットを返します。値のビットフラグは、現在のプロファイラの状態を完全に記述しています。各ビットは、対応する機能が現在利用可能かどうかを示します。: プロファイラーが動作する準備ができているかどう...

APIによるセッションの制御

*ドメインポリシーが、インターネットからダウンロードしたファイルを安全でないものとして扱う場合は、ファイルプロパティのブロック解除ボタンを使用してzipアーカイブのブロックを解除します。dotTrace APIはSDKのプロファイリング*の一部です。APIはプロファイリングプロセスを制御することを可...

プロファイリングセッションの制御

プロファイリング設定を構成してセッションを実行すると、dotTraceコントローラーウィンドウが開きます*。* dotTraceコマンドラインプロファイラーでは使用できません。プロファイリングセッションを手動で制御するには、dotTraceコントローラーウィンドウのボタンを使用します。開始: パフォ...

プロファイルユニットテスト

*プロファイリングを制御するためにAPIを使用する場合、単体テストのプロファイルを作成する唯一の可能な方法はスタンドアロン dotTrace を使用することです。ユニットテストのプロファイリングには 3 つの方法があります。Visual Studio に統合された dotTrace の使用。これが最...