12.6.10 Aggregations

DTrace provides the following built-in functions for aggregating the data that individual probes gather.

Aggregating Function

Description

avg(scalar_expression)

Returns the arithmetic mean of the expressions that are specified as arguments.

count()

Returns the number of times that the function has been called.

lquantize(scalar_expression, lower_bound, upper_bound, step_interval)

Returns a linear frequency distribution of the expressions that are specified as arguments, scaled to the specified lower bound, upper bound, and step interval. Increments the value in the highest bucket that is smaller than the specified expression.

max(scalar_expression)

Returns the maximum value of the expressions that are specified as arguments.

min(scalar_expression)

Returns the minimum value of the expressions that are specified as arguments.

quantize(scalar_expression)

Returns a power-of-two frequency distribution of the expressions that are specified as arguments. Increments the value of the highest power-of-two bucket that is smaller than the specified expression.

stddev(scalar_expression)

Returns the standard deviation of the expressions that are specified as arguments.

sum(scalar_expression)

Returns the sum of the expressions that are specified as arguments.

DTrace indexes the results of an aggregation using a tuple expression similar to that used for an associative array:

@name[list_of_keys] = aggregating_function(args);

The name of the aggregation is prefixed with an @ character. All aggregations are global. If you do not specify a name, the aggregation is anonymous. The keys describe the data that the aggregating function is collecting.

For example, the following command counts the number of write() system calls invoked by processes until you type Ctrl-C.

# dtrace -n syscall::write:entry'{ @["write() calls"] = count(); }'
dtrace: description 'syscall:::' matched 1 probe
^C

  write() calls                                              9

The next example counts the number of both read() and write() system calls:

# dtrace -n syscall::write:entry,syscall::read:entry\
'{ @[strjoin(probefunc,"() calls")] = count(); }'
dtrace: description 'syscall::write:entry,syscall::read:entry' matched 2 probes
^C

  write() calls                                            150
  read() calls                                            1555
Note

If you specify the -q option to dtrace or #pragma D option quiet in a D program, DTrace suppresses the automatic printing of aggregations. In this case, you must use a printa() statement to display the information.