API Reference

GetFeatures()

enum MeasureFeatures: uint

Returns a set of features currently active in the profiler: Bit flags in the MeasureFeatures value fully describe the current profiler state. Each bit indicates whether a corresponding feature is currently available:

• Ready = 0x1: Indicates whether the profiler is ready to work. You need to check this flag only in case you attach the profiler to the current process: the flag will be set once the profiler is ready to accept your commands. If you start a process under profiling, this flag is always set. After you detach the profiler from the process, the flag is cleared.

• Detach = 0x2: Indicates whether it is possible to use MeasureProfiler.Detach().

  
  

  0: the profiler will ignore MeasureProfiler.Detach().

  
  

  1: MeasureProfiler.Detach() will detach the profiler from the profiled process.

StartCollectingData()

Start collecting profiling data.

Doesn't throw any errors even if the application is run with profiling disabled.

StartCollectingData(string groupName)

[Internal use only]

Start collecting profiling data.

Doesn't throw any errors even if the application is run with profiling disabled.

groupName is the name of the collected data block.

StopCollectingData()

Stop collecting profiling data. Current data will persist in memory so next time you start taking measurements with StartCollectingData(), the new data will be added to the current data.

This method doesn't save the collected data block to the disk.

Doesn't throw any errors even if the application is run with profiling disabled.

Important! This method is not applicable to the Timeline profiling type and will be ignored by the profiler.

SaveData()

Stop collecting data if needed and save all collected data blocks to the disk.

After saving a snapshot, the collected data is reset.

Doesn't throw any errors even if the application is run with profiling disabled.

SaveData(string name)

[Internal use only]

Stop collecting data if needed and save all collected data blocks to the disk.

After saving a snapshot, the collected data is reset.

Doesn't throw any errors even if the application is run with profiling disabled.

name is the name of the collected data blocks. It is not a filename.

Detach()

Detach the profiler from the profiled process. Does nothing if detaching is disabled in the profiler. To check whether the detaching is enabled, use MeasureProfiler.GetFeatures() with MeasureFeatures.Detach flag. Doesn't throw any errors even if the application is run with profiling disabled.

DropData()

Stop collecting data if needed and drop all collected data blocks.

Doesn't throw any errors even if the application is run with profiling disabled.

EnsurePrerequisite(Uri nugetUrl = null, NuGetApi nugetApi = NuGetApi.V3, string downloadTo = null)

Initializes the profiler. This method is a simplified way to call the EnsurePrerequisiteAsync() method. This is the recommended method for profiler initialization.

EnsurePrerequisiteAsync( CancellationToken cancellationToken, IProgress<double> progress = null, Uri nugetUrl = null, NuGetApi nugetApi = NuGetApi.V3, string downloadTo = null)

Task

(We recommend that you use EnsurePrerequisite() instead)

Initializes the profiler. During the initialization, the API checks whether the command-line profiler exists in the same folder with the executing assembly. If the profiler is not found, downloads the compatible the JetBrains.dotTrace.CommandLineTools NuGet package (Windows, Linux, macOS) into the downloadTo folder. The compatible package version is set by the NupkgVersion constant. You can track the download progress using the progress callback variable and cancel the downloading using cancellationToken.

Attach()

Attaches the profiler to the current process using the default profiling configuration.

Attach(DotTrace.Config config)

Attaches the profiler to the current process using the specified profiling config.

StartCollectingData()

Starts collecting performance data. The profiler changes its state from "Stopped" to "Started". If the profiler is already in "Started" state, the command is ignored.

SaveData()

Takes a performance snapshot of the current process. All collected data is saved to files specified in the configuration. Note that after saving the data, profiler goes to the "Stopped" state. To start collecting data again, call StartCollectingData().

DropData()

Run this method to discard the collected data. Note that after discarding the data, the profiler goes to the "Stopped" state. To start collecting data again, call StartCollectingData().

StopCollectingData()

Stops collecting performance data. The profiler changes its state from "Started" to "Stopped". If the profiler is already in the "Stopped" state, the command is ignored. It is not necessary to call this method before taking a snapshot. Note: The command is supported only if the profiler API is used to control session. Otherwise, the command is ignored.

GetCollectedSnapshotIndexFiles()

String[]

Returns paths to collected snapshot index files. For each collected snapshot, a separate index file is returned. Note: To share a snapshot, you must copy not only the index file but all files. In such cases, it's more convenient to use GetCollectedSnapshotFilesArchive().

GetCollectedSnapshotFiles()

String[]

Returns paths to all collected snapshot files. For each collected snapshot, more than one file is returned.

GetCollectedSnapshotFilesArchive(bool deleteUnpackedFiles)

String

Returns path to a zip file containing all collected snapshot files (including index files). Returns null if data is not yet collected. deleteUnpackedFiles specifies whether the unpacked snapshot files must be deleted.

Detach()

Detaches the profiler from the current process. Call it after you finish profiling.

SaveToFile(string snapshotFile, bool overwrite = false)

DotTrace.Config

Specifies the path to the snapshot index file. If you take more than one snapshot, the first snapshot will get the specified filename. Others will additionally get the suffix -[snapshot-number]. The directory specified in the path must already exist.

SaveToDir(string dirPath)

DotTrace.Config

Specifies the path to the directory where snapshot files must be saved (names will be auto-generated). The directory must already exist. SaveToDir and SaveToFile are mutually exclusive.