dotMemory 2017.2 Help

Using dotMemory Command-Line Profiler

Sometimes it is necessary to automate the process of gathering memory snapshots. For example, if you want to make profiling a part of your continuous integration builds (e.g., this can be a build step that performs profiling of your integration tests) or when you simply want to speed up profiling routines (e.g., when you regularly profile the same application and do not want to start the dotMemory user interface each time). For this purpose, dotMemory offers the dotMemory.exe command-line tool.

The dotMemory.exe tool can be used to profile any .NET application (including an already running one) and take memory snapshots.

Note that the tool is distributed free of charge and does not require dotMemory to be installed. You can freely upload it to any computer to take memory snapshots of problematic applications.

There are four main dotMemory.exe commands:

  • get-snapshot - instantly get snapshot of a running app.
  • attach - attach the profiler to a running app and get snapshots by condition, using the API, or by sending commands to stdin.
  • start - start an app and get snapshots by condition, using the API, or by sending commands to stdin.
  • start-iis - start IIS and get snapshots by condition, using the API, or by sending commands to stdin.
For detailed information on a particular dotMemory.exe command, run:
dotMemory.exe help <command>

This section covers only most basic tool usage scenarios:

Getting Snapshot of a Running Application

It is the most simple and demanded scenario. There are two ways of identifying the application you want to take snapshot from: via its PID or via its name.

To instantly get a snapshot of a running application by its PID (e.g., 6844):

  • Run the command:
    dotMemory.exe get-snapshot 6844 --save-to-dir=C:\Snapshots

Here:

  • --save-to-dir=C:\Snapshots - (optional) path to directory for saving a snapshot (more correctly, a workspace (.dmw file)). In this case, snapshot filename will be generated automatically. If you want to specify the filename by yourself, use the --save-to-file option.
  • 6844 - process PID (you can find it in Window Task Manager).

To instantly get a snapshot of a running application by its name:

  • Run the command:
    dotMemory.exe get-snapshot MyApp --with-max-mem
    or
    dotMemory.exe get-snapshot MyApp --all

Here:

  • MyApp - process name (you can find it in Windows Task Manager). If there are more than one process with such name, you can remove the ambiguity either with the --with-max-mem or --all option.
  • --with-max-mem - a process that consumes most of the memory will be profiled.
  • --all - all processes with the specified name will be profiled. dotMemory will take snapshots of all process (snapshot per process).

Starting Application and Getting Snapshots by Condition

Sometimes it may be necessary to track application memory consumption during a long time interval. In this case, you can start your application under profiling and get snapshots only in case a particular condition is satisfied: a periodic time interval ends or memory consumption increases by a specified value.

To start MyApp.exe and take snapshots periodically:

  • Run the command:
    dotMemory.exe start --trigger-timer=30s C:\MyApp\MyApp.exe MyAppArg1

Here:

  • --trigger-timer=30s - time period for taking snapshots (30 s in our case).
  • C:\MyApp\MyApp.exe - path to the executable file of the profiled app.
  • MyAppArg1 - (optional) argument of MyApp.exe. Note that if application argument starts with the dash (-) character, you can escape it using double dash (--). For example,
    dotMemory.exe start --trigger-timer=30s C:\MyApp\MyApp.exe -- -MyAppArg1

To start MyApp.exe and take snapshots when memory consumption increases by the specified value:

  • Run the command:
    dotMemory.exe start --trigger-mem-inc=50% --trigger-delay=5s C:\MyApp\MyApp.exe

Here:

  • --trigger-mem-inc=50% - a snapshot will be taken only when memory consumption of MyApp increases by 50%.
  • --trigger-delay=5s - a trigger will be enabled with the 5 s pause to skip the application startup phase.

Starting Application and Getting Snapshots Using stdin Messages

Sometimes it's necessary to have direct control over the profiling process, e.g., get a snapshot at some exact moment by a direct command. This can be done by sending special messages to stdin of dotMemory.exe.

To start MyApp.exe and control profiling using stdin messages:

  1. No additional arguments are required. You can start profiling as usual using start, start-iis, or attach commands. For example:
    dotMemory.exe start c:\MyApp\MyApp.exe

    dotMemory is able to inform you about how the profiling process is going by sending special service messages to stdout. This might be especially helpful in case you control profiling by some external script. To enable the support for stdout messages, run dotMemory with the --service-output option, e.g.:

    dotMemory.exe start --service-output c:\MyApp\MyApp.exe
    dotMemory sends the following messages to stdout:
    • Start of the profiling session
      ##dotMemory["connected", {pid: 1234}]
    • Saving the snapshot
      ##dotMemory["workspace-saved", {path: "..."}]

  2. Get a snapshot by sending the following command to stdin:
    ##dotMemory["get-snapshot", {pid:1234}]
    If pid is specified, dotMemory will take a snapshot of the process with the specified PID. Otherwise, dotMemory will take snapshots of all profiled processes.
  3. To stop profiling and kill the profiled application, send the following command to stdin:
    ##dotMemory["disconnect"]
    Works for all profiling sessions started with start, start-iis, or attach commands.

Starting Application and Getting Snapshots Using API

You also have the option to control profiling (get snapshots, detach from process, and so on) using the API.

To start MyApp.exe and control profiling with API:

  • Run the command:
    dotMemory.exe start --use-api C:\MyApp\MyApp.exe

Attaching to and Profiling Running Applications

If you want to profile an already running application and have full control over the profiling process (unlike the get-snapshot scenario), you should use the attach command. It allows the profiler to attach to running processes (by PID or name as well as get-snapshot) and get snapshots using triggers, stdin commands, or the API. For instance, here is the example of how to profile a running app MyApp.exe and get snapshots using a trigger.

To attach to a running app and get snapshots periodically:

  • Run the command:
    dotMemory attach MyApp.exe --trigger-timer=30s

Running and Profiling IIS-hosted Web Applications

If you want to profile an ASP.NET web application that runs on IIS server, you should use the start-iis command. After you run the command, IIS will be started under profiling (for more details on how IIS-hosted apps are profiled, refer toWeb Application Using IIS). Note that start-iis supports the same ways of controlling profiling as the start command: using triggers, stdin commands, and the API. For instance, here is the example of how to profile a web app and get snapshots using a trigger.

To run IIS under profiling and get snapshots periodically:

  • Run the command:
    dotMemory.exe start-iis --trigger-timer=30s --open-url=localhost/myapp --use-browser=Chrome

Here:

  • --open-url=localhost/myapp - URL of the profiled application that will be opened after you run profiling.
  • --use-browser=Chrome - browser that should be used to open the URL. If not provided, the default system browser will be used.

Last modified: 29 August 2017