Skip to main content


abstract class %SYS.Trace extends %SYSTEM.Help

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.

Method Inventory


classmethod Display(file As %String, flags As %String)
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)

classmethod EventNames() as %List
Returns a list of event names
classmethod GetDirectory() as %SysPath
Returns the directory where trace files will be written by processes being traced.
classmethod GetEvents() as %List
Returns a list where each list element is a monitor event to record. See SetEvents().
classmethod GetMaxSize() as %Integer
Returns the system-wide default for maximum trace file size in MB. See SetMaxSize.
classmethod PIDList() as %List
Returns a list all process IDs that are being traced
classmethod SetDirectory(dir As %SysPath) as %Status
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).
classmethod SetEvents(events As %List) as %Status
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.

classmethod SetMaxSize(maxsize As %Integer) as %Status
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).
classmethod StartPID(pid, dir As %String = "", events As %List = "", maxsize As %Integer = "") as %Status
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.
classmethod StopPID(pid) as %Status
Stop a process's trace
classmethod ValidateDirectory(dir As %SysPath, ByRef ndir As %SysPath) as %Status
Validates a directory argument for tracing. Returns status success or error and, if validation passes, passes the normalized directory back in ndir.
classmethod ValidateEvents(events As %List) as %Status
Validate a list of monitor events for trace files. Returns status success if the event list is valid and an error if not.
classmethod ValidateMaxSize(maxsize As %Integer) as %Status
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.


query ReadFile(file As %String, flags As %String)
Selects Event As %String, Text As %String, TOffset As %Integer, Level As %Integer, Count As %Integer, LineAndRoutine As %String, RoutineSFN As %Integer, RoutineLoc As %String, SrcLine As %String, GlobalRef As %String, GlobalSFN As %Integer, GlobalLoc As %String
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.

  • Inherited Members

    Inherited Methods

    FeedbackOpens in a new tab