stats: exposed and documented

README.md

@@ -277,6 +277,113 @@ class Node extends libp2p {
 [multiaddr]: https://github.com/multiformats/js-multiaddr
 [Connection]: https://github.com/libp2p/interface-connection
 
+-------
+
+### Switch Stats API
+
+##### `libp2p.stats.emit('update')`
+
+Every time any stat value changes, this object emits an `update` event.
+
+#### Global stats
+
+##### `libp2p.stats.global.snapshot`
+
+Should return a stats snapshot, which is an object containing the following keys and respective values:
+
+- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
+- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
+
+##### `libp2p.stats.global.movingAverages`
+
+Returns an object containing the following keys:
+
+- dataSent
+- dataReceived
+
+Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` miliseconds).
+
+Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
+
+#### Per-transport stats
+
+##### `libp2p.stats.transports()`
+
+Returns an array containing the tags (string) for each observed transport.
+
+##### `libp2p.stats.forTransport(transportTag).snapshot`
+
+Should return a stats snapshot, which is an object containing the following keys and respective values:
+
+- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
+- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
+
+##### `libp2p.stats.forTransport(transportTag).movingAverages`
+
+Returns an object containing the following keys:
+
+ dataSent
+ dataReceived
+
+Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` miliseconds).
+
+Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
+
+#### Per-protocol stats
+
+##### `libp2p.stats.protocols()`
+
+Returns an array containing the tags (string) for each observed protocol.
+
+##### `libp2p.stats.forProtocol(protocolTag).snapshot`
+
+Should return a stats snapshot, which is an object containing the following keys and respective values:
+
+- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
+- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
+
+
+##### `libp2p.stats.forProtocol(protocolTag).movingAverages`
+
+Returns an object containing the following keys:
+
+- dataSent
+- dataReceived
+
+Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` miliseconds).
+
+Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
+
+#### Per-peer stats
+
+##### `libp2p.stats.peers()`
+
+Returns an array containing the peerIDs (B58-encoded string) for each observed peer.
+
+##### `libp2p.stats.forPeer(peerId:String).snapshot`
+
+Should return a stats snapshot, which is an object containing the following keys and respective values:
+
+- dataSent: amount of bytes sent, [Big](https://github.com/MikeMcl/big.js#readme) number
+- dataReceived: amount of bytes received, [Big](https://github.com/MikeMcl/big.js#readme) number
+
+
+##### `libp2p.stats.forPeer(peerId:String).movingAverages`
+
+Returns an object containing the following keys:
+
+- dataSent
+- dataReceived
+
+Each one of them contains an object that has a key for each interval (`60000`, `300000` and `900000` miliseconds).
+
+Each one of these values is [an exponential moving-average instance](https://github.com/pgte/moving-average#readme).
+
+#### Stats update interval
+
+Stats are not updated in real-time. Instead, measurements are buffered and stats are updated at an interval. The maximum interval can be defined through the `Switch` constructor option `stats.computeThrottleTimeout`, defined in miliseconds.
+
+
 ## Development
 
 **Clone and install dependencies:**

src/index.js

@@ -34,7 +34,8 @@ class Node extends EventEmitter {
 
     this._isStarted = false
 
-    this.switch = new Switch(this.peerInfo, this.peerBook)
+    this.switch = new Switch(this.peerInfo, this.peerBook, _options.switch)
+    this.stats = this.switch.stats
 
     // Attach stream multiplexers
     if (this.modules.connection && this.modules.connection.muxer) {

test/node.js

@@ -9,3 +9,4 @@ require('./peer-routing.node')
 require('./content-routing.node')
 require('./circuit-relay.node')
 require('./multiaddr-trim')
+require('./stats')

test/stats.js

@@ -0,0 +1,24 @@
+/* eslint-env mocha */
+'use strict'
+
+const chai = require('chai')
+chai.use(require('dirty-chai'))
+const expect = chai.expect
+
+const createNode = require('./utils/node').createNode
+
+describe('libp2p', (done) => {
+  it('has stats', () => {
+    createNode('/ip4/127.0.0.1/tcp/0', {
+      mdns: false,
+      dht: true
+    }, (err, node) => {
+      expect(err).to.not.exist()
+      node.start((err) => {
+        expect(err).to.not.exist()
+        expect(node.stats).to.exist()
+        node.stop(done)
+      })
+    })
+  })
+})