Telemetry per node (#7463)

substrate/client/telemetry/README.md

@@ -1,45 +1,21 @@
-Telemetry utilities.
+# sc-telemetry
 
-Calling `init_telemetry` registers a global `slog` logger using `slog_scope::set_global_logger`.
-After that, calling `slog_scope::with_logger` will return a logger that sends information to
-the telemetry endpoints. The `telemetry!` macro is a short-cut for calling
-`slog_scope::with_logger` followed with `slog_log!`.
+Substrate's client telemetry is a part of substrate that allows logging telemetry information
+with a [Polkadot telemetry](https://github.com/paritytech/substrate-telemetry).
 
-Note that you are supposed to only ever use `telemetry!` and not `slog_scope::with_logger` at
-the moment. Substrate may eventually be reworked to get proper `slog` support, including sending
-information to the telemetry.
+It works using Tokio's [tracing](https://github.com/tokio-rs/tracing/). The telemetry
+information uses tracing's logging to report the telemetry which is then retrieved by a
+tracing's `Layer`. This layer will then send the data through an asynchronous channel and to a
+background task called [`TelemetryWorker`] which will send the information to the telemetry
+server.
 
-The [`Telemetry`] struct implements `Stream` and must be polled regularly (or sent to a
-background thread/task) in order for the telemetry to properly function. Dropping the object
-will also deregister the global logger and replace it with a logger that discards messages.
-The `Stream` generates [`TelemetryEvent`]s.
+If multiple substrate nodes are running, it uses a tracing's `Span` to identify which substrate
+node is reporting the telemetry. Every task spawned using sc-service's `TaskManager`
+automatically inherit this span.
 
-> **Note**: Cloning the [`Telemetry`] and polling from multiple clones has an unspecified behaviour.
+Substrate's nodes initialize/register to the [`TelemetryWorker`] using a [`TelemetryHandle`].
+This handle can be cloned and passed around. It uses an asynchronous channel to communicate with
+the running [`TelemetryWorker`] dedicated to registration. Registering a telemetry can happen at
+any point in time during the execution.
 
-# Example
-
-```rust
-use futures::prelude::*;
-
-let telemetry = sc_telemetry::init_telemetry(sc_telemetry::TelemetryConfig {
-	endpoints: sc_telemetry::TelemetryEndpoints::new(vec![
-		// The `0` is the maximum verbosity level of messages to send to this endpoint.
-		("wss://example.com".into(), 0)
-	]).expect("Invalid URL or multiaddr provided"),
-	// Can be used to pass an external implementation of WebSockets.
-	wasm_external_transport: None,
-});
-
-// The `telemetry` object implements `Stream` and must be processed.
-std::thread::spawn(move || {
-	futures::executor::block_on(telemetry.for_each(|_| future::ready(())));
-});
-
-// Sends a message on the telemetry.
-sc_telemetry::telemetry!(sc_telemetry::SUBSTRATE_INFO; "test";
-	"foo" => "bar",
-)
-```
-
-
-License: GPL-3.0-or-later WITH Classpath-exception-2.0
+License: GPL-3.0-or-later WITH Classpath-exception-2.0