OS/2 Trace Tools v. 20201213 (13/12/2020, Steven Levine) |
Readme/What's new |
How to use the trace tools
2018-04-06 SHL
This package includes two scripts (trcinit.cmd and trcctl.cmd) that
implement an interface to the OS/2 Trace Facility. These scripts are
designed to make it easier to capture the specific trace data needed to
analyze a problem. The scripts are generic. The tracepoints and settings
needed to capture specific data are defined in a configuration file. The
configuration file name is passed to trcinit on the command line. If you do
not supply a configuration file name trcinit will look for the file named
trcinit.cfg.
You need to have a working OS/2 trace setup to use these scripts.
If you don't have a working OS/2 trace setup, see:
http://www.warpcave.com/os2diags/TraceRef.txt
for a cookbook setup guide. TraceRef.txt explains how to get the OS/2 Trace
Facility ready to use on your system. It also includes a sample script for
those that want to write their own scripts. The sample script is
exactly that - a sample. It is unlikely to capture data relevant to your
particular problem.
Once you have the trace facility working, place trcinit.cmd, trcctl.cmd and
the trace configuration file in a convenient directory. This will often be
the application home directory.
If you are working on an application startup problem, shut down the
application before running trcinit.
Run trcinit from the command line supplying the name of the trace
configuration file.
Trcinit will setup the tracepoints and invoke trcctl. Trcctl provides an
interactive interface to the trace facility.
If application in not running, start it now.
Perform whatever actions are needed to trigger the problem you are
analyzing.
Switch to the Trace Formatter window and request File -> Recapture. The
Trace Formatter will read the captured trace data from memory and display it
in the formatter window.
The formatted trace data display is in reverse time order, so you usually
need to read the window from the bottom up.
The trace buffer is fixed size and new data overwrites old data. Request the
recapture as soon as possible after the problem occurs or you may lose the
data you need to see.
To write the formatted data to a file, use File -> Save Formatted.
When you are done with the trace, switch back to the trcctl window and enter
q to shut down trcctl.cmd. Trcctl will turn off all tracepoints and reset
the Trace Facility to a disabled state.
You will usually be supplied with a preconfigured configuration file, but
for the curious, here is an overview of the configuration file layout.
A configuration file will contain some combination of configuration commands,
comments and blank lines.
Comment lines begin with a semicolon (i.e. ;). Blank lines are ignored.
Each configuration commands must be on a single line. Command commands are
of the form:
keyword = value
Command keywords and values are case-insensitive. Some commands take yes/no
values. Yes/no values such as Y, Yes, 1, N, No and 0 are accepted.
The configuration command keywords and their value styles are:
keyword value style default
------- ----------- -------
CMD = trace command none
OPTIONS = trace options none
DIEONERROR = yes/no yes
EXE = executable name none
FINDPID = yes/no no
PID = hexadecimal PID none
All configuration commands are optional, although a typical configuration
file will have an EXE command and one or more CMD commands. A simple
example would be:
exe = trace
cmd = trace on os2krnlr(fs)
The CMD keyword defines a trace command. Typically, the command value will
be a trace command to set specific tracepoints, as shown in the example. The
command value is passed to the shell for execution, so this value can be any
valid shell command. To define multiple trace commands, provide multiple CMD
configuration commands. The commands will be executed in the order they
appear in the configuration file.
The OPTIONS keyword allows the default values used by the trace tools for
buffer size, mode and optional data to be overridden. The mode and optional
data values can be overridden with the CMD configuration command, but the
trace facility does not report accurate return codes when the working
with the buffer size and this will cause the CMD configuration commands to
fail because only zero return codes are expected. The OPTIONS
configuration command avoids this by providing special handling the spurious
return codes.
For example
options /b:1024
will initialize the buffer size to 1MB.
options /d:tsc
can be used to include the timestamp in the trace data, but
cmd trace off /d:all
cmd trace on /d:tsc
is better because it is less sensitive to the existing optional data
settings.
The DIEONERROR configuration command defines how certain errors are handled.
If the command value is set to no, trcinit will continue if an executable or
PID can not be found or if a CMD command fails. The default action is to
quit.
The EXE configuration command value specifies an executable to be traced.
Trcinit will search the PATH for the executable and will report if the
executable can not be found. To trace multiple EXEs, supply multiple EXE
commands. If there are no EXE or PID commands, all executables will be
traced.
The FINDPID configuration command controls PID lookup. If the command value
is yes, trcinit looks up the PID for the executable(s) named by the EXE
command(s). If the executable is not running, trcinit will report the error
and quit. The default action is to bypass PID lookup.
The PID configuration command specifies the hexadecimal process ID of a
process to be traced. Trcinit will search the process list and report the
name of the executable corresponding to the PID. If the search fails,
trcinit will report the error and quit. To trace multiple PIDs, supply
multiple PID commands. The PID command may not be used with the EXE command
unless PID lookup is enabled with the FINDPID command.
WARNING
=======
As of 2004-09-08, it is known that krnlrfs tracepoints 281 and 282, which
are in the QUE group, will trap with kernels between 14.93c and 14.100c.
This may not be a complete list. This means, do not specify:
trace on krnlrfs
or
trace on krnlfs(que)
Specify explicit tracepoints or groups that do not include the above trace
points and group. For example:
trace on krnlrfs(fs)
is OK.
Good luck,
Steven |
Add new comment