[jaeger] unify all used tags, introduce builder pattern, additional… (#2473)

* feat/jaeger: unify all used tags, introduce builder pattern, additional candidate annotations

* chores

* fixes, incomplete fn rename

* another fix

* more fixes

* silly doctests

polkadot/node/jaeger/src/lib.rs

@@ -45,7 +45,9 @@
 //! ```
 
 use sp_core::traits::SpawnNamed;
-use polkadot_primitives::v1::{Hash, PoV, CandidateHash};
+use polkadot_primitives::v1::{CandidateHash, Hash, PoV, ValidatorIndex};
+use sc_network::PeerId;
+
 use parking_lot::RwLock;
 use std::{sync::Arc, result};
 
@@ -133,7 +135,7 @@ impl PerLeafSpan {
 	/// Takes the `leaf_span` that is created by the overseer per leaf and a name for a child span.
 	/// Both will be stored in this object, while the child span is implicitly accessible by using the
 	/// [`Deref`](std::ops::Deref) implementation.
-	pub fn new(leaf_span: Arc<JaegerSpan>, name: impl Into<String>) -> Self {
+	pub fn new(leaf_span: Arc<JaegerSpan>, name: &'static str) -> Self {
 		let span = leaf_span.child(name);
 
 		Self {
@@ -157,6 +159,83 @@ impl std::ops::Deref for PerLeafSpan {
 	}
 }
 
+
+/// A helper to annotate the stage with a numerical value
+/// to ease the life of the tooling team creating viable
+/// statistical metrics for which stage of the inclusion
+/// pipeline drops a significant amount of candidates,
+/// statistically speaking.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+#[non_exhaustive]
+pub enum Stage {
+	Backing = 1,
+	Availability = 2,
+	// TODO expand this
+}
+
+/// Builder pattern for children and root spans to unify
+/// information annotations.
+pub struct SpanBuilder {
+	span: JaegerSpan,
+}
+
+impl SpanBuilder {
+	/// Attach a peer id to the span.
+	#[inline(always)]
+	pub fn with_peer_id(mut self, peer: &PeerId) -> Self {
+		self.span.add_string_tag("peer-id", &peer.to_base58());
+		self
+	}
+	/// Attach a candidate hash to the span.
+	#[inline(always)]
+	pub fn with_candidate(mut self, candidate_hash: &CandidateHash) -> Self  {
+		self.span.add_string_tag("candidate-hash", &format!("{:?}", candidate_hash.0));
+		self
+	}
+	/// Attach a candidate stage.
+	/// Should always come with a `CandidateHash`.
+	#[inline(always)]
+	pub fn with_candidate_stage(mut self, stage: Stage) -> Self {
+		self.span.add_string_tag("candidate-stage", &format!("{}", stage as u8));
+		self
+	}
+
+	#[inline(always)]
+	pub fn with_validator_index(mut self, validator: ValidatorIndex) -> Self {
+		self.span.add_string_tag("validator-index", &validator.to_string());
+		self
+	}
+
+	#[inline(always)]
+	pub fn with_chunk_index(mut self, chunk_index: u32) -> Self {
+		self.span.add_string_tag("chunk-index", &format!("{}", chunk_index));
+		self
+	}
+
+	#[inline(always)]
+	pub fn with_relay_parent(mut self, relay_parent: &Hash) -> Self {
+		self.span.add_string_tag("relay-parent", &format!("{:?}", relay_parent));
+		self
+	}
+
+	#[inline(always)]
+	pub fn with_claimed_validator_index(mut self, claimed_validator_index: ValidatorIndex) -> Self {
+		self.span.add_string_tag(
+			"claimed-validator",
+			&claimed_validator_index.to_string(),
+		);
+		self
+	}
+
+	/// Complete construction.
+	#[inline(always)]
+	pub fn build(self) -> JaegerSpan {
+		self.span
+	}
+}
+
+
 /// A wrapper type for a span.
 ///
 /// Handles running with and without jaeger.
@@ -169,13 +248,34 @@ pub enum JaegerSpan {
 
 impl JaegerSpan {
 	/// Derive a child span from `self`.
-	pub fn child(&self, name: impl Into<String>) -> Self {
+	pub fn child(&self, name: &'static str) -> Self {
 		match self {
 			Self::Enabled(inner) => Self::Enabled(inner.child(name)),
 			Self::Disabled => Self::Disabled,
 		}
 	}
 
+	pub fn child_builder(&self, name: &'static str) -> SpanBuilder {
+		SpanBuilder {
+			span: self.child(name),
+		}
+	}
+
+	/// Derive a child span from `self` but add a candidate annotation.
+	/// A shortcut for
+	///
+	/// ```rust,no_run
+	/// # use polkadot_primitives::v1::CandidateHash;
+	/// # use polkadot_node_jaeger::candidate_hash_span;
+	/// # let hash = CandidateHash::default();
+	/// # let span = candidate_hash_span(&hash, "foo");
+	/// let _span = span.child_builder("name").with_candidate(&hash).build();
+	/// ```
+	#[inline(always)]
+	pub fn child_with_candidate(&self, name: &'static str, candidate_hash: &CandidateHash) -> Self {
+		self.child_builder(name).with_candidate(candidate_hash).build()
+	}
+
 	/// Add an additional tag to the span.
 	pub fn add_string_tag(&mut self, tag: &str, value: &str) {
 		match self {
@@ -215,8 +315,8 @@ impl From<mick_jaeger::Span> for JaegerSpan {
 	}
 }
 
-/// Shortcut for [`candidate_hash_span`] with the hash of the `Candidate` block.
-pub fn candidate_hash_span(candidate_hash: &CandidateHash, span_name: impl Into<String>) -> JaegerSpan {
+/// Shortcut for [`hash_span`] with the hash of the `Candidate` block.
+pub fn candidate_hash_span(candidate_hash: &CandidateHash, span_name: &'static str) -> JaegerSpan {
 	let mut span: JaegerSpan = INSTANCE.read_recursive()
 		.span(|| { candidate_hash.0 }, span_name).into();
 
@@ -226,7 +326,7 @@ pub fn candidate_hash_span(candidate_hash: &CandidateHash, span_name: impl Into<
 
 /// Shortcut for [`hash_span`] with the hash of the `PoV`.
 #[inline(always)]
-pub fn pov_span(pov: &PoV, span_name: impl Into<String>) -> JaegerSpan {
+pub fn pov_span(pov: &PoV, span_name: &'static str) -> JaegerSpan {
 	INSTANCE.read_recursive().span(|| { pov.hash() }, span_name).into()
 }
 
@@ -235,7 +335,7 @@ pub fn pov_span(pov: &PoV, span_name: impl Into<String>) -> JaegerSpan {
 ///
 /// This span automatically has the `relay-parent` tag set.
 #[inline(always)]
-pub fn hash_span(hash: &Hash, span_name: impl Into<String>) -> JaegerSpan {
+pub fn hash_span(hash: &Hash, span_name: &'static str) -> JaegerSpan {
 	let mut span: JaegerSpan = INSTANCE.read_recursive().span(|| { *hash }, span_name).into();
 	span.add_string_tag("relay-parent", &format!("{:?}", hash));
 	span
@@ -307,7 +407,7 @@ impl Jaeger {
 		Ok(())
 	}
 
-	fn span<F>(&self, lazy_hash: F, span_name: impl Into<String>) -> Option<mick_jaeger::Span>
+	fn span<F>(&self, lazy_hash: F, span_name: &'static str) -> Option<mick_jaeger::Span>
 	where
 		F: Fn() -> Hash,
 	{