Labeling Experiments

The er_label command enables you to define part of an experiment and assign a name or label to it. The label captures the profiling events that occur during one or more periods of time in the experiment that you define with start time and stop time markers.

You can specify time markers as the current time, the current time plus or minus a time offset, or as an offset relative to the start time of the experiment. Any number of time intervals can specified in a label, and additional intervals can be added to a label after it is created.

The er_label utility expects that intervals are specified with pairs of markers: a start time followed by a stop time. The utility ignores markers that occur out of sequence, such as a stop marker specified before any start marker, a start marker that follows a previous start marker with no intervening stop marker, or a stop marker that follows a previous stop marker with no intervening start marker.

You can assign labels to experiments by running the er_label command at the command line or by executing it in scripts. Once you have added labels to an experiment, you can use the labels for filtering. For example, you might filter the experiment to include or exclude the profiling events in the time periods defined by the label as described in Using Labels for Filtering.

er_label Command Syntax

The syntax of the er_label command is:

er_label -o experiment-name -n label-name -t {start|stop}[=time-specification] [-C comment

The options are defined as follows:

-o experiment-name is a required option that specifies the name of the experiment that you want to label. Only one experiment name can be specified, and experiment groups are not supported. The -o option can appear anywhere on the command line.

-n label-name is a required option that specifies the label name. The label must be alphanumeric and contain no spaces, but can be any length. If the label already exists in the experiment, the time markers and comments specified are added to the label. The -n option can appear anywhere on the command line.

-C comment is an optional comment about the label. The comment can be enclosed in quotation marks or not, depending on the requirements of your shell or script. You can use multiple -C options for a single label, and the comments will be concatenated with a space between them when the label is displayed. You can use multiple comments, for example, to provide information about each time interval in the label. You might want to include a delimiter such as a semicolon at the end of each comment when using multiple comments in a label.

-t start|stop =time-specification is a specification of the start or stop point used to define a time range within the experiment. If =time-specification is omitted, a marker for current time is created.

The time-specification can be specified in one of the following forms:

hh:mm:ss.uuu

Specifies the time relative to the beginning of the experiment where the start or stop marker should be placed. You must specify at least seconds, and can optionally specify hours, minutes, and subseconds.

The time values you specify are interpreted as follows:

nn

If you specify an integer (without colons), it is interpreted as seconds. If the value is greater than 60 the seconds are converted to mm:ss in the label. For example, -t start=120 places a start marker at 02:00 after the beginning of the experiment.

nn.nn

If you include a decimal of any precision, it is interpreted as a fraction of a second and saved to nanosecond precision. For example, -t start=120.3 places a start maker at 02:00.300 or 2 minutes and 300 nanoseconds after the beginning of the experiment.

nn:nn

If you specify the time using nn:nn format, it is interpreted as mm:ss, and if the value of mm is greater than 60, the time is converted to hh:mm:ss. The number you specify for ss must be between 0 and 59 or an error occurs. For example, -t start=90:30 places a start maker at 01:30:30 or 1 hour, 30 minutes, 30 seconds after the beginning of the experiment.

nn:nn:nn

If you specify the time using nn:nn:nn format, it is interpreted as hh:mm:ss. The numbers you specify for minutes and seconds must be between 0 and 59 or an error occurs. For example, -t stop=01:45:10 places a stop maker at 1 hour, 45 minutes and 10 seconds after the beginning of the experiment.

@

Specifies the current time to place a marker in the experiment at the moment when the er_label command is executed. The current time is set once in a single invocation of the command, so any additional markers that use the @ are set relative to that original timestamp value.

@+offset

Specifies a time after the current timestamp, where offset is a time that uses the same hh:mm:ss.uuu rules described above. This time format places a marker at the specified time after the original timestamp. For example, -t stop=@+180 places a stop marker at 3 minutes after the current time.

@-offset

Specifies a time before the current timestamp, where offset is a time that uses the same hh:mm:ss.uuu rules described above. This time format places a marker at the specified time before the original timestamp. For example, -t start=@-20:00 places a start marker at 20 minutes before the current time. If the experiment has not been running for at least 20 minutes, the marker is ignored.

You can use multiple -t specifications in a single er_label command, or multiple -t specifications in separate commands for the same label name, but they should occur in pairs of -t start and -t stop markers.

If the -t start or -t stop option is not followed by any time specification, =@ is assumed for the specification. You must include a time specification for one of the markers.

er_label Examples

Example 8-1 Defining a label with time markers relative to the beginning of the experiment

To define a label named snap in the experiment test.1.er that covers the part of a run from 15 seconds after the start of the experiment 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

Alternatively, you can specify the markers for the interval in separate commands:

% er_label -o test.1.er -n snap -t start=15
% er_label -o test.1.er -n snap -t stop=10:15

Example 8-2 Defining a label with time markers relative to the current time

To define a label named last5mins in the experiment test.1.er that covers the part of a run from 5 minutes ago to the current time:

% er_label -o test.1.er -n last5mins -t start=@-05:00 -t stop

Using er_label in Scripts

One use of er_label is to support profiling a server program that is being driven by a client as an independent process or processes. In this usage model, you start the server with the collect command to start creating an experiment on the server. Once the server is started and ready to accept requests from a client, you can run a client script that makes requests to drive the server and runs er_label to label the portions of the experiment where the client requests occur.

The following sample client script produces a time label in a test.1.er experiment for each request run against the server. Each of the five labels created marks off the time spent processing the named request.

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

The following sample script shows an alternative usage that produces a single label named all, which includes all the requests.

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 time specification follows -t stop in the second invocation of er_label, so it defaults to stop=@.

You can create more complex scripts, and run multiple scripts simultaneously on the same node or on different nodes. If the experiment is located in shared directory accessible by all the nodes, the scripts can mark intervals in the same experiment. The labels in each script can be the same or different.