Copyright: Copyright (C) 1999 Mark Russinovich


Introduction to DebugView
Copyright © 1999 Mark Russinovich

http://www.sysinternals.com

DebugView/EE (Enterprise Edition) is an application that lets you monitor debug output on your local system, or any computer on the network that you can reach via TCP/IP. It is capable of displaying both kernel-mode and Win32 debug output, so you don’t need a debugger to catch the debug output your applications or device drivers generate.

DebugView/EE works on NT 4.0, 5.0 (Windows 2000), Windows 95 and Windows 98. Note: if you want to run DebugView/EE on Windows 95 you must install the WinSock2 update, available for free download from Microsoft’s Web site.


Starting DebugView

Simply execute the DebugView/EE program file (dbgview.exe) and DebugView/EE will immediately start capturing debug output. Note that if you run DebugView/EE on Windows NT/2K dbgview.exe must be located on a non-network drive and you must have administrative privilege. Menus, hot-keys, or toolbar buttons can be used to clear the window, save the monitored data to a file, search output, and change the window font. In addition, you can toggle on and off capture of kernel or Win32 debug output.

As events are printed to the output, they are tagged with a sequence number. If DebugView/EE’s internal buffers are overflowed during extremely heavy activity, this will be reflected with gaps in the sequence number.

Each time you exit DebugView/EE it remembers the position of the window, the widths of the output columns, the font selection, configured filters, and the time-stamp mode.


Capturing Debug Output

Under Windows 9x DebugView/EE can capture output from the following sources:

•	Win32 OutputDebugString

•	Win16 OutputDebugString

•	Kernel-mode Out_Debug_String

•	Kernel-mode _Debug_Printf_Service

Under Windows NT and Win2k DebugView/EE can capture:

•	Win32 OutputDebugString

•	Kernel-mode DebugPrint

DebugView/EE buffers debug output until it sees a carriage-return (‘\n’) so that you can call a debug print service multiple times in order to build a complete output line.

Global Capture

You control DebugView/EE’s global capture mode by toggling capture-on and capture-off with the [image] toolbar button, the Capture|Capture Events menu entry, or the Ctrl+E hot-key sequence. DebugView/EE does not capture any data when its capture-mode is off. The state of Win32 capture and kernel capture determine what kind of debug output (if any) is captured when the global capture mode is on.

Capturing Win32 Debug Output

If you specify, DebugView/EE will register to receive and print debug output generated by Win32 programs that call OutputDebugString. The [image] toolbar button, the Capture|Capture Win32 menu item, and the Ctrl+W hot-key sequence can toggle this capture on and off. If the Win32 PID options is set (under Options|Win32 PIDs) then information identifying processes that generate Win32 debug output is prefixed to each line of Win32 debug output. If you are running DebugView/EE on Windows NT/2K, then the process ID of the processes are prefixed in brackets to each line of Win32 debug output. If the option is set and you are running on a Win9x system, then the process name is prefixed in brackets to the output.

Capturing Kernel-Mode Debug Output

You can configure DebugView/EE to capture kernel-mode debug output generated by device drivers and/or the Windows kernel by using the Capture|Capture Kernel menu selection, [image] toolbar button, or the Ctrl+K hot-key. Process IDs are not reported for kernel-mode output since such output is typically not process-context related.

Under Windows NT/2K, Win32 debug output and kernel-mode debug output originate with two different sources. Therefore, DebugView/EE captures the different outputs into two separate buffer pools, and merges the outputs in the display window according to their relative sequence numbers. While this means that the order of kernel-mode and Win32 output is correctly represented, the update of such information may not be sequential i.e. DebugView/EE may display a number of Win32 debug messages, and shortly after merge in kernel-mode debug messages that have interleaved sequence numbers. This is the reason that sequence numbers are represented as 8-digit numbers: the display’s listview auto-sorting feature is used by DebugView/EE to order merged kernel-mode/Win32 output.

Pass-Through Mode

DebugView/EE can be configured to pass kernel-mode debug output to a kernel-mode debugger or to swallow the output. The pass-through mode is toggled with the Capture|Pass-Through menu selection or [image] toolbar button. The pass-through mode allows you to see kernel-mode debug output in the output buffers of a conventional kernel-mode debugger while at the same time viewing it in DebugView/EE.


