summaryrefslogtreecommitdiffstats
path: root/collectors/node.d.plugin/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'collectors/node.d.plugin/README.md')
-rw-r--r--collectors/node.d.plugin/README.md236
1 files changed, 0 insertions, 236 deletions
diff --git a/collectors/node.d.plugin/README.md b/collectors/node.d.plugin/README.md
deleted file mode 100644
index 4c5f278bd..000000000
--- a/collectors/node.d.plugin/README.md
+++ /dev/null
@@ -1,236 +0,0 @@
-<!--
-title: "node.d.plugin"
-custom_edit_url: https://github.com/netdata/netdata/edit/master/collectors/node.d.plugin/README.md
--->
-
-# node.d.plugin
-
-`node.d.plugin` is a Netdata external plugin. It is an **orchestrator** for data collection modules written in `node.js`.
-
-1. It runs as an independent process `ps fax` shows it
-2. It is started and stopped automatically by Netdata
-3. It communicates with Netdata via a unidirectional pipe (sending data to the `netdata` daemon)
-4. Supports any number of data collection **modules**
-5. Allows each **module** to have one or more data collection **jobs**
-6. Each **job** is collecting one or more metrics from a single data source
-
-## Pull Request Checklist for Node.js Plugins
-
-This is a generic checklist for submitting a new Node.js plugin for Netdata. It is by no means comprehensive.
-
-At minimum, to be buildable and testable, the PR needs to include:
-
-- The module itself, following proper naming conventions: `node.d/<module_dir>/<module_name>.node.js`
-- A README.md file for the plugin.
-- The configuration file for the module
-- A basic configuration for the plugin in the appropriate global config file: `conf.d/node.d.conf`, which is also in JSON format. If the module should be enabled by default, add a section for it in the `modules` dictionary.
-- A line for the plugin in the appropriate `Makefile.am` file: `node.d/Makefile.am` under `dist_node_DATA`.
-- A line for the plugin configuration file in `conf.d/Makefile.am`: under `dist_nodeconfig_DATA`
-- Optionally, chart information in `web/dashboard_info.js`. This generally involves specifying a name and icon for the section, and may include descriptions for the section or individual charts.
-
-## Motivation
-
-Node.js is perfect for asynchronous operations. It is very fast and quite common (actually the whole web is based on it).
-Since data collection is not a CPU intensive task, node.js is an ideal solution for it.
-
-`node.d.plugin` is a Netdata plugin that provides an abstraction layer to allow easy and quick development of data
-collectors in node.js. It also manages all its data collectors (placed in `/usr/libexec/netdata/node.d`) using a single
-instance of node, thus lowering the memory footprint of data collection.
-
-Of course, there can be independent plugins written in node.js (placed in `/usr/libexec/netdata/plugins`).
-These will have to be developed using the guidelines of **[External Plugins](/collectors/plugins.d/README.md)**.
-
-To run `node.js` plugins you need to have `node` installed in your system.
-
-In some older systems, the package named `node` is not node.js. It is a terminal emulation program called `ax25-node`.
-In this case the node.js package may be referred as `nodejs`. Once you install `nodejs`, we suggest to link
-`/usr/bin/nodejs` to `/usr/bin/node`, so that typing `node` in your terminal, opens node.js.
-
-## configuring `node.d.plugin`
-
-`node.d.plugin` can work even without any configuration. Its default configuration file is
-`node.d.conf`. To edit it on your system, run `/etc/netdata/edit-config node.d.conf`.
-
-## configuring `node.d.plugin` modules
-
-`node.d.plugin` modules accept configuration in `JSON` format.
-
-Unfortunately, `JSON` files do not accept comments. So, the best way to describe them is to have markdown text files
-with instructions.
-
-`JSON` has a very strict formatting. If you get errors from Netdata at `/var/log/netdata/error.log` that a certain
-configuration file cannot be loaded, we suggest to verify it at <http://jsonlint.com/>.
-
-The files in this directory, provide usable examples for configuring each `node.d.plugin` module.
-
-## debugging modules written for node.d.plugin
-
-To test `node.d.plugin` modules, which are placed in `/usr/libexec/netdata/node.d`, you can run `node.d.plugin` by hand,
-like this:
-
-```sh
-# become user netdata
-sudo su -s /bin/sh netdata
-
-# run the plugin in debug mode
-/usr/libexec/netdata/plugins.d/node.d.plugin debug 1 X Y Z
-```
-
-`node.d.plugin` will run in `debug` mode (lots of debug info), with an update frequency of `1` second, evaluating only
-the collector scripts `X` (i.e. `/usr/libexec/netdata/node.d/X.node.js`), `Y` and `Z`.
-You can define zero or more modules. If none is defined, `node.d.plugin` will evaluate all modules available.
-
-Keep in mind that if your configs are not in `/etc/netdata`, you should do the following before running `node.d.plugin`:
-
-```sh
-export NETDATA_USER_CONFIG_DIR="/path/to/etc/netdata"
-```
-
----
-
-## developing `node.d.plugin` modules
-
-Your data collection module should be split in 3 parts:
-
-- a function to fetch the data from its source. `node.d.plugin` already can fetch data from web sources,
- so you don't need to do anything about it for http.
-
-- a function to process the fetched/manipulate the data fetched. This function will make a number of calls
- to create charts and dimensions and pass the collected values to Netdata.
- This is the only function you need to write for collecting http JSON data.
-
-- a `configure` and an `update` function, which take care of your module configuration and data refresh
- respectively. You can use the supplied ones.
-
-Your module will automatically be able to process any number of servers, with different settings (even different
-data collection frequencies). You will write just the work needed for one and `node.d.plugin` will do the rest.
-For each server you are going to fetch data from, you will have to create a `service` (more later).
-
-### writing the data collection module
-
-To provide a module called `mymodule`, you have create the file `/usr/libexec/netdata/node.d/mymodule.node.js`, with this structure:
-
-```js
-// the processor is needed only
-// if you need a custom processor
-// other than http
-netdata.processors.myprocessor = {
- name: 'myprocessor',
-
- process: function(service, callback) {
-
- /* do data collection here */
-
- callback(data);
- }
-};
-
-// this is the mymodule definition
-var mymodule = {
- processResponse: function(service, data) {
-
- /* send information to the Netdata server here */
-
- },
-
- configure: function(config) {
- var eligible_services = 0;
-
- if(typeof(config.servers) === 'undefined' || config.servers.length === 0) {
-
- /*
- * create a service using internal defaults;
- * this is used for auto-detecting the settings
- * if possible
- */
-
- netdata.service({
- name: 'a name for this service',
- update_every: this.update_every,
- module: this,
- processor: netdata.processors.myprocessor,
- // any other information your processor needs
- }).execute(this.processResponse);
-
- eligible_services++;
- }
- else {
-
- /*
- * create a service for each server in the
- * configuration file
- */
-
- var len = config.servers.length;
- while(len--) {
- var server = config.servers[len];
-
- netdata.service({
- name: server.name,
- update_every: server.update_every,
- module: this,
- processor: netdata.processors.myprocessor,
- // any other information your processor needs
- }).execute(this.processResponse);
-
- eligible_services++;
- }
- }
-
- return eligible_services;
- },
-
- update: function(service, callback) {
-
- /*
- * this function is called when each service
- * created by the configure function, needs to
- * collect updated values.
- *
- * You normally will not need to change it.
- */
-
- service.execute(function(service, data) {
- mymodule.processResponse(service, data);
- callback();
- });
- },
-};
-
-module.exports = mymodule;
-```
-
-#### configure(config)
-
-`configure(config)` is called just once, when `node.d.plugin` starts.
-The config file will contain the contents of `/etc/netdata/node.d/mymodule.conf`.
-This file should have the following format:
-
-```js
-{
- "enable_autodetect": false,
- "update_every": 5,
- "servers": [ { /* server 1 */ }, { /* server 2 */ } ]
-}
-```
-
-If the config file `/etc/netdata/node.d/mymodule.conf` does not give a `enable_autodetect` or `update_every`, these
-will be added by `node.d.plugin`. So you module will always have them.
-
-The configuration file `/etc/netdata/node.d/mymodule.conf` may contain whatever else is needed for `mymodule`.
-
-#### processResponse(data)
-
-`data` may be `null` or whatever the processor specified in the `service` returned.
-
-The `service` object defines a set of functions to allow you send information to the Netdata core about:
-
-1. Charts and dimension definitions
-2. Updated values, from the collected values
-
----
-
-_FIXME: document an operational node.d.plugin data collector - the best example is the
-[snmp collector](https://raw.githubusercontent.com/netdata/netdata/master/collectors/node.d.plugin/snmp/snmp.node.js)_
-
-