Alter.Org.UA  
 << Back Home RU ru   Donate Donate www/www1/www2

DbgPrint logger
for
NT3.51/NT4/NT4-TS/w2k/XP/2k3/2k3-r2/Vista and WinPE/BartPE/MobileOS

DbgPrint logger home

DbgDumpLog manual

Overview

DbpPrint() (also known as KdPrint() macro) and OutputDebugString() to file logging utility. Supports log rotation. Maximum log-file size is limited to 128Mb. When file size limit is reached, utility automatically creates new file. For example, if logging was started from dbgprint.log file, next files will be named dbgprint1.log, dbgprint2.log, etc. Supports keyboard control. You can pause/resume logging or force switching to next log-file. In contrast to SysInternals DbgView this utility has no limitations to total amout of logs. (DbgView crashes on huge logs, about 4Gb). Has a number of settings and can be reconfigured from keyboard without restart.

It works so: driver locates the point where DbgPrint() sends string to internal kernel function. Then it patches call address to point to hook routine. Hook copies messages to 1Mb buffer. user-mode application obtains these messages from driver via IOCTL. Messages from OutputDebugString() are catched by separate thread in user-mode app.

Latest versions can capture boot-time logs and can operate as service, so user is not required to log in. You can use -svc and -drv switches to enable this functionality (see below).

Note: driver and service installation code looks for DbgPrintLog.exe and DbgPrnHk.sys in the directory where DbgPrintLog.exe is located. Thus I recommend you to specify full path to DbgPrintLog.exe or run it from the directory where it is located. This will help to avoid execution of previously installed version from %SystemRoot%\System32 or some other place specified in %PATH% environment variable.

For convenience of writing scripts, oriented on software testing, the EchoDbg utility is added to this package. In contrast to standard echo command EchoDbg allows sending text messages to DebugConsole using OutputDebugString(). In addition EchoDbg can redirect StdIn to DebugConsole. When used in testing scripts EchoDbg makes easy to synchronize logs from top-level requests (for example sequences of file manipulation commands) with low-level application responses (for example from underlaying file system driver).

You can also use something like SDK - .H and .LIB, those makes easy to send debug-messages directly to driver's intarnal buffer. It has API similar to printf().

Also, if you are interested, here you can read more about internals of KdPrint()/OutputDebugString().

Compatibility

DbgPrintLog utility was tested under the following OSes with enabled and with disabled SoftIce:

NT 3.51
NT 4.0               build 1381 Service Pack 4
NT 4.0               build 1381 Service Pack 6
NT 4.0               build 1381 Service Pack 6a
NT 4.0 (TS)          build 1381 Service Pack 6
NT 5.0 (Win 2000)    build 2195
NT 5.0 (Win 2000)    build 2195 Service Pack 2
NT 5.0 (Win 2000)    build 2195 Service Pack 4
NT 5.1 (Win XP)      build 2600 Service Pack 1, v.1081
NT 5.1 (Win XP)      build 2600 Service Pack 2, v.2055
NT 5.1 (Win XP)      build 2600 Service Pack 2
NT 5.2 (Win 2003)    build 3790
NT 5.2 (Win 2003-R2)            Service Pack 1
NT 6.0 (Vista)       

Command line reference

Debugger extension

Command line switches for DbgPrintLog (you can read about legacy switches here):

Usage:
    DbgPrintLog.exe [<switches>] [<log-file name>]
