User-Specified Events

user events

The ALOG package consists of a set of macros that can be used to instrument a C program and a set of functions that can be used to instrument a Fortran program. We will focus here primarily on the use of the C interface, which contains more functionality.

The macros that can be used to instrument a program are as follows (from the file README_ALOG in the alog directory):

ALOG_SETUP
\begin{example} ALOG_SETUP(pid,flag): pid - (integer) process id of callee flag - (integer) either ALOG_WRAP or ALOG_TRUNCATE \end{example}
This macro initializes the tracing area for a slave process and must be called once before any event is logged. If the value of flag is set to ALOG_WRAP, then in the event of no more space for logging events the system will only report the latest n events. If flag is set to ALOG_TRUNCATE the system will stop logging events as soon as there is no more memory for the events to be logged.

ALOG_MASTER
\begin{example} ALOG_MASTER(pid,flag): pid - (integer) process id of the callee flag - (integer) either 0 or 1 (see above) \end{example}
This macro has the same effect over its parameters as ALOG_SETUP with the difference that this macro should be referenced by the master process only.

ALOG_DEFINE
\begin{example} ALOG_DEFINE(event,strdef,format): event - (integer) id of event... ...of 'event' format - (string) control string in ''printf'' format \end{example}
This macro puts an event definition code into the logfile.

ALOG_LOG
\begin{example} ALOG_LOG(pid,event,intdata,strdata): pid - (integer) process id... ...event strdata - (string) any string data (can be the null string) \end{example}
This macro provides the event logging service.

ALOG_OUTPUT
\begin{example} ALOG_OUTPUT no parameters \end{example}
This macro dumps the events logged into a log file with the name alogfile.pxx where xx is the logical PID of the callee process. The log file is created in the current directory unless specified otherwise through the macro ALOG_SETDIR.

ALOG_SETDIR
\begin{example} ALOG_SETDIR(dir) dir - (string) directory where log file is created \end{example}
This macro sets the output directory for the log file. The default directory for the creation of the log file is the current directory of the process. If used, then this macro MUST be invoked before ALOG_MASTER/ALOG_SETUP.

ALOG_STATUS
\begin{example} ALOG_STATUS(status): status - (integer) either ALOG_ON or ALOG_OFF \end{example}

This macro controls the logging status of ALOG as follows. Setting status to ALOG_ON enables logging until it is turned off. Setting status to ALOG_OFF disables logging until it is turned on again. Logging is enabled at the outset by default.

ALOG_ENABLE
\begin{example} ALOG_ENABLE no parameters \end{example}

This macro enables event logging; same as calling ALOG_STATUS(ALOG_ON).

ALOG_DISABLE
\begin{example} ALOG_DISABLE no parameters \end{example}
This macro disables event logging; same as calling ALOG_STATUS(ALOG_OFF).

The sample program gridlog.shmem.c in the monitors subdirectory contains an example of a program instrumented with ALOG statements. The macro definitions for ALOG are included when you include #include "p4" in your program. If the line #define ALOG_TRACE is not included before the #include "p4", these macros will generate no code. Thus it is easy to effectively de-instrument the code by recompiling, and there is no need to protect each ALOG statement with an #ifdef.

When an ALOG-instrumented program is run, it will produce one logfile for each process. The files will be named alogfile.p0, alogfile.p1, .... These files need to be merged into a single file with the events sored by timestamp. This is accomplished with the program mergelogs, found in the bin subdirectory. To merge the logfiles, do


\begin{example} mergelogs alogfile.p* > myprog.log rm alogfile.p* \end{example}

The resulting logfile can be examined by upshot or some other logfile examination facility. See [#!herrarte-lusk:upshot!#] for details of the logfile format.

On networks of workstations and some distributed memory machisnes, the microsecond timers on the various processors are synchronized. To produce a usable merged logfile, the adjlogs program, also found in the bin directory, can be used to adjust the timestamps for offset and drift before they are merged. For this to work, synchronization events must be placed in the logfiles by an ALOG_LOG statement. The event type is then passed to adjlogs, which aligns the timestamps, based on the timestamps of the synchonization events. The call to adjlogs looks like this, where <n> is the type of the synchronization event.


\begin{example} adjlogs -e <n> \end{example}

Both mergelogs and adjlogs are less portable than the other p4 code; you might want to run them on a workstation such as a Sun.

Examining Log Files with Upshot,Automatic Logging of p4 Events,User-Specified Events,Creating Logfiles for Upshot