dotTrace Help

Controlling Profiling Session Through API

dotTrace API is a part of profiling SDK. The API provides a number of classes which allow you to control the profiling process. For example, you can start and stop collecting profiling data, save collected snapshots and so on right from your app.

For examples on how to use API, refer to API Usage Examples. For detailed information about API classes, refer to API Reference.

For more details on dotTrace Profiling SDK implementation and usage scenarios, check this tutorial.

When To Use the API

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

  • Profiling a specific part of the code
    API allows you to narrow the profiling scope and profile only methods you are interested in.
  • Self-profiled applications
    API allows you to collect statistics about how your app behaves on end-user desktops.

How the API Works

Timeline and performance profiling methods have slightly different API implementations.

Performance Profiling

The following list summarizes main concepts of using API for performance profiling:

  • The static PerformanceProfiler class located in the JetBrains.Profiler.Windows.Api.dll library provides methods for starting, stopping and cancelling profiling.
  • The PerformanceProfiler API is organized as a simple state machine.
  • The IsActive property is used to determine whether the API is enabled.
  • Profiling must be started from creating a blank snapshot using the Begin method.
  • Profiling is not started initially, therefore Start should be called to begin profiling measurements.
  • Stop stops taking measurements.
  • EndSave stops taking measurements and opens the snapshot in the viewer.
  • To enable the API, you should select the Use profiler API checkbox in the advanced Profiler Options.

The API state machine:

pp_api_state_machine

Timeline Profiling

The following list summarizes main concepts of using API for timeline profiling:

  • The static TimelineProfiler class located in the JetBrains.Profiler.Windows.Api.dll library provides methods for starting, stopping and cancelling profiling.
  • The IsActive property is used to determine whether the API is enabled.
  • Profiling must be started from creating a blank snapshot using the Begin method. This also starts measurements.
  • EndSave stops taking measurements and opens the snapshot in the viewer.
  • To enable the API, you should select the Use profiler API checkbox in the advanced Profiler Options.

Self-Profiling

The following list summarizes "self-profiling" concepts:

  • End-users do not have dotTrace installed; therefore, you must include dotTrace redistributables into your app's installation package.
  • As end-users are not supposed to initiate profiling, the self-profiling session is initiated by the API. For this purpose, the API uses the static SelfAttach class located in the JetBrains.Profiler.Windows.SelfApi.dll library.
  • The Attach method prepares profiling configuration and executes the profiler from the "redistributables" folder.
  • The profiling configuration is defined by one of two classes (instantiated from the BaseSnapshotProfilingConfig BaseProfilingConfig classes) passed to the Attach method:
    • SaveSnapshotProfilingConfig - the resulting snapshot is saved in the designated folder.
    • ExecutableSnapshotProfilingConfig - the resulting snapshot is saved in the designated or default folder, the path to the snapshot is passed to an external application as a command line parameter.
  • For performance profiling, there is a limitation on the profiling type - it can be only Sampling.

See Also

Reference:

Last modified: 26 June 2015