How to collect memory dumps using ProcDump

  • Introduction

    Process memory dumps are very efficient sources of information that are used for troubleshooting websites, which is the reason they are frequently requested by Sitecore Support.

    Various tools exist that allow collecting the memory dumps of a specific process, both based on user request (on-demand), as well as based on a specific event (conditional).

    This article describes the way to gather memory dumps using the ProcDump application.

    For other methods of gathering memory dumps, refer to the following article:

  • Gathering memory dump files - on-demand

    To gather a memory dump file at a custom point in time, run the ProcDump tool without condition-related parameters.

    procdump -ma [Name or PID]

    ProcDump requires a process name or process ID to be passed instead of "[Name or PID]" argument to identify the target process.

    Use the process name (such as w3wp.exe for IIS 6 or later) when there is only one process with this name.

    Specify the process ID when there is more than one process with the w3wp.exe name. For information on how to get the Process ID of a particular Sitecore instance, refer to this article: How to identify process ID of appropriate Sitecore instance.

    Important: Always remember to specify the "-ma" argument. It instructs the tool to collect the Full memory dump file. If not specified, the memory dump file collected may contain limited amount of useful diagnostics information.

  • gathering memory dump files  - conditional

    When the manual memory dump collection is not appropriate, the ProcDump tool provides the ability to specify different conditions for when to automatically collect a memory dump. The following conditions are supported:

    • Exception based rules
    • CPU usage based rules
    • Memory usage based rules
    • Performance counters based rules

    This section covers some basic scenarios of the tool usage.

    1. Collect a memory dump file based on a first chance exception

      To collect a memory dump file on any first chance exception, use the "-e 1" argument. To gather more than one memory dump file, use the "-n [num]" argument.

      Example. Gather a memory dump file when the process encounters any first chance exception:

      procdump -e 1 -ma [Name or PID]

      Example. Gather 3 memory dump files on any raised first chance exceptions:

      procdump -n 3 -e 1 -ma [Name or PID]
    2. Collect a memory dump file based on a specific first chance exception

      The ProcDump tool allows to set the exception type filter to allow collecting memory dumps only for specific exception types. This is useful for troubleshooting the reasons of a specific exception being raised. The "-f [ExceptionType]" 

      Example. Gather a memory dump file when the "System.NullReferenceException" exception is thrown:

      procdump -e 1 -f "System.NullReferenceException" -ma [Name or PID]
    3. Collect a memory dump file based on high CPU usage

      The "-c [%value]" argument specifies the CPU usage threshold after which a memory dump file should be collected.

      The "-c" argument is usually combined with the following ones:

      "-s [secs]" – specifies how long the CPU usage should remain at a specified level for a memory dump file to be collected. The default value is 10 seconds.

      "-u" – specifies the CPU usage of any particular processor core to be tracked, comparing the average CPU usage of all the cores.

      Example. Gather a memory dump file if the process uses more than 60% of total CPU resources for 5 seconds:

      procdump -c 60 -s 5 -ma [Name or PID]

      Example. Gather a memory dump file if the process uses more than 80% of a single CPU core for 15 seconds:

      procdump -c 80 -u -s 15 -ma [Name or PID]
    4. Collect a memory dump file based on high memory usage

      The "-m [MBs]" argument can be used to specify memory usage threshold after which a memory dump file should be collected.

      Example. Collect a memory dump file if the process memory usage is larger than 500 MB.

      procdump -m 500 -ma [Name or PID]
    5. Collect a memory dump file based on performance counter values

      The "-p \Process(Name_PID)\[counterName] [threshold]" argument can be used to specify a threshold for the value of a specific Windows Performance Counter that triggers memory dump file collection.

      Example. Collect a memory dump file when the Thread Count performance counter reaches or exceeds 85 threads. The process name is w3wp, the process ID is 66666:

      procdump -p "\Process(w3wp_66666)\Thread Count" 85 -ma 66666
      Note: While the documentation does not require the process ID value to be specified if only one process with this name exists, it is recommended to always specify the process ID. The reason is that the ProcDump tool uses the specified name and Process ID to identify the process for which performance counters should be monitored. If you specify the process name only and two processes with the same name exist, it may happen that ProcDump will use performance counters of a different process to trigger memory dump file collection.

Applies to:

CMS 6+

September 10, 2014
October 29, 2015

Keywords: 

  • Performance