zbxscr

README

Nxs-zbxscr

The better way to monitoring multiple instances of same service with Zabbix (e.g. on host system or/and Docker containers) on one node, it is a using the Zabbix autodiscovery mechanism. In this case at the Zabbix-agent side must be an application implements of following actions:

• Discovery: presents to the Zabbix-server information about the service instances at the node (in JSON format).
• Metric: after the discovery has been executed and metrics (the 'items' in Zabbix terms) from prototypes has been created for each instance of monitored service, the metrics starts to collect the data. Every metric check it's a request to the Zabbix-agent and call associated application (or script). An application in turn makes a request to an appropriate instance of the service for data obtaining.

If a monitored service represents a lot of metrics, each check will be made a request. It may spawn a redundant load and distort the data. To prevent this you can set up and use a cache to reduce interactions with the service.

This Go package provides the tools to write an applications for Zabbix-agent checks. This applications oriented to work with Zabbix autodiscovery.

The package includes following kinds:

• Instance
• Actions
• Exporter
• Cache

Instance

In common case application config file contains an array of instances for certain monitored service. Each instance block describes a way to interact with service instance for obtain a specified metric data.

Actions

To use this package you need to implement a functions for following actions:

• Discovery: function implements an instances discovery. This function must return the slice of elements to be sent to Zabbix server to automatically create items, triggers, and graphs for different entities.
• CheckConf: function implements a check config for syntax errors, instances duplicates, etc.
• CheckAlive: implements a check for an ability to obtain the data from specified instance
• Metric: implements a data obtaining for specified metric

Exporter

All interactions with monitored service aimed to obtain the data must be made through Exporter. If you are using a cache, this fucntion will be automatically called when instance cache does not exist or it's outdated.

Cache

If the service represents a lot of metrics, you can reduce number of interactions them by using cache. If this feature is used, first request for any metric generate a cache and all subsequent requests will be obtained from them. Further, first metric request after cache is outdated will be update them, and so on.

How to use

To develop the application using this package you must implement following functions:

• Discovery
• Metric
• Exporter
• CheckConf
• CheckAlive

See the tests for examples.

Documentation

Index

• Constants
• func DockerGetContainerIPs(c context.Context, name string) ([]string, error)
• type Cache
• type CheckAliveFunc
• type CheckConfFunc
• type DiscoveryFunc
• type ExporterFunc
• type MetricFunc
• type Settings
  • func (s *Settings) Action(action string, ctx interface{}) string
  • func (s *Settings) CacheGet(name string, ctx interface{}, forceUpdate bool) Cache
  • func (s *Settings) DebugGet() bool
  • func (s *Settings) DebugPrint(format string, a ...interface{})
  • func (s *Settings) DebugSet(toggle bool)

Constants

const (
	// MsgNotSupported - error message from zabbix agent
	MsgNotSupported = "ZBX_NOTSUPPORTED"

	// UserDefault is a default username wich set as UID
	UserDefault = "zabbix"

	// GroupDefault is a default group wich set as GID
	GroupDefault = "zabbix"
)

Functions

func DockerGetContainerIPs

func DockerGetContainerIPs(c context.Context, name string) ([]string, error)

DockerGetContainerIPs gets the IPs for specified docker container `name` - is a regular expression for container search by name

Types

type Cache

type Cache struct {

	// This field indicates for ability to retrieve data from instance endpoint.
	// If true  - data successfully retrieved from from cache file (if it's actual) or exeporter without any errors.
	// If false - some errors occurs while processing data retrieve (from cache or exporter)
	InstanceAlive bool `yaml:"instance_alive"`

	// This field contains data was obtained from cache (if it's actual) or exporter.
	Data []byte `yaml:"data"`
}

Cache contains data cache

type CheckAliveFunc

type CheckAliveFunc func(s *Settings, ctx interface{}) bool

CheckAliveFunc defines the process to check alive for specified instance.

type CheckConfFunc

type CheckConfFunc func(s *Settings, ctx interface{}) error

CheckConfFunc defines the process to check config for syntax errors, instances duplicates, etc.

type DiscoveryFunc

type DiscoveryFunc func(s *Settings, ctx interface{}) (interface{}, error)

DiscoveryFunc defines the process to service discovery. This function must return the slice of elements to be sent to Zabbix server to automatically create items, triggers, and graphs for different entities.

type ExporterFunc

type ExporterFunc func(ctx interface{}) ([]byte, error)

ExporterFunc defines the process to obtain all the needed data from monitored service. Usually this function automatically called from cache process, when the cache data is outdated, or from `MetricFunc` when cache disabled.

type MetricFunc

type MetricFunc func(s *Settings, ctx interface{}) (string, error)

MetricFunc defines the process to obtain specified metric

type Settings

type Settings struct {

	// Directory path to save instances cache
	CacheRoot string

	// Cache TTL in seconds
	CacheTTL float64

	// Whether or not to check user and group of running application
	CheckGUIDDisable bool

	// User to SUID. Available only for root
	User string

	// Group to SGID. Available only for root
	Group string

	// See functions description above for details
	DiscoveryAction  DiscoveryFunc
	CheckConfAction  CheckConfFunc
	CheckAliveAction CheckAliveFunc
	MetricAction     MetricFunc
	Exporter         ExporterFunc
	// contains filtered or unexported fields
}

Settings is struct to store settings

func (*Settings) Action

func (s *Settings) Action(action string, ctx interface{}) string

Action is package entrypoint function

func (*Settings) CacheGet

func (s *Settings) CacheGet(name string, ctx interface{}, forceUpdate bool) Cache

CacheGet retrieves data either from cache file if it's actual, or from exporter if cache rotted (in this case cache will be updated) If cache processing fails by any reasons, `InstanceAlive` field will be set to false. If `forceUpdate` argument is true, cache will be force updated.

func (*Settings) DebugGet

func (s *Settings) DebugGet() bool

DebugGet returns current debug toggle

func (*Settings) DebugPrint

func (s *Settings) DebugPrint(format string, a ...interface{})

DebugPrint prints the message if debug toggle true

func (*Settings) DebugSet

func (s *Settings) DebugSet(toggle bool)

DebugSet toggles the debug messages to stdout