Switches:
    Log-file format:
	-m, --caller_mode
	         write initiator mode (K - kernel, U - user) to log
	-p, --pid, --process_id
	         write ProcessId to log
	-P, --pname, --process_name (since v0.8a)
	         write Process Name to log
	-t, --tid, --thread_id
	         write ThreadId to log (for kernel-mode only)
	-i, --irql
           write IRQL to log (for kernel-mode only)
	--cpu    write CPU num to log (for kernel-mode only)
	--full   same as -m -p -t -i
	--raw    (since v0.8b)
	         write messages in raw format (doesn't affect syslog stream)
	-T FMT, --timestamp_fields FMT
	         specify absolute time format FMT. FMT string can contain
	         the following switches: D - date, T - time, N - high precision time
	         R - relative time (tick count), U - UTC time
	-fm M    do not log messages from <M> mode
	         <M> can be K - kernel or U - user
	--filter:<action> <condition>
	         perform <action> for all messages matching <condition>
	         prior to putting them to log. For now the only possible action
	         is DENY (or BLOCK, SKIP, DROP). Available <conditions> are:
	         origin=kernel (origin=ring0 or K) - messages from kernel mode
	         origin=user (origin=ring3 or U) - messages from user mode
	-sfp, --stack_frame_ptr  (since v0.7)
	         write Stack Frame Pointer information to log (for kernel-mode only)
    Log-file control:
	-s NUM, --max_log_size NUM
	         set max log-file size to NUM Mbytes (0 < NUM < 2048)
	         128Mb is used by default
	-S NUM, --prealloc_log_size NUM
	         does like -s, but sets initial file size to specified value.
	         Is intended mainly for use by GUI tool.
	-x NUM, --build_index NUM
	         create index file for each log file.
	         Is intended mainly for use by GUI tool.
	-l NUM, --max_log_count NUM, --log_rotate_count NUM
	         keep NUM latest log files
	-n NUM, --initial_log_number NUM
	         set start log number to NUM
        -ovw, --overwrite_old_log  (since v0.7f)
                 overwrite existing log files
	-ft NUM, --flush_timeout NUM
	         flush messages buffer after NUM seconds of inactivity
	-sm, --sync_mode
	         synchronous mode. all messages are flushed immediately
	-wd DIR, --working_directory DIR
	         specify working directory
    Output data stream control:
	--out:<output> [<parameters>]
	         since v0.8b multiple --out: options ara allowed
	         available values for <output> are:
	  stdout   write log to STDOUT instead of file
	  file     write log file (default)
	  syslog HOST[:PORT] (since v0.8a)
	           send messages via UDP syslog protocol to
	           speciified PORT of HOST. PORT is defaulted to 514
	  none     do not write logs anyware
	           just forward OutputDebugString to driver
	-o, --stdout
	         same as --out:stdout
	-cf      same as --out:file --out:stdout
	--no_out same as --out:none
        --syslog:mtu MTU (since v0.8c)
                 set maximum syslog packet size to MTU bytes (1024 by default)
    Input data stream control:
	--in:<input> [<parameters>]
	         available values for <input> are:
	  drv      read message stream from the driver (default)
	  stdin    read message stream from STDIN
	  file FILENAME
	         read message stream from FILENAME
	  comdbg   read serial port (COM) over WinDbg protocol (since v0.8g)
	  syslog [HOST][:PORT] (since v0.9)
	         get messages via UDP syslog protocol at
	         speciified PORT of HOST. PORT is defaulted to 514
	         HOST is defaulted to ANY interface of local host
	--stdin  same as --in:stdin
	--in_file FILENAME
	         same as --in:file FILENAME
	--in_drv same as --in:drv
	--comdbg:port NUM (since v0.8g)
	         use serial port NUM
	         by default used COM1 if _NT_DEBUG_PORT env. variable
	         not defined
	--comdbg:baud NUM (since v0.8g)
	         use baudrate NUM (e.g. 9600, 19200, 57600, 115200)
	         by default used 115200 if _NTKD_BAUD_RATE env. variable
	         not defined
	--comdbg:int3 NUM (since v0.9a)
	         INT3 handling: 0 - do not handle, 1 - skip, 2 - prompt
    Service control:
	--svc:install MOD
	         install or uninstall as service. MOD specify startup mode:
	         A - automatic, M - manual, U - uninstall. 'A' is used by default
	         if MOD is omited.
        --run:MOD  (since v0.7e)
                 Specify DbgPrintLog.exe run mode:
                 U, user - run as plain user even under SYSTEM account
                 S, svc  - run as service regardless of user account
                 by default Service mode is assumed if runnyng under SYSTEM account
    Driver run mode:
	--drv:install MOD
	         Specify driver startup mode:
	         1 - very first (boot), B - boot, S - system,
	         A - automatic, M - manual, U - uninstall
	         'M' is used by default if MOD is omited.
	--drv:noload, --no_drv
	         do not use driver for message routing
	--drv:reload, -rd
	         restart and reinstall driver before start
	--drv:reconfig, -rc  (since v0.7)
	         make driver to read config changes from Registry
	--drv:opt OPTION_NAME VALUE
	 or --drv_opt OPTION_NAME VALUE
	         Specify driver startup option. Valid OPTION_NAMEs and VALUEs are
	  CheckIrql               0|1
	  BufferSize               NUM (in KBytes, integral multiple of 2)
	  DoNotPassMessagesDown   0|1
          StopOnBufferOverflow    0|1|2 (2 invokes Kernel Debugger on overflow)
          TimeStampType           0|1|2
	  AggregateMessages       0|1
	  DumpStackFramePtr       0|1
	         Read documentation for each option description
    Misc options:
	--status display information about installed and active components
	--nowait do not wait for new messages, just dump already stored in driver and exit
	-h, -?, /?, /h, --help
	         display this help message

Console commands reference

When DbgPrintLog is running as console application, you can control it with the following hot-keys:

Commands:
    'Esc'   - exit
    'N'     - start new log
    'F'     - flush log buffer
    'H'     - display this help message

Mode switchers (toggle on/off):
    'Space' - pause
    'S'     - synchronous mode
    'C'     - copy log to stdout
    'K'     - capture kernel messages
    'U'     - capture user-mode messages
    'I'     - CheckIrql
    'P'     - DoNotPassMessagesDown
    'O'     - StopOnBufferOverflow
    'A'     - AggregateMessages
    '?'     - query current options

Examples

Logging Boot-driver

If you want to capture logs generated during initial boot phase, for example logs from SCSI/IDE drivers, I would recommend the following install options for DbgPrintLog:

DbgPrintLog.exe --full -T DTN -wd X:\dir_for_logs --drv:inst 1 --svc:inst A --drv:opt DoNotPassMessagesDown 1
    --drv:opt StopOnBufferOverflow 1 --drv:opt BufferSize 16384 BootInit.log

With such settings driver shall intercept all calls to DbgPrint() and store messages in its internal 16Mb buffer. When buffer gets full, newer messages shall be dropped until service is started. Then all stored logs are written down to file and capturing process contuniues in normal way. Because debug messages are not passed to the original DbgPrint() routine, you can sefely produce logs on high IRQLs.

You can get captured logs in the following ways:

  • From X:\dir_for_logs folder (which you have specified in command line) if system successfully boots up.
  • From CRASHDUMP if system makes BSOD :)
    With Kernel Debugger extension.
  • When debugging over COM, IEE1394 or USB2.0 cable you can download latest messages with Kernel Debugger extension when necessary.
  • Since v0.8g you can download logs over COM cable directly with DbgPrintLog. You need not WinDbg and shall not meet difficulties when running different NT OS versions on master and slave machines. Also, in this case our helper driver is not required to be installed on target machine.
