agent

README

agent

This library is a tool for writing netdata plugins.

We strongly believe that custom plugins are very important, and they must be easy to write.

Definitions:

• orchestrator

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.

• plugin

plugin is a set of data collection modules.

• module

module is a data collector. It collects, processes and returns processed data to the orchestrator.

• job

job is a module instance with specific settings.

Package provides:

• CLI parser
• plugin orchestrator (loads configurations, creates and serves jobs)

You are responsible only for creating modules.

Custom plugin example

Yep! So easy!

How to write a Module

Module is responsible for charts creating and data collecting. Implement Module interface and that is it.

type Module interface {
	// Init does initialization.
	// If it returns false, the job will be disabled.
	Init() bool

	// Check is called after Init.
	// If it returns false, the job will be disabled.
	Check() bool

	// Charts returns the chart definition.
	// Make sure not to share returned instance.
	Charts() *Charts

	// Collect collects metrics.
	Collect() map[string]int64

	// SetLogger sets logger.
	SetLogger(l *logger.Logger)

	// Cleanup performs cleanup if needed.
	Cleanup()
}

// Base is a helper struct. All modules should embed this struct.
type Base struct {
	*logger.Logger
}

// SetLogger sets logger.
func (b *Base) SetLogger(l *logger.Logger) { b.Logger = l }

How to write a Plugin

Since plugin is a set of modules all you need is:

• write module(s)
• add module(s) to the plugins registry
• start the plugin

How to integrate your plugin into Netdata

Three simple steps:

• move the plugin to the plugins.d dir.
• add plugin configuration file to the etc/netdata/ dir.
• add modules configuration files to the etc/netdata/<DIR_NAME>/ dir.

Congratulations!

Configurations

Configurations are written in YAML.

• plugin configuration:

# Enable/disable the whole plugin.
enabled: yes

# Default enable/disable value for all modules.
default_run: yes

# Maximum number of used CPUs. Zero means no limit.
max_procs: 0

# Enable/disable specific plugin module
modules:
#  module_name1: yes
#  module_name2: yes

• module configuration

# [ GLOBAL ]
update_every: 1
autodetection_retry: 0

# [ JOBS ]
jobs:
  - name: job1
    param1: value1
    param2: value2

  - name: job2
    param1: value1
    param2: value2

Plugin uses yaml.Unmarshal to add configuration parameters to the module. Please use yaml tags!

Debug

Plugin CLI:

Usage:
  plugin [OPTIONS] [update every]

Application Options:
  -d, --debug    debug mode
  -m, --modules= modules name (default: all)
  -c, --config=  config dir

Help Options:
  -h, --help     Show this help message

Specific module debug:

# become user netdata
sudo su -s /bin/bash netdata

# run plugin in debug mode
./<plugin_name> -d -m <module_name>

Change <plugin_name> to your plugin name and <module_name> to the module name you want to debug.

Documentation

Index

• type Agent
  • func New(cfg Config) *Agent
  • func (a *Agent) Run()
• type Config

Types

type Agent

type Agent struct {
	Name              string
	ConfDir           multipath.MultiPath
	ModulesConfDir    multipath.MultiPath
	ModulesSDConfPath []string
	StateFile         string
	LockDir           string
	RunModule         string
	MinUpdateEvery    int
	ModuleRegistry    module.Registry
	Out               io.Writer

	*logger.Logger
	// contains filtered or unexported fields
}

Agent represents orchestrator.

func New

func New(cfg Config) *Agent

New creates a new Agent.

func (*Agent) Run

func (a *Agent) Run()

Run starts the Agent.

type Config

type Config struct {
	Name              string
	ConfDir           []string
	ModulesConfDir    []string
	ModulesSDConfPath []string
	StateFile         string
	LockDir           string
	ModuleRegistry    module.Registry
	RunModule         string
	MinUpdateEvery    int
}

Config is an Agent configuration.