diff options
Diffstat (limited to 'collectors/python.d.plugin/README.md')
| -rw-r--r-- | collectors/python.d.plugin/README.md | 89 |
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. -[]() +[](<>) |