er_label arguments
er_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 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 relative to the start time of the founder process in the experiment.
Filter criteria and markers associated with different labels are completely independent.
All invocations of er_label must specify a label name and an experiment name.
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.
Name the label. The label-name can be any length, but it must be alphanumeric, beginning with a letter, and 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. Label names are case insensitive. Label names must not conflict with other names that can appear in filters, including properties in experiments or names of memory-objects or index-objects. Properties from loaded experiments are listed with the er_print describe command. Memory-objects are listed with the er_print mobj_list command. Index-objects are listed with the er_print indxobj_list command.
Add a comment explaining the label. Multiple -C arguments may be used, and they will be concatenated, with a semi-colon and a space between the comments.
Specify a start or stop point defining a time range within the experiment.
If the time-specification following the equal sign is specified as offset, 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 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 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 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 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 argument is not followed by an equal sign with the time specification, =@ is assumed for the specification.
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.
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
analyzer (1) , collect (1) , er_print (1)
Performance Analyzer manual