Searching, Filtering and Limiting Output

Searching, Filtering, and Limiting Output

DebugView/EE has several features that can help you zoom-in on the debug output you are interested in. These capabilities include searching, filtering, and limiting the number of debug output lines saved in the display.

Clearing the Display

To reset the output window, use the Edit|Clear Display menu item, [image] toolbar button, or Ctrl+X hot-key sequence. This also causes the sequence number to be reset to 0.

Searching

If you want to search for a line containing text of interest you use the find dialog. The find dialog is activated with the Ctrl+F hot-key sequence, the Edit|Find menu entry, or the [image] toolbar button. If the search you specify matches text in the output window, DebugView/EE will highlight the matching line and turn off the display’s auto-scroll in order to keep the line in the window. To repeat a successful search, use the F3 hot-key.

Filtering

Another way to isolate output that you are interested in is to use DebugView/EE’s filtering capability. Use the Edit|Filter/Highlight menu item, [image] toolbar button, or Ctrl-L hot-key to activate the filter dialog. The dialog contains two edit fields: include and exclude. The include field is where you enter substring expressions that match debug output lines that you want DebugView/EE to display, and the exclude field is where you enter text for debug output lines that you do not want DebugView/EE to display. You can enter multiple expressions, separating each with a semicolon (‘;’). Do not include spaces in the filter expression unless you want the spaces to be part of the filter. Note that the filters are interpreted in a case-insensitive manner, and that you should use ‘*’ as a wildcard.

As an example, say you want DebugView/EE to display debug output that contains either “error” or  “abort”, but want to exclude lines that contain either of those strings and the word “gui”. To configure DebugView/EE’s filters for this you enter “*error*;*abort*” for the include filter and “*gui*” for the exclude filter.

Highlighting

DebugView/EE also has another type of filtering: highlighting. If you want output lines that contain certain text to be highlighted in the DebugView/EE output window, enter a highlight filter. Use the same syntax just described for include and exclude filters. As soon as you enter a highlight filter all output lines that match the filter will be highlighted for easy recognition.

To change the colors used for the foreground and background of highlighted lines, choose the Edit|Filter/Highlight Colors menu item. You will be asked to pick colors from a palette, and your choices will be remembered by DebugView/EE from run to run.

History-Depth

A final way to control DebugView/EE output is to limit the number of lines that are retained in the display. You use the Edit|History-Depth menu item, [image] toolbar button, or the Ctrl+H hot-key sequence to activate the history-depth editor. Enter the number of output lines you want DebugView/EE to retain and it will keep only that number of the most recent debug output lines, discarding older ones. A history-depth of 0 represents no limit on output lines retained.

You do not need to use the history-depth feature to prevent all of a system’s virtual memory from being consumed in long-running captures. DebugView/EE monitors system memory usage and will go into a low-memory state when it detects that memory is running low. DebugView/EE’s low-memory state consists of it not capturing further debug output until the low-memory condition is no longer in effect.


Saving and Printing

Saving, Printing and Logging

DebugView/EE lets you both save and print captured debug output.

Saving Output

You can save the contents of the DebugView/EE output window as a text file (.log extension) using the File|Save or File|Save As menu items, or the Ctrl+S hot-key sequence.

Using Edit|Copy or the Ctrl+C hot-key sequence you can copy the debug output contained within selected output lines to the clipboard.

Logging to a File

To have DebugView/EE log output to a file as it displays it, use the File|Log to File or File |Log to File As menu items, the [image] toolbar button, or the Ctrl+O hot-key sequence. Log file settings you specify include the name of the log file, the maximum size it should be allowed to grow, and whether or not DebugView/EE should restart the log or append to it if the file specified already contains output.

When logging is active the log file toolbar button will look like [image]. To stop logging simply select the toolbar button or the File |Log to File menu item. A log file maximum size of 0 signifies no limit on the log file size. If the log file’s maximum size is reached logging to the file stops and the logging toolbar button changes to [image].

If you are monitoring debug output from multiple remote computers and enable logging to a file, all output is logged to the file you specify. Ranges of output from different computers are separated with a header that indicates the name of the computer from which the subsequent records were recorded.

