Unify span traversal

[nightkr]

Feature Request

Crates

• tracing-subscriber

Motivation

Currently there are a way to traverse spans, that all behave subtly differently:

• Context::scope: implicit leaf span (based on the active span), ordered root-to-leaf, includes leaf span
• Span::from_root: explicit leaf span, ordered root-to-leaf, excludes leaf span
• Span::parents: explicit leaf span, ordered leaf-to-root, excludes leaf span
• while let iteration on Span::parent: explicit leaf span, ordered leaf-to-root, includes leaf span, not an Iterator

All of these are problematic in different ways:

• Excluding the leaf span leads to issues like JSON formatter: "spans" property does not contain the leaf #1408, where the leaf node is left out of formatting
• Inferring the leaf span makes the function unusable in Layer::on_event, and other cases where the current Span may not match what you're trying to format (see also: Look up span for event #1428)
• Manual iteration is harder to compose
• Root-to-leaf iteration is expensive (requires reifying the whole list and iterating over that), so it should be an explicit choice

Based on a Discord discussion starting at https://canary.discord.com/channels/500028886025895936/627649734592561152/852143116244221973

Proposal

• Add a new method SpanRef::scope(&self) that returns a leaf-to-root Iterator, including the specified leaf
• Add a new method Scope::from_root(self) (where Scope is the type returned by SpanRef::scope defined earlier) that returns a root-to-leaf Iterator that ends at the current leaf (in other words: it's essentially the same as Scope::collect::<Vec<_>>().into_iter().rev())
• Deprecate all existing iterators, since they can be replaced by the new unified mechanism:
  • Span::parents is equivalent to Span::scope().skip(1) (although the skip is typically a bug)
  • Span::from_root is equivalent to Span::scope().skip(1).from_root() (although the skip is typically a bug)
  • Context::scope is equivalent to Context::lookup_current().scope().from_root() (although the lookup_current is sometimes a bug, see also Look up span for event #1428)

Alternatives

• Keep existing API as-is, add Context::event_scope(&self, event: &Event) (to handle the same use-case as Look up span for event #1428)
  • Yet another special case
  • Less API churn
• Have SpanRef::scope reify the list immediately
  • Simpler implementation, since we can just reuse the standard library's
  • No need for separate types for going in each direction
  • Leaf-to-root iteration gets the same overhead as root-to-leaf iteration