Allow specifying parent and/or follows_from of spans made by #[instrument]

[anp]

Feature Request

Crates

tracing & tracing-core, I think.

Motivation

It would be very useful to have support for #[instrument] on methods of a type which holds a span corresponding to its lifecycle.

Proposal

It's not (yet?) possible to inject fields into a struct from a derive, so we'll assume that a user has added a span field to the type whose lifecycle we're tracking:

struct ServiceConnection {
    // ...
    span: tracing::Span,
}

What I think we want is a way for that span to be used as the immediate span for method calls that are annotated with instrument:

impl ServiceConnection {
    #[instrument(parent = "self.span")]
    fn send_response(&self) { ... }
}

In this example, send_response's span would have the value's span as its parent. I think we'd also want a way to say that the method's span follows from the span which was active when the call was made, so that the method's span is connected both to the object and to the active tree of spans. Maybe that should be implicit or have a convenient shorthand?

Alternatives

We could express these semantics in terms of a trait, like

trait Spanned {
    fn span(&self) -> tracing::Span;
}

Then #[instrument] could have a shorthand for using self's span:

impl ServiceConnection {
    #[instrument(spanned)]
    fn send_response(&self) { ... }
}

Related

This relies on #651 to omit self by default from instrumentation. The core idea is to provide a less verbose way to instrument self.

[hawkw]

Now that we accept arbitrary expressions in #[instrument], I think it would be quite possible to add a parent argument, so you could write

struct MyGreatStruct {
    /* ... my great fields */
    span: tracing::Span,
}

impl MyGreatStruct {
    #[instrument(parent = &self.span), skip(self)]
    pub fn do_something_interesting(&self, /* ... cool method parameters ... */) {
         /* do something interesting and cool */
    }
}

I think adding this should be pretty simple. We would add a new custom keyword for parent, in this module:

tracing/tracing-attributes/src/lib.rs

Lines 776 to 783 in c9f8b6d

	mod kw {
	syn::custom_keyword!(fields);
	syn::custom_keyword!(skip);
	syn::custom_keyword!(level);
	syn::custom_keyword!(target);
	syn::custom_keyword!(name);
	syn::custom_keyword!(err);
	}

and then add logic for parsing the parent keyword in InstrumentArgs::parse:

tracing/tracing-attributes/src/lib.rs

Lines 553 to 558 in c9f8b6d

	} else if lookahead.peek(kw::target) {
	if args.target.is_some() {
	return Err(input.error("expected only a single `target` argument"));
	}
	let target = input.parse::<StrArg<kw::target>>()?.value;
	args.target = Some(target);

We would parse any expression after the parent keyword, and interpolate that into the generated span.

We could probably do something similar for a follows_from argument, except that this could take a list of multiple expressions (or be provided multiple times). We would then generate a Span::follows_from call for each argument after the span is created and before it's entered.

This relies on #651 to omit self by default from instrumentation. The core idea is to provide a less verbose way to instrument self.

I don't think this strictly relies on skipping self by default — it can also be used today with skip(self), although that introduces some boilerplate. I'd prefer to add this feature now, rather than waiting for 0.2 (which skipping self fields by default will require) — if there was a PR up for this change, we could merge and release it today.

[bnjjj]

I will implement this :) thanks for the explanation