summaryrefslogtreecommitdiffstats
path: root/collectors/python.d.plugin/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--collectors/python.d.plugin/README.md89
1 files changed, 49 insertions, 40 deletions
diff --git a/collectors/python.d.plugin/README.md b/collectors/python.d.plugin/README.md
index 32437c6db..d0074a124 100644
--- a/collectors/python.d.plugin/README.md
+++ b/collectors/python.d.plugin/README.md
@@ -1,13 +1,13 @@
# python.d.plugin
-`python.d.plugin` is a netdata external plugin. It is an **orchestrator** for data collection modules written in `python`.
+`python.d.plugin` is a Netdata external plugin. It is an **orchestrator** for data collection modules written in `python`.
-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
+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
## Disclaimer
@@ -17,7 +17,7 @@ Module configurations are written in YAML and **pyYAML is required**.
Every configuration file must have one of two formats:
-- Configuration for only one job:
+- Configuration for only one job:
```yaml
update_every : 2 # update frequency
@@ -27,7 +27,7 @@ other_var1 : bla # variables passed to module
other_var2 : alb
```
-- Configuration for many jobs (ex. mysql):
+- Configuration for many jobs (ex. mysql):
```yaml
# module defaults:
@@ -51,6 +51,7 @@ other_job:
# become user netdata
sudo su -s /bin/bash netdata
```
+
Depending on where Netdata was installed, execute one of the following commands to trace the execution of a python module:
```
@@ -58,16 +59,18 @@ Depending on where Netdata was installed, execute one of the following commands
/opt/netdata/usr/libexec/netdata/plugins.d/python.d.plugin <module> debug trace
/usr/libexec/netdata/plugins.d/python.d.plugin <module> debug trace
```
-Where `[module]` is the directory name under https://github.com/netdata/netdata/tree/master/collectors/python.d.plugin
+
+Where `[module]` is the directory name under <https://github.com/netdata/netdata/tree/master/collectors/python.d.plugin>
## How to write a new module
Writing new python module is simple. You just need to remember to include 5 major things:
-- **ORDER** global list
-- **CHART** global dictionary
-- **Service** class
-- **_get_data** method
-- all code needs to be compatible with Python 2 (**≥ 2.7**) *and* 3 (**≥ 3.1**)
+
+- **ORDER** global list
+- **CHART** global dictionary
+- **Service** class
+- **\_get_data** method
+- all code needs to be compatible with Python 2 (**≥ 2.7**) *and* 3 (**≥ 3.1**)
If you plan to submit the module in a PR, make sure and go through the [PR checklist for new modules](#pull-request-checklist-for-python-plugins) beforehand to make sure you have updated all the files you need to.
@@ -76,11 +79,13 @@ For a quick start, you can look at the [example plugin](example/example.chart.py
### Global variables `ORDER` and `CHART`
`ORDER` list should contain the order of chart ids. Example:
+
```py
ORDER = ['first_chart', 'second_chart', 'third_chart']
```
`CHART` dictionary is a little bit trickier. It should contain the chart definition in following format:
+
```py
CHART = {
id: {
@@ -97,15 +102,16 @@ Parameters like `priority` and `update_every` are handled by `python.d.plugin`.
Every module needs to implement its own `Service` class. This class should inherit from one of the framework classes:
-- `SimpleService`
-- `UrlService`
-- `SocketService`
-- `LogService`
-- `ExecutableService`
+- `SimpleService`
+- `UrlService`
+- `SocketService`
+- `LogService`
+- `ExecutableService`
Also it needs to invoke the parent class constructor in a specific way as well as assign global variables to class variables.
Simple example:
+
```py
from base import UrlService
class Service(UrlService):
@@ -120,6 +126,7 @@ class Service(UrlService):
This method should grab raw data from `_get_raw_data`, parse it, and return a dictionary where keys are unique dimension names or `None` if no data is collected.
Example:
+
```py
def _get_data(self):
try:
@@ -129,12 +136,12 @@ def _get_data(self):
return None
```
-More about framework classes
-============================
+# More about framework classes
Every framework class has some user-configurable variables which are specific to this particular class. Those variables should have default values initialized in the child class constructor.
If module needs some additional user-configurable variable, it can be accessed from the `self.configuration` list and assigned in constructor or custom `check` method. Example:
+
```py
def __init__(self, configuration=None, name=None):
UrlService.__init__(self, configuration=configuration, name=name)
@@ -153,11 +160,12 @@ _This is last resort class, if a new module cannot be written by using other fra
_Example: `ceph`, `sensors`_
It is the lowest-level class which implements most of module logic, like:
-- threading
-- handling run times
-- chart formatting
-- logging
-- chart creation and updating
+
+- threading
+- handling run times
+- chart formatting
+- logging
+- chart creation and updating
### `LogService`
@@ -174,11 +182,12 @@ _Examples: `exim`, `postfix`_
_Variable from config file_: `command`.
This allows to execute a shell command in a secure way. It will check for invalid characters in `command` variable and won't proceed if there is one of:
-- '&'
-- '|'
-- ';'
-- '>'
-- '<'
+
+- '&'
+- '|'
+- ';'
+- '>'
+- '\<'
For additional security it uses python `subprocess.Popen` (without `shell=True` option) to execute command. Command can be specified with absolute or relative name. When using relative name, it will try to find `command` in `PATH` environment variable as well as in `/sbin` and `/usr/sbin`.
@@ -214,12 +223,12 @@ This is a generic checklist for submitting a new Python plugin for Netdata. It
At minimum, to be buildable and testable, the PR needs to include:
-* The module itself, following proper naming conventions: `python.d/<module_dir>/<module_name>.chart.py`
-* A README.md file for the plugin under `python.d/<module_dir>`.
-* The configuration file for the module: `conf.d/python.d/<module_name>.conf`. Python config files are in YAML format, and should include comments describing what options are present. The instructions are also needed in the configuration section of the README.md
-* A basic configuration for the plugin in the appropriate global config file: `conf.d/python.d.conf`, which is also in YAML format. Either add a line that reads `# <module_name>: yes` if the module is to be enabled by default, or one that reads `<module_name>: no` if it is to be disabled by default.
-* A line for the plugin in `python.d/Makefile.am` under `dist_python_DATA`.
-* A line for the plugin configuration file in `conf.d/Makefile.am`, under `dist_pythonconfig_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.
+- The module itself, following proper naming conventions: `python.d/<module_dir>/<module_name>.chart.py`
+- A README.md file for the plugin under `python.d/<module_dir>`.
+- The configuration file for the module: `conf.d/python.d/<module_name>.conf`. Python config files are in YAML format, and should include comments describing what options are present. The instructions are also needed in the configuration section of the README.md
+- A basic configuration for the plugin in the appropriate global config file: `conf.d/python.d.conf`, which is also in YAML format. Either add a line that reads `# <module_name>: yes` if the module is to be enabled by default, or one that reads `<module_name>: no` if it is to be disabled by default.
+- A line for the plugin in `python.d/Makefile.am` under `dist_python_DATA`.
+- A line for the plugin configuration file in `conf.d/Makefile.am`, under `dist_pythonconfig_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.
-[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fcollectors%2Fpython.d.plugin%2FREADME&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]()
+[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fcollectors%2Fpython.d.plugin%2FREADME&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)