Printing Output

You can use File|Print or File|Print Range to print the contents of the display to a printer. Choose Print Range if you only want to print a subset of the sequence numbers displayed, or Print if you want to print all the output records. The Ctrl+P hot-key sequence corresponds to File|Print.

Using the Print Range dialog you can also specify whether or not sequence numbers and timestamps will be printed along with the debug output. Omitting these fields can save page space if they are not necessary. The settings you choose are used in all subsequent print operations.

In order to prevent wrap-around when output lines are wider than a page, consider using landscape mode instead of portrait when printing.


Options

There are a number of options that let you adjust several characteristics of DebugView/EE, including the way that it behaves and looks.

Timing Format

DebugView/EE displays time stamps of captured debug output in one of two formats: as clock-time (the time of day), or as relative time. When displaying relative time DebugView/EE represents the time of a debug output record as the difference between its timestamp and the timestamp of the first record in the display. This mode is helpful when you debug timing-related problems. Use the Options|Clock Time menu item, [image] toolbar button, or Ctrl+T hot-key sequence to toggle between clock time and relative time modes.

Force Carriage Returns

The default behavior of DebugView/EE is to buffer output strings in an internal buffer DebugView/EE maintains until a carriage-return is encountered or the buffer overflows. This allows applications and drivers to build output lines with multiple invocations of debug output functions.

Select Options|Force Carriage Returns to cause DebugView/EE to display every string passed to a debug output function on a separate output line, regardless of whether the string is terminated with a carriage return.

Auto Scroll

Use the Options|Auto Scroll menu item, [image] toolbar button, or Ctrl+A hot-key sequence to toggle DebugView/EE between auto-scroll and non-auto scroll modes. When in auto-scroll mode DebugView/EE will always keep the most recent debug output visible in the display window.

Hiding the Toolbar

You can gain more display space by hiding the DebugView/EE toolbar. Use the Options|Hide Toolbar menu item or Ctrl+B hot-key sequence to toggle the toolbar’s presence. DebugView/EE will remember the toolbar state when you exit it and restore the same state the next time you start it.

Win32 PIDS

Setting this option using the Options|Win32 PIDs menu item will cause DebugView/EE to prefix Win32 debug output with either the process ID (Windows NT/2K) or the process name (Windows 9x) of the process that generated the output. Deselecting this option can save screen space if you are not interested in what process generates Win32 output.

Changing the Font

Use the Edit|Font menu entry to open a font-selection dialog where you can choose a font that DebugView/EE will use in its output window.

Always on Top

To keep DebugView/EE as the top-most window on the desktop, use the Options|Always On Top menu item. Selecting the menu item a second time will toggle off the always-on-top mode.


Crash Dumps

Crash Dumps (WinNT/2K Only)

Under Windows NT/2K you can configure the system to save a dump of physical memory when the operating system crashes. Using this crash dump facility DebugView/EE allows you to view any debug output your kernel-mode driver made up to the time of a crash. If your driver is sufficiently instrumented with debug output, then this feature permits users that experience a crash using your driver to send you a debug output file instead of an entire memory dump. You must be capturing kernel-mode debug output with DebugView/EE at the time of crash for this option to work.

Use the Edit|Process Crash menu item to select a crash dump file for DebugView/EE to analyze. DebugView/EE will process the file, looking for its debug output buffers. If it finds debug output in the crash dump DebugView/EE will prompt you for the name of the log file where it should save the output.


Remote Monitoring

Remote Monitoring Startup

DebugView/EE has advanced remote monitoring capabilities that allow you to view debug output generated on remote systems from a central location. The remote systems must be accessible via TCP/IP. DebugView/EE lets you monitor multiple remote systems simultaneously, using a hot-key or a menu selection to switch between them. If both the computer you are running the DebugView/EE GUI on (the server) and the system you want to monitor (the client) are running Windows NT/2K, and they are in the same Network Neighborhood, then DebugView/EE will automatically install its client software on the client. For all other combinations you must manually install and start DebugView/EE’s client software on the client.

Manual Client Startup

