Log file format

First, an example.

head {
  events {
    10 "BEGIN:Begin"
    11 "MAIN:Enter main loop"
    21 "LOCKREQ:Request lock"
    22 "LOCKREC:Receive lock"
    99 "END:End"
  states {
    21 22 "Waiting for lock"
  counters {
  timeunitspersec 1.0e+6
  nproc 4
  starttime 00001AF0
foot {
  stoptime 00001FF3
The log file consists of a magic number, a header, a series of records, and a footer. These four segments are delimited by 1 or more white space characters.

Magic Number

The first ten bytes of the file are "the magic number": the string GISTLOG-01. The numeral 01 will be incremented when the file format is changed substantially.

Header and Footer

The header and footer have the same basic structure. The settings may appear in any order. In the future we may designate some as "optional" and declare default values for their absence. We may also specify new settings as necessary.

The events are pairs of tokens. In a pair, the first token is an event number in decimal, and the second is a descriptive string. Optionally, the string is of the form tag:description, where the tag is the symbolic tag that the programmer has chosen to stand for the event number in her code.

The states are triples of tokens. They consist of a a pair of events e0,e1 and a descriptive string. A state is said to exist when its start and stop events are adjacent in a stream of events (say, per thread or processor). Notice that the tag:description convention is not used here; if a concise tag is desired for a state, it is formed from the tags of its two events. For example, in the file above, the symbolic name for the waiting state could be LOCKREQ-LOCKREC. The counters is a list of names for the quantities measured.

The timeunitspersec is a decimal floating-point quantity representing the number of time units in a second.

The nproc is the number of processors in decimal. This is in the footer since it may only be known after all of the Gist_log() calls have been executed.

The starttime and stoptime are the time at the beginning and ending of execution.

Event records

All records contain the same number of bytes and are delimited by white space. (In the future, we may specify that the records are further padded by a fixed amount of white-space so that they start at, say, 256-byte offsets.) The fields are separated by colons. The fields are: The number of digits in each field is arbitrary, but is the same for all records in a single log file.

Timothy Culver
Last modified: Mon Mar 29 11:36:19 EST 1999