A declaration introduces a name for a constant, event type, or interval type into the global scope. The name is available in all expressions that follow the declaration.
An interval type name is not available in metric definitions for that type (thus, interval declarations are not recursive). A declaration may also introduce a name for an unknown number to be solved for later. It is an error to redeclare a name in the same scope (but a name may be redeclared in a nested scope).
A.3.1 Constants
If id is an identifier and e is an expression, then:
def id = e
declares id as a constant bound to the value of e. e is evaluated in the global scope.
The declaration def id = ?
declares id to be an unknown. Unknowns are recognized by psolve, the PSpec solver, and are different from UNDEFINED values.
A.3.2 Event Types
If id is an identifier and alist is a (possibly empty) comma-separated list of identi-fiers, then the two declarations
event id ( [ alist ] ) and
timed event id ( [ alist ] )
declare id as an event type.1 Events of the type have attributes named in alist.
The second form also indicates that events of type id have an implicit timestamp attribute, which is used by the elapsed function on intervals and the timestamp and elapsed functions on events. Note that the timed events in a log need not necessarily occur in timestamp order.
A.3.3 Interval Types
An interval type declaration introduces a new interval type, which identifies a set of intervals in an event stream. An interval type declaration provides predicates for determining whether an event in the event stream is the start or end event for an interval of the type, and expressions for computing the metric values for an interval of the type.
An interval declaration may also introduce virtual time events into the event stream to mark the start or end of an interval based on time. These are described in the next section.
The basic interval type definition identifies an interval by the types of its start and end events in an event stream. If id, s, and e are identifiers, stype and etype are event type names, and spred and epred are boolean-valued expressions, then:
[ nested ] interval id = s: stype [ where spred ] , e: etype [ where epred ] [ metrics
mlist ] end id
1The square brackets here and in the rest of the appendix indicate optional elements and are not themselves part of the syntax.
declares an interval with type name id. mlist is a comma-separated list of metric definitions of the form m = expr where m is an identifier and expr is an expression.
The declaration defines an interval of type id to be one that has a start event named s of type stype for which spred is true, and an end event named e that is the next event in the event stream of type etype following the start event for which epred is true.
An interval declaration may be modified slightly by inserting the keyword nested before interval. A nested interval type has the further condition that the end event e is not an end event for any other interval of type id that starts after the event s. In this case, e is the end event for the interval started by the nearest preced-ing s that does not already have an end event. Thus, without the nested restriction, multiple intervals of the type may share the same end event. With the restriction, all intervals of the type will have different end events and will nest like parentheses.
It is always the case that multiple intervals of different types may share end events.
For each interval of type id in the event stream, its metrics are computed as follows. A new scope is introduced with s and e bound to the start and end events for the interval. The metric expressions are evaluated in this scope over the portion of the event stream enclosed by the interval, and their values are bound to the inter-val’s metric names. This binding is, in effect, simultaneous for all of an interinter-val’s metric definitions; hence metric definitions may not reference each other. Metric expressions that aggregate over events or intervals may not refer to the end event e (because of implementation efficiency considerations).
The where-clause for the start or end event may be omitted, in which case it defaults to true. The metrics mlist clause may be omitted, in which case the interval has no metrics (but the elapsed function may still be applicable for the interval).
The identifier s is available in spred and epred. The identifier e is available in epred. Both identifiers are available in the metric expressions, as explained above.
The identifier id cannot be referenced inside mlist. Moreover, expressions in mlist cannot reference constants that are defined in terms of aggregate expressions.
A.3.4 Time-based Interval Types
In an interval type declaration, the start event declaration s: stype [ where spred ]
can be replaced by the declaration:
s: [ from oexpr ] every texpr
where s is an identifier, and oexpr and texpr are positive number-valued expres-sions. This declaration introduces new virtual time events of type start$I (where I
is the interval type name) into the event stream. The events have timestamp values startts + oexpr + (i * texpr), for i = 0,1,. . ., where startts is the first event times-tamp in the log. In other words, the virtual time events occur starting oexpr time units after the first event in the log, and every texpr time units thereafter. Each such virtual time event starts a new interval of the type. The from clause may be omitted, in which case oexpr defaults to 0.
If the events in the log are in timestamp order, the virtual time events are in-serted in timestamp order, up to the last real event in the log. If a virtual event has the same timestamp as a real event, the virtual event is inserted before the real event. If two virtual events have the same timestamp, their relative order is undefined.
If the events in the log are not in timestamp order, then the sequencing is more complicated. For each declaration of an interval type I, virtual eventsve0, ve1, . . ., of type start$I, are inserted into the event stream as follows:
1. ve0, which has timestamp t0 = startts+oexpr, is inserted before the first real event whose timestamp is at least t0.
2. vei, which has timestamp ti =startts+oexpr+(i∗texpr)(for i =1,2, . . .), is inserted after vei−1, and before the first real event whose timestamp is at least ti and that occurs after vei−1. If no such real event exists, vei is discarded (as are all subsequent virtual events resulting from this interval type declaration).
In addition, two virtual events that are adjacent in the event stream are in timestamp order.
Similarly, the end event declaration for an interval type, e: etype [ where epred ]
may be replaced by the declaration:
e: after texpr
where e is an identifier and texpr is a positive number-valued expression. This declaration introduces, for each start event s that matches the interval type’s start declaration (s may be virtual or real), a new virtual time event v of type end$I where I is the interval type name, and with timestamp value timestamp(s) + texpr.
v ends the interval that was started by s, and is inserted in the event stream before the first real event following s that has a timestamp value at least timestamp(s) + texpr.
A.3.5 Interval Subtypes
If id is an identifier, inttype is the name of a previously declared interval type, and mlist is a comma-separated list of metric definitions, then
interval id = inttype [ metrics
mlist ] end id
defines a new interval type, named id, that is a subtype of inttype. The new interval type is nested if inttype is nested, and has the same start and end event specification as inttype. It inherits all of inttype’s metric definitions, in addition to those newly defined in mlist. If mlist is supplied, the metric names in mlist must be different from inttype’s metric names.
A.3.6 Procedure Sugar
A proc statement provides a convenient syntax for declaring events and intervals corresponding to procedures in a program. If p, a1, a2,. . ., an, and r are identifiers, a statement of the form
proc p ( [ a1, a2, ..., an] ) [ returns r ]
has the effect of declaring two new events types named call@p and ret@p and a new interval type named intv@p. (These identifiers are special since @ cannot appear in an identifier supplied by a PSpec user). The declarations for these new types are equivalent to:
timed event call@p( [ a1, a2,. . ., an] ); ret@p( [ r, exact ] );
nested interval intv@p = s: call@p,
e: ret@p where thread(s) = thread(e) end intv@p
The argument list and returns-clause are optional.
An event of type call@p corresponds to a call of procedure p with integer argu-ments a1through an, and an event of type ret@p corresponds to a return of p with result r. Any of a1through anmay be replaced by the symbol ?, if the correspond-ing procedure argument is not of interest. If the returns r clause is omitted, the equivalent return event is ret@p(?, exact). The exact attribute on the return event has a value of 0 or 1, indicating whether the return event’s timestamp is approxi-mate or exact. If exact=0, then the timestamp was estiapproxi-mated from other events in
the log and may be later than the actual time at which the procedure exited. (This is to accommodate some monitoring techniques; for example, inexact timestamps result when procedures exit with exceptions rather than normal returns.) Note that in the interval type intv@p, the start and end events are always named s and e, respectively.