subscriber: Add a Layer type for composing subscribers

[hawkw]

Motivation

In many cases, it is valuable to compose multiple consumers for trace
events. However, certain aspects of tracing's design --- in
particular, that span IDs are assigned by the subscriber, and that a
single subscriber collects events from multiple threads --- make it
difficult to compose the Subscriber trait directly.

Solution

This branch introduces a new trait, Layer, in tracing-subscriber.
Layer represents the composable subset of the Subscriber
functionality --- it recieves notifications of spans and events, and can
filter callsites, but it does not assign IDs or manage reference counts,
instead being notified on span closure by the underlying subscriber. A
Layer can thus be wrapped around another subscriber to add additional
functionality. In addition, this branch adds functionality for composing
layers, and a filter module that provides Layer implementations for
simple filters.

Future Work

To have a complete story for multi-subscriber fanout, we will also want
to implement a performant concurrent span store, as I described in #157.
To better support the use of subscriber layers, may wish to consider
having a "registry" subscriber that implements only span storage, ID
generation, and lifecycle management, for composing layers on top of.
Finally, we should consider adding Layer implementations to other
crates that currently only expose Subscriber impls.

Refs: #135

Signed-off-by: Eliza Weisman [email protected]

[LucioFranco]

I think this looks pretty good as a first approach, Im gonna have to see how this fits in with my subscribers.

[hawkw]

7bd71e5 adds a Ctx type to the Layer module to allow exposing functions on the inner subscriber such as current_span to the layer. It's wrapped as a new type to restrict the layer from calling any arbitrary method on the inner subscriber, and to allow us to add new methods to it in the future without breaking changes.

[hawkw]

Some potential points to bikeshed (@davidbarsky, @jonhoo, @LucioFranco):

• What should the name of the trait implemented by layerable subscribers be? Is Layer the most descriptive, or should it be Consumer or Observer?
• Should the Layer::enter, Layer::exit, and Layer::event methods be on_enter, on_exit, and on_event, to make it clearer that they're just callbacks & disambiguate them from the Subscriber methods?

[hawkw]

I've marked this as ready for review, though I'd like to finish writing docs once we agree on the API.

[LucioFranco]

@hawkw, in this case, I actually like Observer I think its fits a lot better.

[hawkw]

@hawkw, in this case, I actually like Observer I think its fits a lot better.

Worth noting that a Layer can also be e.g. a filter, though.

[davidbarsky]

What should the name of the trait implemented by layerable subscribers be? Is Layer the most descriptive, or should it be Consumer or Observer?

Getting some déjà vu here! Layer seems to be the best fit, as Consumer implies a finality that Layer doesn't have. I'd be happy to be a swing vote if there's a clear split.

Should the Layer::enter, Layer::exit, and Layer::event methods be on_enter, on_exit, and on_event, to make it clearer that they're just callbacks & disambiguate them from the Subscriber methods?

I'm very strongly in favor of this change—this was one of the biggest bits of confusion to me, and the on_* naming scheme would communicate the intent much more clearly, I think.