If either the server or the client is running Windows 9x, or the server and client are not mutually accessible via the Windows Network Neighborhood, then you must manually start the DebugView/EE client on the client computer. To do this, run the DebugView/EE program on the client and specify “/c” as a command-line argument:

dbgview /c

The DebugView/EE client window will appear and indicate that it is waiting for a connection from the DebugView/EE server.

After you have started the DebugView/EE client use the Computer|Connect menu item or Ctrl+R hot-key sequence of the DebugView/EE server to open a computer connection dialog. In the dialog enter the name or IP address of the client computer.  If the client computer is in the server’s Network Neighborhood you can also use the browse button in the dialog to open a view of the Network Neighborhood and visually select the client computer.

If you want to run the client in a “headless” mode, specify “/s” (silent) in addition to the “/c” command-line argument when you start the DebugView/EE client. This will cause the DebugView/EE client to not display a window, and to remain active until the current user logs out, silently connecting with and disconnecting from DebugView/EE servers.

Use the “/e” option when starting the client if you want it to notify you when server connections break. When a server connection is broken and this switch is specified you must close the notification window before the client will accept further connections.

If you specify “/?” DebugView/EE will tell you its supported command-line options.

Automatic Client Startup

Automatic startup is not supported on the Alpha.

If both the client and server are running Windows NT/2K and are in the same Network Neighborhood, there is no need for you to install the DebugView/EE client on the client computer. Instead, specify the client computer name or address in the connection dialog as you would if you were connecting to a manually started DebugView/EE client, and DebugView/EE will automatically install and start the DebugView/EE client on the client computer. When you disconnect from the client DebugView/EE uninstalls its client software for you. In case you want to clean up client files yourself after a non-graceful exit of the server, the files DebugView/EE installs on the client are placed in <winnt>\system32 and include dbgvsvc.exe and dbgv.sys.

The DebugView/EE server will always attempt an automatic install, and if that fails it falls back on trying to connect to a manually installed client.


Managing Connection Views

When a remote capture session is established DebugView/EE creates a new computer view for the session. The active computer view is the one that has captured output displayed in the DebugView/EE GUI, and is identified on the DebugView/EE title bar. To switch from one computer view to another select the desired view, which is listed by computer name, in the Computer menu. Alternatively, you can use Ctrl+Tab to cycle through the computer views.

The state of global capture, Win32 debug capture, kernel capture, and pass-through for a newly established remote session are all adopted from the current settings of the local view (the view of the computer on which the DebugView/EE is executing). Changes you make to these settings only apply to the active computer view.

Disconnecting a Remote Session

When you are through capturing debug output from a remote system, make the view for the computer from which you want to disconnect the active view and then use the Computer|Disconnect menu entry to close the session.

When you exit DebugView/EE it saves the state of the local view, including the width of the display columns, and DebugView/EE applies those settings the next time you start it.


Multiple Windows

Managing Multiple Windows

DebugView/EE allows you to open multiple DebugView/EE windows on the same computer, allowing you to capture debug output from different computers into different windows. This is an alternative to connecting to multiple computers from the same DebugView/EE window, and is desirable when you wish to simultaneously view different output sources.

By default, when you start the first DebugView/EE window on a computer it connects with the local computer. This means that it captures and displays any debug output generated on the computer.  You can open a second instance of DebugView/EE either by starting it again, or by selecting the File|New Window menu entry.

You can use the Computer|Connect Local menu entry to connect DebugView/EE to the local computer, and choose the Computer|Disconnect menu entry to disconnect from the local computer when it is selected as the active computer view within a DebugView/EE window. Note that only one DebugView/EE instance can be connected to any computer at a given time.

If you start a new DebugView/EE window by executing the program again the configuration settings DebugView/EE uses reflect those of the last DebugView/EE window that was closed. If you start a new DebugView/EE window using the File|New Window menu entry, the configuration settings are adopted from the window in which you select the menu item.


Reporting Problems

If you encounter a problem while running DebugView/EE, please visit the Systems Internals web site (http://www.sysinternals.com) to see if an update has been released that might correct the bug. If the problem has not been fixed, please submit a thorough report of the problem, including information on your system configuration and details on how to reproduce the problem, to:

mark@sysinternals.com