This option can be used to specify a format to use in DTrace output.
The following formats are supported:
- json
- xml
- html
- none (default DTrace output)
This is implemented using libxo and integrated into libdtrace. Client
code only works with the following API:
- dtrace_oformat_setup(dtrace_hdl_t *) -- to be called when output is
starting.
- dtrace_oformat_teardown(dtrace_hdl_t *) -- to be called when output
is finished
- dtrace_oformat(dtrace_hdl_t *) -- check if oformat is enabled.
- dtrace_set_outfp(FILE *) -- sets the output file for oformat.
- Ensure that oformat is correctly checked in the drop handler and
record processing callbacks.
This commit also adds tests for oformat which only really check that the
output generated is valid JSON and XML.
The format is as follows (JSON as example):
```
{
"dtrace": {
"probes": [
{
"timestamp": ...,
"cpu": ...,
"id": ...,
"provider": ...,
"module": ...,
"function": ...,
"name": ...,
"output": [
... (script specific)
]
}
]
}
}
```
or the XML/HTML equivalent.
Moreover, client code callbacks are always guaranteed to be called in
the "probes" array, including in the drop handler, so the caller may
wish to add its own data there. In this commit, dtrace(1) does not make
use of this feature.
oformat is intended as a supplementary mechanism to add machine-readable
output to DTrace and it is not intended to replace libdtrace as a
library that one can link against directly and process the data that
way. It aims to be a middle ground between manually parsing
pretty-printed output that dtrace(1) outputs and linking against
libdtrace in order to implement a new frontend.
Furthermore, streaming output should be possible but hasn't been tested
at this point. oformat guarantees that at any given point when a probe
fires and output is produced via a flush, it will be in the context of
the "probes" array, so adding "]}}" after the last received probe will
always produce valid JSON. Similarly, any incremental XML parser should
work.
There is an example [1] that can be viewed (written in Python 3) on how
one might use oformat. This file really isn't meant to be "good code" or
pretty, it is simply a quick and dirty script that demonstrates how one
might go about interfacing with the oformat output.
[1]: https://reviews.freebsd.org/P610
This is a first working version of the implementation and subject to change, but I believe that the main design goals are here. There is also a distinct lack of documentation currently on the entire format because I'm unsure as to where it should live. Perhaps its own man page is warranted in order to avoid polluting dtrace(1)?
Another design point which might be worth pondering is using the "probes" array for drops. Right now, all of the drops are formatted as a probe that doesn't exist ("dtrace:INTERNAL:INTERNAL:DROP") because this makes it easy to provide drop statistics while the probes are firing and still produce valid JSON/XML throughout the whole run.
The inspiration for this is taken from the CADETS project, however the implementation is different as it has different goals.