dotTrace 2023.2 Help

Integrate Third-Party Tools with dotTrace

The JetBrains .NET tools (dotTrace, dotCover, and dotMemory) are based on the common profiler core. The core provides low-level profiling functionality like attaching to profiled processes, communication with the .NET Framework, .NET Core, or .NET runtime, collecting profiling data, and so on.

The profiler core provides a mechanism that lets third-party tools to integrate with JetBrains .NET tools. An example of such integration is Typemock Isolator running along with JetBrains dotTrace: Users can not only test their code but also investigate performance problems.

Transparent integration concepts

When a JetBrains .NET tool profiles a process, it loads the profiler core into the profiled process. In the case of transparent integration, profiling is initiated by a third-party tool. So, the third-party tool becomes responsible for loading the profiler core into the profiled process.

How to integrate your tool with dotTrace

  1. Before starting profiling, your tool must provide its integration configuration in at least one of following places:

    • On Linus and macOS:

      • The file $HOME/.jetbrains-profiler-transparent-integration-config

    • On Windows:

      • The registry HKCU\SOFTWARE\JetBrains\Profiler\TransparentIntegration

      • The registry HKLM\SOFTWARE\JetBrains\Profiler\TransparentIntegration

      • The registry HKLM\SOFTWARE\WOW6432Node\JetBrains\Profiler\TransparentIntegration

      • The file %USERPROFILE%\.jetbrains-profiler-transparent-integration-config

    The configuration file contains the list of key-value pairs. Only one key-value pair per line is allowed. The key and value must be separated with =. The parser disregards any text following the # symbol on a line. Empty lines are ignored.

    Key name

    Windows registry data type

    Description

    {name}

    REG_SZ

    (Required) A class ID of the third-party profiler COM object.

    {name}_Path32

    REG_SZ

    (Required on Windows ARM64/x64/x86) An absolute path to the x86 third-party profiler shared library.

    {name}_Path64

    REG_SZ

    (Required on Linux x64, macOS ARM64/x64, Windows ARM64/x64) An absolute path to the x64 third-party profiler shared library.

    {name}_PathArm32

    (Required on Linux ARM) An absolute path to the ARM third-party profiler shared library.

    {name}_PathArm64

    REG_SZ

    (Required on Linux ARM64, macOS ARM64, Windows ARM64) An absolute path to the ARM64 third-party profiler shared library.

    {name}_RegistryFreeActivation

    REG_DWORD

    (Optional, Windows only) 0 by default. Specify any number other than 0 if you are going to skip step 2, i.e., if you're not going to profile .NET Framework 2.0 - 4.5.2 processes.

    If your tool starts a process that it's going to profile, create corresponding registry values for each {name} below:

    • SamplingPerformanceProfiler

    • TracingPerformanceProfiler

    • TracingInjectPerformanceProfiler

    • TimelineProfiler

    If your tool attaches to a running process that it's going to profile, create corresponding registry values for each {name} below:

    • SamplingPerformanceProfiler_Attach

    • TimelineProfiler_Attach

  2. Register your tool as a COM object using the Win32 API or regsvr32 for x86 and x64 (ARM64 CPUs don't support .NET Framework 2.0 - 4.5.2).

  3. To load the JetBrains profiler core into the profiled process, use the following data:

    Variable

    Windows registry data type

    Description

    JETBRAINS_PROFILER_CORE_GUID

    REG_SZ

    (Required) The profiler core GUID.

    JETBRAINS_PROFILER_CORE_PATH32

    REG_SZ

    (Required on Windows ARM64/x64/x86) An absolute path to the x86 profiler core shared library.

    JETBRAINS_PROFILER_CORE_PATH64

    REG_SZ

    (Required on Linux x64, macOS ARM64/x64, Windows ARM64/x64) An absolute path to the x64 profiler core shared library.

    JETBRAINS_PROFILER_CORE_PATH_ARM32

    REG_SZ

    (Required on Linux ARM) An absolute path to the ARM profiler core shared library.

    JETBRAINS_PROFILER_CORE_PATH_ARM64

    REG_SZ

    (Required on Linux ARM64, macOS ARM64, Windows ARM64) An absolute path to the ARM64 profiler core shared library.

    You must take the values of these variables from the following sources (search the sources exactly in the specified order until the required value is found):

    1. On Linus and macOS:

      1. Files: /tmp/Upid_<pid>_<pst>/<var>

      2. Environment variables

    2. On Windows:

      1. Registry: HKCU\SOFTWARE\JetBrains\Profiler\Upid_<pid>_<pst>

      2. Registry: HKLM\SOFTWARE\JetBrains\Profiler\Upid_<pid>_<pst>

      3. Environment variables

      4. Registry: HKLM\SOFTWARE\JetBrains\Profiler\Global

    Where:

    • <var> – a Variable from the table above.

    • <pid> – an unsigned decimal process id.

    • <pst> – a hexadecimal process start time:

      • On Linux: in clock ticks from the system boot.

      • On Windows and macOS: in 100-nanosecond intervals since 01-Jan-1601 (UTC).

  4. Make sure your tool implements and keeps up to date the translation of the ICorProfilerInfo* interfaces. Note that the implementation of the ICorProfilerInfo::QueryInterface() in your tool must return the same set of available interfaces as the CLR/CoreCLR version it supports. For example, if CoreCLR supports only ICorProfilerInfo – ICorProfilerInfo4, then only these interfaces must be available to the JetBrains profiler core.

Last modified: 30 August 2023
Symbol Server Integration