6.2 printa

The printa function allows you to format the results of aggregations in a D program. The function is invoked using one of two forms:

printa(@aggregation-name); 
printa(format-string, @aggregation-name);

If the first form of the function is used, the dtrace command takes a consistent snapshot of the aggregation data and produces output equivalent to the default output format used for aggregations, described in Chapter 3, Aggregations. If the second form of the function is used, dtrace takes a consistent snapshot of the aggregation data and produces output according to the conversions specified in the format string, according to the following rules:

The format conversions must match the tuple signature used to create the aggregation. Each tuple element may only appear once. For example, if you aggregate a count using the following D statements:
```
@a["hello", 123] = count(); 
@a["goodbye", 456] = count();
```
and then add the D statement printa(format-string, @a) to a probe clause, dtrace takes a snapshot of the aggregation data and produces output as if you had entered these statements:
```
printf(format-string, "hello", 123); 
printf(format-string, "goodbye", 456);
```
and so on for each tuple defined in the aggregation.
Unlike printf, the format string you use for printa need not include all elements of the tuple. That is, you can have a tuple of length 3 and only one format conversion. Therefore, you can omit any tuple keys from your printa output by changing your aggregation declaration to move the keys you want to omit to the end of the tuple and then omit corresponding conversion specifiers for them in the printa format string.
The aggregation result can be included in the output by using the additional @ format flag character, which is only valid when used with printa. The @ flag can be combined with any appropriate format conversion specifier, and may appear more than once in a format string so that your tuple result can appear anywhere in the output and can appear more than once. The set of conversion specifiers that can be used with each aggregating function are implied by the aggregating function's result type. The aggregation result types are:

Aggregation	Result Type
`avg`	`uint64_t`
`count`	`uint64_t`
`lquantize`	`int64_t`
`max`	`uint64_t`
`min`	`uint64_t`
`quantize`	`int64_t`
`sum`	`uint64_t`

For example, to format the results of avg, you can apply the %d, %i, %o, %u, or %x format conversions. The quantize and lquantize functions format their results as an ASCII table rather than as a single value.

The following D program shows a complete example of printa, using the profile provider to sample the value of caller, and then formatting the results as a simple table:

profile:::tick-1000
{
  @a[caller] = count();
}

END
{
  printa("%@8u %a\n", @a);
}

If you use dtrace to execute this program, wait a few seconds, and then press Ctrl-C, you see output similar to the following example:

# dtrace -s printa.d 
dtrace: script 'printa.d' matched 2 probes
^C
CPU     ID                    FUNCTION:NAME
  0      2                             :END        8 0xffffffff8105f128
    1313 0xffffffff8110cb90
    6358 0xffffffff81052fb9
   36347 0xffffffffa03c92d7
...