er_label(1)er_label(1)NAMEer_label - label parts of an experiment for easier filtering
SYNOPSISer_label arguments
DESCRIPTIONer_label is a utility that annotates an experiment with persistent
named labels that define a subset of the given experiment, and can be
used to construct filters for examining 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 pre‐
vious 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 relative to the start time of
the founder process in the experiment.
Filter criteria and markers associated with different labels are com‐
pletely 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 exper‐
iment can be named; experiment groups are not supported. A sin‐
gle -o argument is required, but may appear anywhere on the com‐
mand 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 cri‐
teria will be added to it; if it did not exist, it will be cre‐
ated. 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 arguments 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 specified as off‐
set, it refers to a time relative to the beginning 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 sec‐
onds 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 sec‐
onds and minutes fields must be between 0 and 59. If the hour field is
not specified, 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 pre‐
cision 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 specifications 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 argu‐
ment 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 examples 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 command:
er_label-o test.1.er -n snap -t start=15 -t stop=10:15
SEE ALSOcollect(1), analyzer(1), er_print(1), and the Performance Analyzer man‐
ual.
September 2011 er_label(1)