subscriber: provide a simpler 'init' function

[tokio-rs]

subscriber: provide a simpler 'init' function

[seanmonstar]

For example, if we can replace the code needed in the example app here, that'd be a win.

[hawkw]

+1, this would be nice, one of those lower-priority things that we should definitely do before we' call the crate ready to release. If anyone's interested in working on this, I imagine it would be an easy first issue to work on --- I'd be happy to answer any questions.

A couple thoughts on Sean's proposal:

• Inits a tracing registry and adds the layer.

We should probably return the registry with the layer, rather than setting it as the default...this would mean that there are a few more steps than just calling init, but I imagine that in most cases, people will also want to add logging etc. That could always be done with the current API, but since I imagine a majority of people would want to add additional layers, it seems like not allowing it would limit the usability of the shorthand init function.

Another option would be to take an Option<impl Layer<...>> or something, if we want the init function to also be responsible for setting up the tracing subscriber. That way, users could pass in any additional layers they want to add, and we could add them to the registry before initializing it. Note that this would allow adding multiple layers, because two Layers can be composed to make a new Layer. But, this might be more complex in some ways?

• Starts a new thread to run a single-threaded Tokio runtime.

Do we really want to run the server and aggregator in a separate runtime rather than just calling tokio::spawn on the current runtime? I guess this would allow the init function to be used outside of Tokio, but it seems less efficient to create a separate thread just to run the two console tasks..in particular we'd miss out on e.g. same-thread wakeup optimizations when an event occurs on the same thread as the aggregator task, because the channel would always be across threads. I don't know how much it matters... 🤷‍♀️

[hawkw]

Also, one lesson I've learnt from working on tracing-subscriber is that if you are going to provide both a more flexible API (e.g. a builder) and a single-function convenience API like init, it's very important for the convenience function to clearly document exactly what it does. I might go so far as to just paste the entire body of the init function into an example and say "Calling this function is equivalent to...".

That way, when people need to "graduate" from the convenience API and change one configuration, but keep the rest of the behavior the same, they know how to get all the previous behavior easily. This is especially important if the init function does things beyond just calling FooBuilder::default().init() or whatever, because the builder's defaults don't capture all the behavior (e.g., if the init API spawns a background runtime, we'll want to show people exactly how we do that in the docs, so that switching to the manual init API doesn't suddenly break their world)...

[seanmonstar]

Do we really want to run the server and aggregator in a separate runtime rather than just calling tokio::spawn on the current runtime?

If the application is using a different runtime, then we'd have to. We don't have to put it in another thread, but it also has the benefit of keeping any work the subscriber is doing off any main runtime, instead of competing. I realize that threads still compete in an OS, but at that level it doesn't have to rely on cooperation for a thread to not hog the whole execution time. 🤷