3.2 Basic Aggregation Statement

DTrace stores the results of aggregating functions in objects called aggregations. In D, the syntax for an aggregation is as follows:

@name[ keys ] = aggfunc( args );

The aggregation name is a D identifier that is prefixed with the special character @. All aggregations that are named in your D programs are global variables. There are no thread-local or clause-local aggregations. The aggregation names are kept in an identifier namespace that is separate from other D global variables. If you reuse names, remember that a and @a are not the same variable. The special aggregation name @ can be used to name an anonymous aggregation in simple D programs. The D compiler treats this name as an alias for the aggregation name @_.

Aggregations are indexed with keys, where keys are a comma-separated list of D expressions, similar to the tuples of expressions used for associative arrays. Keys can also be actions with non-void return values, such as stack, func, sym, mod, ustack, uaddr, and usym.

The aggfunc is one of the DTrace aggregating functions, and args is a comma-separated list of arguments that is appropriate to that function. The DTrace aggregating functions are described in the following table. Most aggregating functions take just a single argument that represents the new datum.

Table 3.1 DTrace Aggregating Functions

Function Name

Arguments

Result

count

None

Number of times called.

sum

Scalar expression

Total value of the specified expressions.

avg

Scalar expression

Arithmetic average of the specified expressions.

min

Scalar expression

Smallest value among the specified expressions.

max

Scalar expression

Largest value among the specified expressions.

stddev

Scalar expression

Standard deviation of the specified expressions.

quantize

Scalar expression [, increment]

Power-of-two frequency distribution (histogram) of the values of the specified expressions. An optional increment (weight) can be specified.

lquantize

Scalar expression, lower bound, upper bound [, step value [, increment]]

Lnear frequency distribution of the values of the specified expressions, sized by the specified range.

Note that the default step value is 1.

llquantize

Scalar expression, base, lower exponent, upper exponent, number of steps per order of magnitude [, increment]

Log-linear frequency distribution. The logarithmic base is specified, along with lower and upper exponents and the number of steps per order of magnitude.