ADPlus Overview
ADPlus automates the CDB debugger to produce memory dumps and log files that contain debug output from one or more processes.
Every time that you run ADPlus, debugging information (such as memory dumps and text files that contain debug information) is put in a new, uniquely named folder (such as C:\Temp\Crash_Mode__Date_01-22-2001__Time_09-41-08AM) on the local file system or a remote network share. In addition, each file that ADPlus creates is also given a unique name (such as PID-1708__Inetinfo.exe__Date_01-22-2001__Time_09-41-08AM.log) to avoid overwriting older files with newer ones.
ADPlus works with any user-mode process or service such as Internet Information Services (IIS), Microsoft Transaction Server (MTS), or Microsoft COM+ applications.
ADPlus has the following features:
- ADPlus uses the latest Microsoft debuggers for speed and reliability.
- ADPlus dumps memory asynchronously for multiple processes so that each process is frozen and dumped at the same time. This process provides an effective "snapshot" of the whole application at the time ADPlus was run. It is important to capture all of the processes that make up a given application and all of the processes that a given application uses at the same time so that you can capture the state of the application at the time that the problem occurs. This snapshot is especially important for applications that make remote procedure calls to other processes.
- ADPlus has a command-line interface. Because ADPlus does not have a graphical user interface (GUI), you can run it with the -quiet option in a remote command shell (a Command Prompt window that is controlled through Remote.exe). The -quiet option suppresses all dialog boxes and logs all output to the event log. For more information about how to run ADPlus from a remote command shell, see Running in Crash Mode Remotely.
- When ADPlus monitors for crashes, it can notify you or a computer of a crash through the Microsoft Windows Messenger service. This feature is activated though the -notify command-line option.
- When ADPlus monitors a process in crash mode and a failure (that is, crash) occurs, ADPlus sends important information about the type of failure to the event log.
- ADPlus supports XCOPY deployment. That is, if you copy the Debugging Tools for Windows installation folder to a new location, ADPlus still works correctly. In addition, ADPlus does not require that you register any custom Component Object Model (COM) components on the system. Therefore, this tool is ideal for use on production servers that have a locked-down software configuration. To remove ADPlus, you have to only delete the folder that it was installed or copied to.
When ADPlus Can Be Used
ADPlus can create a detailed dump file in a variety of scenarios. This file contains debugging information that you must have to isolate the cause of problems that occur in complex environments.
When Should You Use ADPlus?
You should use ADPlus to capture debugging information if you are experiencing the following problems:
- Processes that stop responding (that is, hang).
- Processes that have 100 % CPU utilization on a single processor computer, 50 % utilization on a dual processor computer, 25 % utilization on a quad processor computer, and so on.
- Processes that fail (that is, crash) or shut down unexpectedly.
When Should You Not Use ADPlus?
You should not use ADPlus in the following situations:
- If you have to troubleshoot an application or process that ends unexpectedly during startup.
You can use ADPlus only together with processes that start successfully. If you have to troubleshoot processes that end unexpectedly during startup, you should use CDB, WinDbg, or UserDump instead.
- If there is a noticeable performance effect when you use ADPlus in crash mode.
This performance effect is typically caused by dynamic-link libraries (DLLs) or applications that throw many Microsoft Visual C++ EH exceptions (which occur when you use the C++ throw statement or when you use try/catch blocks). Applications that write lots of information to the debug output stream can also cause a decrease in performance. Frequently, ADPlus does not affect performance noticeably when it is running in crash mode.
Crash Mode
In crash mode, ADPlus attaches the CDB debugger to all processes that are specified at the command prompt and automatically configures the debugger to monitor for the following kinds of exceptions:
- Invalid handle
- Illegal instruction
- Integer divide-by-zero
- Floating-point divide-by-zero
- Integer overflow
- Invalid lock sequence
- Access violation
- Stack overflow
- C++ EH exception
- Unknown exception
You can use ADPlus in crash mode instead of UserDump when you are troubleshooting these kinds of exceptions.
Because crash mode uses an "invasive" attach through the CDB debugger, you cannot use this mode in a Microsoft Windows NT 4.0 or Windows 2000 Terminal Server session, because these operating systems do not permit a debugger in one window station to attach to a process in a different window station. Crash mode is supported in a Terminal Server session on Windows XP and later versions of Windows. Hang mode does work inside a Terminal Server session on any platform.
Note For a workaround in Windows NT or Windows 2000 Terminal Server by using remote.exe, see Running in Crash Mode Remotely. For more information about invasive and non-invasive attaching, see Starting the Debugger.
When ADPlus is running in crash mode, a debugger remains attached to each process that is specified at the command prompt for the lifetime of that process until a fatal exception is trapped and the process fails (that is, crashes), or until a user presses CTRL+C to detach the debugger from that process. To manually detach the debugger from the process, you must maximize the debugger window and press CTRL+C to break into the debugger. When you press CTRL+C, ADPlus traps the command, begins to list the stacks for all threads to a log file, and then produces a minidump file of the process before it detaches from the debugger. Because crash mode performs an invasive attach, the process is ended when the debugger is detached, and you have to restart it. If the process is a Microsoft Transaction Server (MTS) or COM+ process, the process is restarted automatically the next time that a call is made to a component in that package.
First-Chance Exceptions
Each kind of exception (access violation, stack overflow, and so on) can be raised to a debugger as a "first chance" or "second chance" exception. First-chance exceptions are not fatal unless they are not handled properly by an error handler. If a first-change exception is not handled properly by an error handler, they are raised again as a second-chance exception (which only a debugger can handle). If a debugger does not handle a second-chance exception, the application is shut down.
By default, when ADPlus detects a first-chance (nonfatal) exception for all kinds of exceptions (except unknown and EH exceptions), ADPlus does the following:
- Pauses the process to log the date and time that the exception occurred in the log file for the process that is being monitored.
- Logs the thread ID and call stack for the thread that raised the exception in the log file for the process that is being monitored.
- Produces a uniquely-named minidump file of the process at the time that the exception occurred and then resumes the process. (This step is equivalent to .dump -u /m.)
By default, ADPlus does not produce a unique minidump file for first-chance EH and unknown exceptions because processes frequently encounter many of these exceptions. These kinds of exceptions are typically handled by error handling code in a process or DLL. In other words, these exceptions are typically handled exceptions, and they do not become second-chance (unhandled) exceptions, which end the process.
However, you can configure ADPlus to produce unique minidump files for first-chance EH and unknown exceptions. For more information about how to configure ADPlus, see ADPlus Command-Line Options and ADPlus Configuration Files.
Second-Chance Exceptions
When ADPlus detects a second-chance (fatal) exception for all kinds of exceptions (including EH and unknown exceptions), ADPlus does the following:
- Pauses the process.
- Logs the date and time that the exception occurred.
- Logs the thread ID and the call stack for the thread that raised the exception.
- Produces a full memory dump of the process at the time that the fatal exception occurred.
- Exits the debugger. This step ends the process.
ADPlus keeps a separate log file for each process that it monitors.