github.com/netdata/go.d.plugin@v0.58.1/agent/README.md (about)

     1  # agent
     2  
     3  This library is a tool for writing [netdata](https://github.com/netdata/netdata) plugins.
     4  
     5  We strongly believe that custom plugins are very important, and they must be easy to write.
     6  
     7  
     8  Definitions:
     9   - orchestrator
    10   > plugin orchestrators are external plugins that do not collect any data by themselves. Instead, they support data collection modules written in the language of the orchestrator. Usually the orchestrator provides a higher level abstraction, making it ideal for writing new data collection modules with the minimum of code.
    11  
    12   - plugin
    13   > plugin is a set of data collection modules.
    14  
    15   - module
    16   > module is a data collector. It collects, processes and returns processed data to the orchestrator.
    17  
    18   - job
    19   > job is a module instance with specific settings.
    20  
    21  
    22  Package provides:
    23   - CLI parser
    24   - plugin orchestrator (loads configurations, creates and serves jobs)
    25  
    26  You are responsible only for __creating modules__.
    27  
    28  ## Custom plugin example
    29  
    30  [Yep! So easy!](https://github.com/netdata/go.d.plugin/blob/master/examples/simple/main.go)
    31  
    32  ## How to write a Module
    33  
    34  Module is responsible for **charts creating** and **data collecting**. Implement Module interface and that is it.
    35  
    36  ```go
    37  type Module interface {
    38  	// Init does initialization.
    39  	// If it returns false, the job will be disabled.
    40  	Init() bool
    41  
    42  	// Check is called after Init.
    43  	// If it returns false, the job will be disabled.
    44  	Check() bool
    45  
    46  	// Charts returns the chart definition.
    47  	// Make sure not to share returned instance.
    48  	Charts() *Charts
    49  
    50  	// Collect collects metrics.
    51  	Collect() map[string]int64
    52  
    53  	// SetLogger sets logger.
    54  	SetLogger(l *logger.Logger)
    55  
    56  	// Cleanup performs cleanup if needed.
    57  	Cleanup()
    58  }
    59  
    60  // Base is a helper struct. All modules should embed this struct.
    61  type Base struct {
    62  	*logger.Logger
    63  }
    64  
    65  // SetLogger sets logger.
    66  func (b *Base) SetLogger(l *logger.Logger) { b.Logger = l }
    67  
    68  ```
    69  
    70  ## How to write a Plugin
    71  
    72  Since plugin is a set of modules all you need is:
    73   - write module(s)
    74   - add module(s) to the plugins [registry](https://github.com/netdata/go.d.plugin/blob/master/plugin/module/registry.go)
    75   - start the plugin
    76  
    77  
    78  ## How to integrate your plugin into Netdata
    79  
    80  Three simple steps:
    81   - move the plugin to the `plugins.d` dir.
    82   - add plugin configuration file to the `etc/netdata/` dir.
    83   - add modules configuration files to the `etc/netdata/<DIR_NAME>/` dir.
    84  
    85  Congratulations!
    86  
    87  ## Configurations
    88  
    89  Configurations are written in [YAML](https://yaml.org/).
    90  
    91   - plugin configuration:
    92  
    93  ```yaml
    94  
    95  # Enable/disable the whole plugin.
    96  enabled: yes
    97  
    98  # Default enable/disable value for all modules.
    99  default_run: yes
   100  
   101  # Maximum number of used CPUs. Zero means no limit.
   102  max_procs: 0
   103  
   104  # Enable/disable specific plugin module
   105  modules:
   106  #  module_name1: yes
   107  #  module_name2: yes
   108  
   109  ```
   110  
   111   - module configuration
   112  
   113  ```yaml
   114  # [ GLOBAL ]
   115  update_every: 1
   116  autodetection_retry: 0
   117  
   118  # [ JOBS ]
   119  jobs:
   120    - name: job1
   121      param1: value1
   122      param2: value2
   123  
   124    - name: job2
   125      param1: value1
   126      param2: value2
   127  ```
   128  
   129  Plugin uses `yaml.Unmarshal` to add configuration parameters to the module. Please use `yaml` tags!
   130  
   131  ## Debug
   132  
   133  Plugin CLI:
   134  ```
   135  Usage:
   136    plugin [OPTIONS] [update every]
   137  
   138  Application Options:
   139    -d, --debug    debug mode
   140    -m, --modules= modules name (default: all)
   141    -c, --config=  config dir
   142  
   143  Help Options:
   144    -h, --help     Show this help message
   145  
   146  ```
   147  
   148  Specific module debug:
   149  ```
   150  # become user netdata
   151  sudo su -s /bin/bash netdata
   152  
   153  # run plugin in debug mode
   154  ./<plugin_name> -d -m <module_name>
   155  ```
   156  
   157  Change `<plugin_name>` to your plugin name and `<module_name>` to the module name you want to debug.