NAME
er_label - label parts of an experiment for easier filtering
SYNOPSIS
er_label arguments
DESCRIPTION
er_label is a utility that annotates an experiment with per-
sistent named labels that define a subset of the given
experiment, and can be used to construct filters for examin-
ing the experiment data.
Time-based labels
Time-based labels support start and stop markers. The
defined by the markers will include all profile events
between any number of start and stop pairs. A stop marker
before any start marker, or following a previous stop marker
with no intervening start marker will be ignored. A start
marker following a previous start marker with no intervening
stop marker will be ignored.
The time markers may be specified as the current time, the
current time plus or minus an offset, or as a offset rela-
tive to the start time of the founder process in the experi-
ment.
Filter criteria and markers associated with different labels
are completely independent.
REQUIRED OPTIONS
All invocations of er_label must specify a label name and an
experiment name.
-o experiment
Name the experiment to which the label applies. Only
one experiment can be named; experiment groups are not
supported. A single -o argument is required, but may
appear anywhere on the command line.
-n label-name
Name the label. The label-name can be any length, but
it must be alphanumeric, with no embedded spaces, even
if quotes are used around the string. If the label-
name exists, the new criteria will be added to it; if
it did not exist, it will be created. A single -n
argument is required, but may appear anywhere on the
command line.
OPTIONS
-C comment
Add a comment explaining the label. Multiple -C argu-
ments may be used, and they will be concatenated, with
a new line between the comments.
-t {start|stop}[=time-specification]
Specify a start or stop point defining a time range
within the experiment.
If the time-specification following the equal sign is speci-
fied as offset, it refers to a time relative to the begin-
ning of the experiment. If the time-specification following
the equal sign is specified as "@", it refers to the current
time; if it is specified as @+offset, or @-offset, it
refers to a time after or before the current time.
offset is specified in the form:
[[hh:]mm:]ss[.uuu]
The hour and minute and subsecond fraction are optional, but
the seconds setting is required. If only the seconds field
is supplied, the numerical value can be greater than 60, and
will be converted to hours and minutes as appropriate. If
the hour field is specified, the seconds and minutes fields
must be between 0 and 59. If the hour field is not speci-
fied, the minutes field can be greater than 60, and will be
converted to hours as appropriate, but the seconds field
must be between 0 and 59. The subsecond fraction may be
specified to any precision desired, and it will be saved to
nanosecond precision.
Multiple -t specifications may be given in a single command;
they will be processed left-to-right. If multiple specifi-
cations referring to the current time are given, they will
all refer to a single timestamp captured for the current
time ("@"). If the -t stop or -t start argument is not
followed by an equal sign with the time specification, =@ is
assumed for the specification.
USAGE MODEL
Client-driven Server Profiling
One use of er_label is to support profiling a server which
is being driven by a client as an independent process or
processes. In this usage model, an experiment is started on
the server. Once the server is started and ready to accept
requests from a client, a client script containing er_label
invocations can be used to drive the server. (In the exam-
ples below, the experiment name is assumed to be test.1.er).
A sample client script which produces a time label for each
request run against the server is:
for REQ in req1 req2 req3 req4 req5
do
echo "=========================================================="
echo " $REQ started at `date`"
er_label -o test.1.er -n $REQ -t start=@
run_request $REQ
er_label -o test.1.er -n $REQ -t stop=@
done
Each of the five labels created marks off the time spent
processing the named request.
An alternative usage that produces a single label covering
all the requests would be:
for REQ in req1 req2 req3 req4 req5
do
echo "=========================================================="
echo " $REQ started at `date`"
er_label -o test.1.er -n all -t start=@
run_request $REQ
er_label -o test.1.er -n all -t stop
done
Note that no string follows the stop in the last line; it
defaults to stop=@. More complex scripting can be used, and
multiple such scripts can be run simultaneously on the same
node or on different nodes. The labels in each script can
be the same or different.
Other Uses
To define a label relative to the experiment start, covering
the part of a run from 15 seconds after the start of the
program for a duration of 10 minutes, use the following com-
mand:
er_label -o test.1.er -n snap -t start=15 -t stop=10:15
SEE ALSO
collect(1), analyzer(1), er_print(1), and the Performance
Analyzer manual.