misc/metrics: Add auxiliary crate to record events as OpenMetrics

CHANGELOG.md

@@ -36,6 +36,7 @@
 
 ## Utilities
 
+- [`libp2p-metrics` CHANGELOG](misc/metrics/CHANGELOG.md)
 - [`multistream-select` CHANGELOG](misc/multistream-select/CHANGELOG.md)
 
 # `libp2p` facade crate
@@ -66,7 +67,9 @@
 
 - Re-export the `wasm-bindgen` feature from `parking_lot`, so
   `libp2p` users can opt-in to that crate's Wasm support. See [PR 2180].
-
+
+- Add `libp2p-metrics`.
+
 [PR 2180]: https://github.com/libp2p/rust-libp2p/pull/2180/
 
 ## Version 0.39.1 [2021-07-12]

Cargo.toml

@@ -36,13 +36,14 @@ deflate = ["libp2p-deflate"]
 dns-async-std = ["libp2p-dns", "libp2p-dns/async-std"]
 dns-tokio = ["libp2p-dns", "libp2p-dns/tokio"]
 floodsub = ["libp2p-floodsub"]
-identify = ["libp2p-identify"]
-kad = ["libp2p-kad"]
+identify = ["libp2p-identify", "libp2p-metrics/identify"]
+kad = ["libp2p-kad", "libp2p-metrics/kad"]
 gossipsub = ["libp2p-gossipsub"]
+metrics = ["libp2p-metrics"]
 mdns = ["libp2p-mdns"]
 mplex = ["libp2p-mplex"]
 noise = ["libp2p-noise"]
-ping = ["libp2p-ping"]
+ping = ["libp2p-ping", "libp2p-metrics/ping"]
 plaintext = ["libp2p-plaintext"]
 pnet = ["libp2p-pnet"]
 relay = ["libp2p-relay"]
