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)
--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
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
-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
Please, send your comments and propositions here:
alterX@alter.org.ua (remove X)
|
