diff --git a/README.md b/README.md index 870021bb..d05669e4 100644 --- a/README.md +++ b/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:** diff --git a/src/index.js b/src/index.js index 624105eb..3498bab7 100644 --- a/src/index.js +++ b/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) { diff --git a/test/node.js b/test/node.js index 0ea47d11..84807201 100644 --- a/test/node.js +++ b/test/node.js @@ -9,3 +9,4 @@ require('./peer-routing.node') require('./content-routing.node') require('./circuit-relay.node') require('./multiaddr-trim') +require('./stats') diff --git a/test/stats.js b/test/stats.js new file mode 100644 index 00000000..7b16a8df --- /dev/null +++ b/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/0.0.0.0/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) + }) + }) + }) +})