@@ -70,6 +71,7 @@ libp2p-floodsub = { version = "0.31.0", path = "protocols/floodsub", optional =
 libp2p-gossipsub = { version = "0.33.0", path = "./protocols/gossipsub", optional = true }
 libp2p-identify = { version = "0.31.0", path = "protocols/identify", optional = true }
 libp2p-kad = { version = "0.32.0", path = "protocols/kad", optional = true }
+libp2p-metrics = { version = "0.1.0", path = "misc/metrics", optional = true }
 libp2p-mplex = { version = "0.30.0", path = "muxers/mplex", optional = true }
 libp2p-noise = { version = "0.33.0", path = "transports/noise", optional = true }
 libp2p-ping = { version = "0.31.0", path = "protocols/ping", optional = true }
@@ -104,6 +106,7 @@ tokio = { version = "1.0.1", features = ["io-util", "io-std", "macros", "rt", "r
 resolver = "2"
 members = [
     "core",
+    "misc/metrics",
     "misc/multistream-select",
     "misc/peer-id-generator",
     "muxers/mplex",

misc/metrics/CHANGELOG.md

@@ -0,0 +1,3 @@
+## Version 0.1.0 [unreleased]
+
+- Add initial version.

misc/metrics/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "libp2p-metrics"
+edition = "2018"
+description = "Metrics for libp2p"
+version = "0.1.0"
+authors = ["Max Inden <mail@max-inden.de>"]
+license = "MIT"
+repository = "https://github.com/libp2p/rust-libp2p"
+keywords = ["peer-to-peer", "libp2p", "networking"]
+categories = ["network-programming", "asynchronous"]
+
+[features]
+identify = ["libp2p-identify"]
+kad = ["libp2p-kad"]
+ping = ["libp2p-ping"]
+
+[dependencies]
+libp2p-core=  { version = "0.30.0", path = "../../core" }
+libp2p-identify =  { version = "0.31.0", path = "../../protocols/identify", optional = true }
+libp2p-kad =  { version = "0.32.0", path = "../../protocols/kad", optional = true }
+libp2p-ping =  { version = "0.31.0", path = "../../protocols/ping", optional = true }
+libp2p-swarm =  { version = "0.31.0", path = "../../swarm" }
+open-metrics-client = "0.12.0"
+
+[dev-dependencies]
+env_logger = "0.8.1"
+futures = "0.3.1"
+libp2p = { path = "../../", features = ["metrics"] }
+tide = "0.16"

misc/metrics/examples/metrics.rs

@@ -0,0 +1,115 @@
+// Copyright 2021 Protocol Labs.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+//! Example demonstrating `libp2p-metrics`.
+//!
+//! In one terminal run:
+//!
+//! ```
+//! cargo run --example metrics
+//! ```
+//!
+//! In a second terminal run:
+//!
+//! ```
+//! cargo run --example metrics -- <listen-addr-of-first-node>
+//! ```
+//!
+//! Where `<listen-addr-of-first-node>` is replaced by the listen address of the
+//! first node reported in the first terminal. Look for `NewListenAddr`.
+//!
+//! In a third terminal run:
+//!
+//! ```
+//! curl localhost:<metrics-port-of-first-or-second-node>/metrics
+//! ```
+//!
+//! Where `<metrics-port-of-first-or-second-node>` is replaced by the listen
+//! port of the metrics server of the first or the second node. Look for
+//! `tide::server Server listening on`.
+//!
+//! You should see a long list of metrics printed to the terminal. Check the
+//! `libp2p_ping` metrics, they should be `>0`.
+
+use futures::executor::block_on;
+use futures::stream::StreamExt;
+use libp2p::metrics::{Metrics, Recorder};
+use libp2p::ping::{Ping, PingConfig};
+use libp2p::swarm::SwarmEvent;
+use libp2p::{identity, PeerId, Swarm};
+use open_metrics_client::encoding::text::encode;
+use open_metrics_client::registry::Registry;
+use std::error::Error;
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    tide::log::start();
+
+    let local_key = identity::Keypair::generate_ed25519();
+    let local_peer_id = PeerId::from(local_key.public());
+    tide::log::info!("Local peer id: {:?}", local_peer_id);
+
+    let mut swarm = Swarm::new(
+        block_on(libp2p::development_transport(local_key))?,
+        Ping::new(PingConfig::new().with_keep_alive(true)),
+        local_peer_id,
+    );
+    swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;
+    if let Some(addr) = std::env::args().nth(1) {
+        let remote = addr.parse()?;
+        swarm.dial_addr(remote)?;
+        tide::log::info!("Dialed {}", addr)
+    }
+
+    let mut metric_registry = Registry::default();
+    let metrics = Metrics::new(&mut metric_registry);
+    thread::spawn(move || block_on(metrics_server(metric_registry)));
+
+    block_on(async {
+        loop {
+            match swarm.select_next_some().await {
+                SwarmEvent::Behaviour(ping_event) => {
+                    tide::log::info!("{:?}", ping_event);
+                    metrics.record(&ping_event);
+                }
+                swarm_event => {
+                    tide::log::info!("{:?}", swarm_event);
+                    metrics.record(&swarm_event);
+                }
+            }
+        }
+    })
+}
+
+pub async fn metrics_server(registry: Registry) -> std::result::Result<(), std::io::Error> {
+    let mut app = tide::with_state(Arc::new(Mutex::new(registry)));
+
+    app.at("/metrics")
+        .get(|req: tide::Request<Arc<Mutex<Registry>>>| async move {
+            let mut encoded = Vec::new();
+            encode(&mut encoded, &req.state().lock().unwrap()).unwrap();
+            Ok(String::from_utf8(encoded).unwrap())
+        });
+
+    app.listen("0.0.0.0:0").await?;
+
+    Ok(())
+}

misc/metrics/src/identify.rs

@@ -0,0 +1,122 @@
+// Copyright 2021 Protocol Labs.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+use open_metrics_client::metrics::counter::Counter;
+use open_metrics_client::metrics::histogram::{exponential_buckets, Histogram};
+use open_metrics_client::registry::Registry;
+use std::iter;
+
+pub struct Metrics {
+    error: Counter,
+    pushed: Counter,
+    received: Counter,
+    received_info_listen_addrs: Histogram,
+    received_info_protocols: Histogram,
+    sent: Counter,
+}
+
+impl Metrics {
+    pub fn new(registry: &mut Registry) -> Self {
+        let sub_registry = registry.sub_registry_with_prefix("identify");
+
+        let error = Counter::default();
+        sub_registry.register(
+            "errors",
+            "Number of errors while attempting to identify the remote",
+            Box::new(error.clone()),
+        );
+
+        let pushed = Counter::default();
+        sub_registry.register(
+            "pushed",
+            "Number of times identification information of the local node has \
+             been actively pushed to a peer.",
+            Box::new(pushed.clone()),
+        );
+
+        let received = Counter::default();
+        sub_registry.register(
+            "received",
+            "Number of times identification information has been received from \
+             a peer",
+            Box::new(received.clone()),
+        );
+
+        let received_info_listen_addrs =
+            Histogram::new(iter::once(0.0).chain(exponential_buckets(1.0, 2.0, 9)));
+        sub_registry.register(
+            "received_info_listen_addrs",
+            "Number of listen addresses for remote peer received in \
+             identification information",
+            Box::new(received_info_listen_addrs.clone()),
+        );
+
+        let received_info_protocols =
+            Histogram::new(iter::once(0.0).chain(exponential_buckets(1.0, 2.0, 9)));
+        sub_registry.register(
+            "received_info_protocols",
+            "Number of protocols supported by the remote peer received in \
+             identification information",
+            Box::new(received_info_protocols.clone()),
+        );
+
+        let sent = Counter::default();
+        sub_registry.register(
+            "sent",
+            "Number of times identification information of the local node has \
+             been sent to a peer in response to an identification request",
+            Box::new(sent.clone()),
+        );
+
+        Self {
+            error,
+            pushed,
+            received,
+            received_info_listen_addrs,
+            received_info_protocols,
+            sent,
+        }
+    }
+}
+
+impl super::Recorder<libp2p_identify::IdentifyEvent> for super::Metrics {
+    fn record(&self, event: &libp2p_identify::IdentifyEvent) {
+        match event {
+            libp2p_identify::IdentifyEvent::Error { .. } => {
+                self.identify.error.inc();
+            }
+            libp2p_identify::IdentifyEvent::Pushed { .. } => {
+                self.identify.pushed.inc();
+            }
+            libp2p_identify::IdentifyEvent::Received { info, .. } => {
+                self.identify.received.inc();
+                self.identify
+                    .received_info_protocols
+                    .observe(info.protocols.len() as f64);
+                self.identify
+                    .received_info_listen_addrs
+                    .observe(info.listen_addrs.len() as f64);
+            }
+            libp2p_identify::IdentifyEvent::Sent { .. } => {
+                self.identify.sent.inc();
+            }
+        }
+    }
+}