printa
() Function
The printa
() function is used to format the results of aggregations in a D program. The function is invoked using one of the two following 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 DTrace Aggregations. If the second form of the function is used, the dtrace
command 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, aggregate a count using the following D statements:
@a["hello", 123] = count(); @a["goodbye", 456] = count();
Add the D statement
printa(format-string, @a)
to a probe clause. Thedtrace
utility takes a snapshot of the aggregation data and produces output as if you had entered the following statements for each tuple defined in the aggregation.printf(format-string, "hello", 123); printf(format-string, "goodbye", 456);
-
Unlike
printf
(), the format string you use forprinta
() 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 yourprinta
() 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 theprinta
() format string. -
You can use the additional
@
format flag character, which is only valid when used withprinta
(), to include the aggregation result in the output. 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 following table lists the aggregation result types.
Table 6-1 Aggregation Result Types
Aggregation Result Type | Argument |
---|---|
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 the 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:::profile-997 { @a[caller] = count(); } END { printa("%@8u %a\n", @a); }
If you use dtrace
to execute this program, wait a few seconds, and press Control-C
, the following output is displayed:
# dtrace -s printa.d
^C
CPU ID FUNCTION:NAME
1 2 :END 1 0x1
1 ohci`ohci_handle_root_hub_status_change+0x148
1 specfs`spec_write+0xe0
1 0xff14f950
1 genunix`cyclic_softint+0x588
1 0xfef2280c
1 genunix`getf+0xdc
1 ufs`ufs_icheck+0x50
1 genunix`infpollinfo+0x80
1 genunix`kmem_log_enter+0x1e8
...