Remote debugging

If you want to capture latest logs generated before crash using remote debugging (e.g. with WinDbg over COM, IEEE1394, USB2.0), I would recommend the following install options for DbgPrintLog:

DbgPrintLog.exe --out:none --drv:inst 1 --svc:inst A --drv:opt DoNotPassMessagesDown 1
    --drv:opt StopOnBufferOverflow 0 --drv:opt BufferSize 16384

With such settings driver and service together shall intercept all calls to KdPrint()/DbgPrint() and OutputDebugString() and store messages in internal 16Mb buffer. When buffer gets full, older messages shall be dropped. Because debug messages are not passed to the original DbgPrint() routine, there will be no performance degrade due to sending logs to remote debugger.

You can download latest messages with Kernel Debugger extension

Remote debugging without WinDbg

If you experience OS version compatibility problem (WinDbg doesn't work normally when master and target OS versions are different), you may use DbgPrintLog instead. For now it supports only COM-port debugging. Configure target machine for using COM-port as decrined in WinDbg HOWTO for QA engineers. Then run DbgPrintLog:

DbgPrintLog.exe --full --in:comdbg --comdbg:port 1 --comdbg:baud 115200 DbgLog.log

In this case DbgPrintLog will pretend to be WinDbg, get logs and save them to file. Note, you must run DbgPrintLog before rebooting target machine. When target machine reboots and starts looking for debugger, DbgPrintLog shall already listen on COM-port.

Logging System-driver

If you want to capture logs generated by drivers with system startup type, for example from CDROM driver, I would recommend the following install options:

DbgPrintLog.exe --full -T DTN -wd X:\dir_for_logs --drv:inst B --svc:inst A 
    --drv:opt StopOnBufferOverflow 1 --drv:opt BufferSize 16384 SystemDrivers.log

With such settings driver shall intercept all calls to DbgPrint() and store messages in its internal 16Mb buffer. When buffer gets full, newer messages shall be dropped until service is started. Then all stored logs are written down to file and capturing process contuniues in normal way. Вebug messages are passed to the original DbgPrint() routine, thus you should not produce logs on high IRQLs.

Logging Logon process

If you want to capture logs generated during logon process, for example from gina.dll, I would recommend you to use DbgPrint logger SDK for debug output in your application instead of standard OutputDebugString(). This is because OutputDebugString() capturing requires DbgPrintLog.exe to be already started, but it can be not started yet.

I would recommend the following install options:

DbgPrintLog.exe -p -t -T DT -wd X:\dir_for_logs --drv:inst S --svc:inst A Logon.log

Driver shall store messages in its internal 1Mb buffer (default size). When buffer gets full, the most old messages shall be dropped. When service gets started all stored logs are written down to file and capturing process contuniues in normal way.

Logging on demand

If you want to capture logs during execution time of the application being debugged, I would recommend the following options:

DbgPrintLog.exe -p -fm K -T DT -wd X:\dir_for_logs MyApp.log

User mode part of the utility shall capture all messages coming through OutputDebugString() and store them in a file. No kernel messages from DbgPrint() shall be captured.

You can control log capturing process in console window with help of keyboard.

Deinstall

You you need to disable automatic launch of this utility, use the following command:

DbgPrintLog.exe -drv U -svc U

DbgPrintLog main page


See also:


Please, send your comments and propositions here: Mail to alterX@alter.org.ua (remove X)  
designed by Alter aka Alexander A. Telyatnikov powered by Apache+PHP under FBSD © 2002-2017