Allow opt-in of arguments in `instrument` macro

[erikjohnston]

Feature Request

Allow specifying which arguments to be recorded in the instrument macro in an opt-in manner (rather than opt-out via skip(..)).

Crates

tracing

Motivation

Currently, the arguments which should be recorded with the instrument macro can only be specified by listing the ones to skip, as opposed to which ones to include.

This means that when adding a new argument one must be careful to consider whether it should be recorded. If it should not be recorded then one must remember to add it to the list of fields to skip. In practice, we've found that it is easy to overlook this.

The negative affects of getting this wrong include:

1. Potentially logging information that should not be logged.
2. Logging huge amounts of data if the parameter is a big data structure.

For us, the latter is the biggest problem as it tends not to be noticed until it causes an issue. As such, we're much rather new arguments were not automatically included, so that the "default" would be to not include new arguments.

Another minor issue is that annotating a function with #[instrument] then also suppresses unused argument warnings.

Proposal

Add an include(..) argument to the instrument macro, which specifies which of the function arguments to include (i.e. mirrors the skip(..) argument). When specified only the arguments listed in include are recorded.

I think this is equivalent to #instrument[skip_all, fields(x = ?x)], but specifying x = ?x is mildly annoying and the form #instrument[skip_all, fields(?x)] seems to work but isn't documented.

It would be an error to specify include(..) with skip or skip_all.

Alternatives

One can use the form #instrument[skip_all, fields(%x)] to get equivalent behaviour, though doesn't seem to be documented and is more verbose.