-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
restrcuture, remove old metrics format from readme, enhanced example
- Loading branch information
Showing
1 changed file
with
56 additions
and
35 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,65 +1,86 @@ | ||
| # Sematext Agent Framework for Node.js | ||
| - spm-agent is used in: [spm-agent-nodejs](https://github.com/sematext/spm-agent-nodejs), [spm-agent-mongodb](https://github.com/sematext/spm-agent-mongodb) and [sematext-agent-docker](https://github.com/sematext/sematext-agent-docker) | ||
| - Sematext: [https://sematext.com/cloud](https://sematext.com/cloud) (monitoring metrics, logs, alerting, etc.) | ||
| - Node.js monitoring: [https://sematext.com/integrations/nodejs-monitoring](http://sematext.com/spm/integrations/nodejs-monitoring.html) | ||
|
|
||
| A framework for monitoring agents. | ||
| Ship metrics to [Sematext Cloud](https://sematext.com/cloud) or InfluxDB. | ||
|
|
||
| ## Functionality | ||
|
|
||
| - Sender interface to Sematext backend receivers | ||
| - Buffering metrics to disk in case of network outages (using NeDB) | ||
| - Limit the file size of buffers | ||
| - Buffering metrics in case of network outages | ||
| - Reconnect after failures | ||
| - Logging functions | ||
| - Configuration handling | ||
| - Pluggable agents | ||
|
|
||
| ## Example to implement a monitoring agent: | ||
| ## Example to Implement a Monitoring Agent | ||
|
|
||
| ```js | ||
| Sematext Cloud supports the Influx Line Protocol for the metric ingestion. | ||
|
|
||
| var SpmAgent = require('spm-agent') | ||
| var client = new SpmAgent() | ||
| var testAgent = client.createAgent(new SpmAgent.Agent ({ | ||
| start: function (agent) { | ||
| // initialize your metrics collector ... | ||
| this.tid = setInterval(function () { | ||
| // get every 30 seconds some metrics | ||
| // SPM gets an array of metrics for a specific app | ||
| agent.addMetrics({name: 'test-app', value: [1, 2, 3]}) | ||
| }, client.config.collectionInterval) | ||
| } | ||
| })) | ||
| // monitor which values we added by "addMetrics" | ||
| testAgent.on ('metrics', console.log) | ||
| ``` | ||
| Agent modules must provide a `start` and `stop`function. | ||
|
|
||
| The function `agent.addMetrics(metric)` collects a metric, which is shipped in bulk requests via Influx Line Protocol to the metrics receiver. | ||
|
|
||
| ### Using InfluxDB format | ||
| All metric objects, must have the mandatory fields `measurement`, `tags` and `fields`: | ||
|
|
||
| Sematext Cloud supports the influx line protocol. | ||
| All metric objects, having the properties `measurement`, `tags` and `fields` are sent via the Influx Line Protocol. | ||
| - measurement - the name of the measurement e.g. 'process.memry' | ||
| - tags - key/value pairs, useful for filtering or aggregation of data | ||
| - fields - numeric fields with the measurement values | ||
|
|
||
| ```js | ||
|
|
||
| var SpmAgent = require('spm-agent') | ||
| var client = new SpmAgent() | ||
| var os = require('os') | ||
|
|
||
| // configure client, with non-defautl values | ||
| // or use the file ./.spmagentrc in YAML format | ||
| // the default configuration contains values for Sematext Cloud US | ||
| client.config.tokens.spm = process.env.MONITORING_TOKEN | ||
| client.config.influx = { | ||
| dbName: 'metrics', | ||
| // change receiver to Sematext Cloud EU | ||
| host: 'spm-receiver.eu.sematext.com', | ||
| port: 443, | ||
| protocol: 'https' | ||
| } | ||
|
|
||
| var testAgent = client.createAgent(new SpmAgent.Agent ({ | ||
| start: function (agent) { | ||
| // initialize your metrics collector ... | ||
| // Typically agents collect metrics periodically, every N seconds. The time between // two collection activities is the collectionInterval, specified in milliseconds. | ||
| this.tid = setInterval(function () { | ||
| // get every 30 seconds some metrics | ||
| // SPM gets an array of metrics for a specific app | ||
| agent.addMetrics({ | ||
| measurement: 'test-app', | ||
| tags: {role: 'frontend'}, | ||
| fields: {requestCount: 1}} | ||
| // get every N seconds some metrics | ||
| agent.addMetrics({ | ||
| measurement: 'process.memory', | ||
| tags: {role: 'frontend', 'os.host': os.hostname()}, | ||
| fields: {rss: process.memoryUsage().rss}} | ||
| ) | ||
| }, client.config.collectionInterval) | ||
| }, | ||
| stop: function () { | ||
| if (this.tid) { | ||
| cancelInterval(this.tid) | ||
| } | ||
| } | ||
| })) | ||
| // monitor which values we added by "addMetrics" | ||
| testAgent.on ('metrics', console.log) | ||
|
|
||
| // log collected metrics to console | ||
| // observe all metrics | ||
| testAgent.on('metrics', console.log) | ||
| // observe a specific metric using the measurment name | ||
| testAgent.on('process.memory', console.log) | ||
| ``` | ||
|
|
||
| Let us know about monitoring agents you need, maybe you like to contribute with your domain expertise! | ||
|
|
||
| ## Related Modules | ||
| Please check [spm-metrics-js](https://github.com/sematext/spm-metrics-js) to ship your application specific metrics to Sematext. | ||
| # Related Modules | ||
|
|
||
| - [Node.js Monitoring](http://sematext.com/spm/integrations/nodejs-monitoring.html) | ||
| - [spm-agent-nodejs](https://github.com/sematext/spm-agent-nodejs), | ||
| - [spm-agent-mongodb](https://github.com/sematext/spm-agent-mongodb), | ||
| - [sematext-agent-nginx](https://github.com/sematext/sematext-agent-nginx), | ||
| - [sematext-agent-httpd](https://github.com/sematext/sematext-agent-httpd) | ||
| - [Sematext Cloud](https://sematext.com/cloud) - one platform for metrics and logs | ||
|
|
||
|
|
||
|
|