Ottomata has submitted this change and it was merged.
Change subject: Consolidate docs on README
..
Consolidate docs on README
Bug: T145099
Change-Id: I6d7b7e31ae9c2b66fa6f16208dc43f0a194044d7
---
M README.md
M lib/rdkafka-statsd.js
2 files changed, 99 insertions(+), 28 deletions(-)
Approvals:
Ottomata: Looks good to me, approved
jenkins-bot: Verified
diff --git a/README.md b/README.md
index a016d69..0b71e59 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,100 @@
+# Documentation #
+
Utility module to flatten an object, filter keys and send wanted metrics to
statsd.
-By default metrics that include '-1' or 'toppars' are not sent.
+
+This package has an implicit dependency on an statsd client that implements
the function gauge.
+
+Callers can specify the keys they are interested on sending to statsd or use
+the filtered defaults which are these ones:
+
+```
+[
+// Broker stats
+'outbuf_cnt',
+'outbuf_msg_cnt',
+'waitresp_cnt',
+'waitresp_msg_cnt',
+'tx',
+'txbytes',
+'txerrs',
+'txretries',
+'req_timeouts',
+'rx',
+'rxbytes',
+'rxerrs',
+'rxcorriderrs',
+'rxpartial',
+'rtt',
+'throttle',
+
+// Topic partition stats
+'msgq_cnt',
+'msgq_bytes',
+'xmit_msgq_cnt',
+'xmit_msgq_bytes',
+'fetchq_cnt',
+'fetchq_size',
+'query_offset',
+'next_offset',
+'app_offset',
+'stored_offset',
+'committed_offset',
+'eof_offset',
+'lo_offset',
+'hi_offset',
+'consumer_lag',
+'txmsgs',
+'txbytes',
+'msgs',
+'rx_ver_drops'
+
+];
+```
+
+If using a filter function metrics that include '-1' or 'toppars' are not sent.
+
+
+## Usage ##
+
+
+### Example: Filter function
+
+
+```javascript
+
+var StatsD require('node-statsd'),
+client new StatsD({ host: 'statsd.eqiad.wmnet'}); // or metrics-reporter
+
+function myFilter(key) = {...}
+
+var rdkafkaStatsdCb = require('node-rdkafka-statsd')(client,{'filterFn':
myFilter});
+
+var kafka = require('node-rdkafka');
+
+var consumer = new kafka.KafkaConsumer({
+...
+'statistics.interval.ms': 3,
+});
+
+ // Flowing mode
+consumer.connect();
+consumer
+.on('ready', function() {
+consumer.consume('some-topic');
+})
+.on('event.stats', rdkafkaStatsdCb);
+
+```
+
+ Example: No filter function
+
+When no filter function is used all metrics are sent to statsd
+
+```javascript
+
+var StatsD require('node-statsd'),
+client new StatsD({ host: 'statsd.eqiad.wmnet'}); // or metrics-reporter
+
+var rdkafkaStatsdCb = require('node-rdkafka-statsd')(client,{'filterFn':
false});
+
+```
diff --git a/lib/rdkafka-statsd.js b/lib/rdkafka-statsd.js
index 28ab7ae..d036eae 100644
--- a/lib/rdkafka-statsd.js
+++ b/lib/rdkafka-statsd.js
@@ -2,36 +2,9 @@
* Parses an object structure, flattens it
* and sends the whitelisted metrics to statsd
* Depends implicitily on statsd client
- * Use like:
-
-var StatsD require('node-statsd'),
-client new StatsD({ host: 'statsd.eqiad.wmnet'}); // or metrics-reporter
-
-function myFilter(key) = {...}
-
-var rdkafkaStatsdCb = require('node-rdkafka-statsd')(client,{'filterFn':
myFilter});
-
-var kafka = require('node-rdkafka');
-var consumer = new kafka.KafkaConsumer({
-...
-'statistics.interval.ms': 3,
-});
-// Flowing mode
-consumer.connect();
-consumer
-.on('ready', function() {
-consumer.consume('some-topic');
-})
-.on('event.stats', rdkafka_statsd_cb);
- *
- *
- * If filterFn is set to false no whitelist is applied
- * metrics that include 'toppars' or '-1' are filtered by default
**/
'use strict';
-
-
const DOT = '.';
--
To view, visit https://gerrit.wikimedia.org/r/324277
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I6d7b7e31ae9c2b66fa6f16208dc43f0a194044d7
Gerrit-PatchSet: 4
Gerrit-Project: node-rdkafka-statsd
Gerrit-Branch: master
Gerrit-Owner: Nuria
Gerrit-Reviewer: Ottomata
Gerrit-Reviewer: jenkins-bot <>
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
