This class provides methods to trace the execution of a process. Traced processes
write events to a trace file with information about the routine line where it ocurred
and, if applicable, the global reference. The events available for tracing
correspond to the metrics reported in performance monitoring tools (PERFMON,
%SYS.MONLBL, etc). Raw data is written to a trace file, iristrace_pid.txt,
in a specified directory, which is parsed by this class.
Different sets of trace events can be selected to produce traces for different purposes.
Highly detailed application execution tracing can be achieved, including all
global references (the GloRef event), all application subroutine calls (RtnLoad)
and/or every line of application code executed (RtnLines). Or, tracing can be limited
to less common events such as physical block reads (DataBlkRd, UpntBlkRd, etc),
network cache misses (NCacheMiss), and/or block collisions (BlkWait), in order to
find all the locations in the application where these occurenced may be affecting
performance.
Writes a formatted display of a trace file to the current device.
The flags parameter may include the following characters
d - Display databases for routines and globals. If possible, ^sys^directory is displayed,
otherwise, internal system file numbers. If the trace file was created prior to the last
startup (or created on a different machine), the reported ^sys^directory may be inaccurate.
n - Display databases for routines and global references as internal system file numbers.
s - Display source line
w - Wait for more data if end of the file is encountered and the process is still being traced (ctrl-c to stop)
Sets the directory where trace files will be written by processes being traced.
Note that trace files may contain sensitive information such as global references
(but not values) or parameters passed to subroutines. The trace directory must
exist and must be writeable by the processes being traced (i.e. on UNIX and Linux
systems it must be writeable by the effective group selected at installation).
Set the default list of monitor events that traced processes will record in the trace file.
The list of available events is returned by EventNames() and listed in
by the ^TRACE or ^%SYS.MONLBL utilities.
Note that the "RtnLoad" event is treated specially, and traces not just literal
routine loads but all subroutine calls and returns. This allows for tracing the
application stack and time spent in subroutines, methods, and extrinsic functions.
Sets the system-wide default for maximum trace file size in MB. The default value is 0 (no cap).
The value, when converted from MB to bytes, must be a valid integer (maximum ~2047 MB).
Start tracing in a target process. If a trace file of the same name
already exists, it will be recreated. If arguments are empty,
system-wide defaults will be used.
Note that a successful return status does not wait for the target
process to (re)create the trace file.
Accepts as input a size cap in MB, converts to bytes, and checks if the byte count is within range.
If the byte count is negative or too large for a 32-bit integer, it is invalid.
Reads a trace file and parses records into rows with the following columns:
Event: the event (monitor metric) name, or special markers CALL, QUIT, START, STOP, HALT, ARG, STACK
Text: some events (ARG and STACK) carry only an unstructured text note relating to the previous event (with all other columns null)
TOffset: time offset from start in microseconds
Level: the stack level if subroutine calls are being traced, otherwise -1
Count: the number that this event would add to the corresponding performance metric (typically 1)
LineAndRoutine: routine line where the event occurred
RoutineSFN: internal SFN (system file number) for the routine database (directly from trace file)
RoutineLoc: an implied namespace (^sys^directory) corresponding to RoutineSFN. If the trace file was created prior to the last
startup (or created on a different machine), this column may be inaccurate or null.
SrcLine: the line of source code, if the "s" flag is used and if the source is available)
GlobalRef: Null if the trace event is not an operation on a global, otherwise the global
reference (gvn). The reference includes a leading ^. No environment is specified - it is not given
as an extended reference - except in the case of a process private global, which will include ^||.
In some unusual cases the global reference may not be able to be translated properly and either the
last subscript may appear incomplete, or the value of GlobalRef may instead be a printable sequence
of hex characters with no leading ^. Therefore the caller should be mindful if doing any
manipulations of this value (e.g. use try/catch if operating on this value with $qlength or $qsubscript).
If "q" is specified in the flags parameter, non-printing characters in the global reference will be
quoted (similarly to the output of the ZWRITE command).
GlobalSFN: internal SFN (system file number) for the database (directly from trace file)
GlobalLoc: an implied namespace (^sys^directory) corresponding to GlobalSFN. If the trace file was created prior to the last
startup (or created on a different machine), this column may be inaccurate or null. Process private globals also report null.
The flags parameter may include the following characters
s - fetch source line into SrcLine column from routine INT code
q - quote global reference to avoid non-printing characters in subscript
Note that if the end of the trace file is reached before a STOP or HALT record up fetching the
next row, an error $$$UnexpectedEndOfFile, will be returned and additional rows may become
available later if the traced process is still running.