|
%SYS
|
|
|
%SYS
|
|
This class provides methods to trace the execution of a process. More...
Static Public Member Functions | |
| Display (_.Library.String file, _.Library.String flags) | |
| Writes a formatted display of a trace file to the current device. More... | |
| _.Library.List | EventNames () |
| Returns a list of event names. | |
| _.Library.SysPath | GetDirectory () |
| Returns the directory where trace files will be written by processes being traced. | |
| _.Library.List | GetEvents () |
| Returns a list where each list element is a monitor event to record. More... | |
| _.Library.Integer | GetMaxSize () |
| Returns the system-wide default for maximum trace file size in MB. More... | |
| _.Library.List | PIDList () |
| Returns a list all process IDs that are being traced. | |
| _.Library.Status | SetDirectory (_.Library.SysPath dir) |
| Sets the directory where trace files will be written by processes being traced. More... | |
| _.Library.Status | SetEvents (_.Library.List events) |
| Set the default list of monitor events that traced processes will record in the trace file. More... | |
| _.Library.Status | SetMaxSize (_.Library.Integer maxsize) |
| Sets the system-wide default for maximum trace file size in MB. More... | |
| _.Library.Status | StartPID (pid, _.Library.String dir, _.Library.List events, _.Library.Integer maxsize) |
| Start tracing in a target process. More... | |
| _.Library.Status | StopPID (pid) |
| Stop a process's trace. | |
| _.Library.Status | ValidateDirectory (_.Library.SysPath dir, _.Library.SysPath ndir) |
| Validates a directory argument for tracing. More... | |
| _.Library.Status | ValidateEvents (_.Library.List events) |
| Validate a list of monitor events for trace files. More... | |
| _.Library.Status | ValidateMaxSize (_.Library.Integer maxsize) |
| Accepts as input a size cap in MB, converts to bytes, and checks if the byte count is within range. More... | |
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.
|
static |
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)
|
static |
Returns a list where each list element is a monitor event to record.
See <METHOD>SetEvents</METHOD>.
|
static |
Returns the system-wide default for maximum trace file size in MB.
See SetMaxSize.
|
static |
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).
|
static |
Set the default list of monitor events that traced processes will record in the trace file.
The list of available events is returned by <METHOD>EventNames</METHOD> 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.
|
static |
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).
|
static |
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.
|
static |
Validates a directory argument for tracing.
Returns status success or error and, if validation passes, passes the normalized directory back in ndir.
|
static |
Validate a list of monitor events for trace files.
Returns status success if the event list is valid and an error if not.
|
static |
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.
1.9.1