Go to main content

Oracle® Solaris 11.4 DTrace (Dynamic Tracing) Guide

Exit Print View

Updated: September 2020
 
 

Processing Aggregation Data in DTrace

Aggregations have two sets of records: the key (or keys) and the value corresponding to the key (or keys). The following example shows a sample dtrace_aggdesc_t structure.

typedef struct dtrace_aggdesc {
        DTRACE_PTR(char, dtagd_name);           /* not filled in by kernel */
        dtrace_aggvarid_t dtagd_varid;          /* not filled in by kernel */
        int dtagd_flags;                        /* not filled in by kernel */
        dtrace_aggid_t dtagd_id;                /* aggregation ID */
        dtrace_epid_t dtagd_epid;               /* enabled probe ID */
        uint32_t dtagd_size;                    /* size in bytes */
        int dtagd_nrecs;                        /* number of records */
        uint32_t dtagd_pad;                     /* explicit padding */
        dtrace_recdesc_t dtagd_rec[1];          /* record descriptions */
} dtrace_aggdesc_t;

The dtagd_nrecs member of this structure specifies the number of record descriptions in the dtagd_rec array. dtagd_rec[1] through dtagd_rec[dtagd_nrecs - 2] contains the record description for the keys. The dtagd_rec[0] does not contain a key. The final record in this array, dtagd_rec[dtagd_nrecs - 1], is the record description for the value. The values for these aggregations are stored as simple values. The formats for the different value types are as follows:

count()

dtrd_action == DTRACEAGG_COUNT

sum()

dtrd_action == DTRACEAGG_SUM

min()

dtrd_action == DTRACEAGG_MIN

max()

dtrd_action == DTRACEAGG_MAX

avg() Function

The value for the avg() action is stored as a two-element array of 64-bit values. The first element of this array is a count of the individual data points, and the second element is a sum of those data points.

avg() (dtrd_action == DTRACEAGG_AVG)

stddev() Function

The value for the stddev() action is stored as a four-element array of 64-bit values. As with avg(), the first two values are a count of the individual data points and a sum of those data points. The lower two values contain a 128-bit representation of the sum of the squares of the individual data points. The third element contains the higher 64 bits of the value, and the fourth element contains the lower 64 bits. Standard deviation can be calculated as the square root of the average of the squares minus the square of the average: sqrt(average(x**2) - average(x)**2).

stddev() (dtrd_action == DTRACEAGG_STDDDEV)

Figure 8  Data Format for the stdev() Action

image:Graphic shows data format for the stdev action

quantize() Function

quantize() (dtrd_action == DTRACEAGG_QUANTIZE)

The quantize() action stores unsigned 64-bit values in power-of-2 buckets, from -2^63 to 2^63. Thus, the data are stored as a 127-element array of unsigned 64-bit values, as shown in the following figure.

Figure 9  Data Format for the quantize() Action

image:Graphic shows data format for the quantize action

    This action provides the following macros:

  • DTRACE_QUANTIZE_NBUCKETS – Number of buckets

  • DTRACE_QUANTIZE_ZEROBUCKET – Index of the zero bucket

  • DTRACE_QUANTIZE_BUCKETVAL(bucket) – Value for the specified bucket

lquantize() Function

The lquantize() action stores unsigned 64-bit values in buckets similar to the quantize() action. However, the number and range of buckets is specified in the arguments to the lquantize() action. The arguments to the lquantize() action are:

  • Value of interest

  • Lower bound of the linear quantization

  • Upper bound of the linear quantization

  • Step value between levels

    The first 64 bits of the data encode the following values:

  • DTRACE_LQUANTIZE_BASE(x) – Lower bound

  • DTRACE_LQUANTIZE_LEVELS(x) – Number of steps between the lower and upper bounds

  • DTRACE_LQUANTIZE_STEPS(x) – Step value between levels

    The remaining values in the data are:

  • The underflow bucket, which is the count of values less than the lower bound

  • The buckets in the range of the linear quantization

  • The overflow bucket, which is the count of values greater than or equal to the upper bound

lquantize() (dtrd_action == DTRACEAGG_LQUANTIZE)

The following diagram shows the layout.

Figure 10  Data Format for the lquantize() Action

image:Graphic shows data format for the lquantize action

llquantize() Function

The llquantize() action stores unsigned 64-bit values in buckets similar to the lquantize() action. Because llquantize() presents a log-linear quantization, the arguments to llquantize() are different from those for lquantize(). The arguments to the llquantize() action are:

  • Value of interest

  • A factor – The base of the logarithm

  • Lower magnitude of the log-linear quantization, which is the first set of buckets that cover the values n * factor ^ lower magnitude

  • Upper magnitude of the log-linear quantization, which is the last set of buckets that cover the values n * factor ^ upper magnitude

  • Step value – Each magnitude contains this number of buckets

    The first 64-bit word in the data encodes the factor, low magnitude, high magnitude, and steps. Each is encoded as an unsigned 16-bit integer. You can extract these values of encoded data by using the following macros:

  • DTRACE_LLQUANTIZE_FACTOR(x)

  • DTRACE_LLQUANTIZE_LMAG(x)

  • DTRACE_LLQUANTIZE_HMAG(x)

  • DTRACE_LLQUANTIZE_STEPS(x)

    The remaining values in the data are:

  • The underflow bucket

  • Sets of buckets for each magnitude

  • Overflow data

The factor and the value of the steps determines the number of buckets at each level. If the magnitude is zero, there are only factor-1 buckets. If the magnitude is other zero, there are steps - steps/factor buckets per magnitude.

For example, if factor == 10 and steps == 20, there are 20 - 20/10 == 18 buckets per magnitude. However, if the magnitude is 0, there are 10 - 1 == 9 buckets: 1x10^0 through 9x10^0.

llquantize() (dtrd_action == DTRACEAGG_LLQUANTIZE)

Figure 11  Data Format for the llquantize() Action

image:Graphic shows data format for the llquantize action