procdump KB

procdump

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:

How to collect memory dumps
Procdump Overview And Download Link
The ProcDump tool is a free command line tool published by Sysinternals that allows both on-demand and conditional collection of memory dump files. It supports a variety of properties and conditions for generating memory dump files. 

It can be downloaded at the following location:
http://technet.microsoft.com/en-us/sysinternals/dd996900.aspx

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.

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]``
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]``
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]``
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]``
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.