poller

README

poller

UniFi Poller Core

This module ties the inputs together with the outputs.

Aggregates metrics on request. Provides CLI app and args parsing.

Ideal

This library has no notion of "UniFi" or controllers, or Influx, or Prometheus. This library simply provides an input interface and an output interface. Each interface uses an []any type, so any type of data can be used. That is to say, you could write input and output plugins that work with, say, Cisco gear, or any other network (or even non-network) data. The existing plugins should provide ample example of how to use this library, but at some point the godoc will improve.

Features

• Automatically unmarshal's plugin config structs from config file and/or env variables.
• Initializes all "imported" plugins on startup.
• Provides input plugins a Logger, requires an interface for Metrics and Events retrieval.
• Provides Output plugins an interface to retrieve Metrics and Events, and a Logger.
• Provides automatic aggregation of Metrics and Events from multiple sources.

Documentation

Overview

Package poller provides the CLI interface to setup unifi-poller.

Index

• Constants
• func DefaultConfFile() string
• func DefaultObjPath() string
• func NewInput(i *InputPlugin)
• func NewOutput(o *Output)
• type Collect
• type Config
• type Events
• type Filter
• type Flags
  • func (f *Flags) Parse(args []string)
• type Input
• type InputPlugin
• type Logger
• type Metrics
  • func AppendMetrics(existing *Metrics, m *Metrics) *Metrics
• type Output
• type OutputPlugin
• type Poller
• type UnifiPoller
  • func New() *UnifiPoller
  • func (u *UnifiPoller) DebugIO() error
  • func (u *UnifiPoller) Events(filter *Filter) (*Events, error)
  • func (u *UnifiPoller) InitializeInputs() error
  • func (u *UnifiPoller) InitializeOutputs() error
  • func (u *UnifiPoller) Inputs() (names []string)
  • func (u *UnifiPoller) LoadPlugins() error
  • func (u *UnifiPoller) LogDebugf(m string, v ...any)
  • func (u *UnifiPoller) LogErrorf(m string, v ...any)
  • func (u *UnifiPoller) Logf(m string, v ...any)
  • func (u *UnifiPoller) Metrics(filter *Filter) (*Metrics, error)
  • func (u *UnifiPoller) Outputs() (names []string)
  • func (u *UnifiPoller) ParseConfigs() error
  • func (u *UnifiPoller) Poller() Poller
  • func (u *UnifiPoller) PrintPasswordHash() (err error)
  • func (u *UnifiPoller) PrintRawMetrics() (err error)
  • func (u *UnifiPoller) Run() error
  • func (u *UnifiPoller) Start() error

Constants

const (
	// AppName is the name of the application.
	AppName = "unpoller"
	// ENVConfigPrefix is the prefix appended to an env variable tag name.
	ENVConfigPrefix = "UP"
)

Functions

func DefaultConfFile

func DefaultConfFile() string

DefaultConfFile is where to find config if --config is not provided.

func DefaultObjPath

func DefaultObjPath() string

DefaultObjPath is the path to look for shared object libraries (plugins).

func NewInput

func NewInput(i *InputPlugin)

NewInput creates a metric input. This should be called by input plugins init() functions.

func NewOutput

func NewOutput(o *Output)

NewOutput should be called by each output package's init function.

Types

type Collect

type Collect interface {
	Logger
	Metrics(*Filter) (*Metrics, error)
	Events(*Filter) (*Events, error)
	// These get used by the webserver output plugin.
	Poller() Poller
	Inputs() []string
	Outputs() []string
}

Collect is passed into output packages so they may collect metrics to output.

type Config

type Config struct {
	*Poller `json:"poller" toml:"poller" xml:"poller" yaml:"poller"`
}

Config represents the core library input data.

type Events

type Events struct {
	Logs []any
}

Events defines the type for log entries.

type Filter

type Filter struct {
	Type string
	Term string
	Name string
	Role string
	Kind string
	Path string
	Text string
	Unit int
	Pass bool
	Skip bool
	Time time.Time
	Dur  time.Duration
}

Filter is used for metrics filters. Many fields for lots of expansion.

type Flags

type Flags struct {
	ConfigFile string
	DumpJSON   string
	HashPW     string
	ShowVer    bool
	DebugIO    bool
	*pflag.FlagSet
}

Flags represents the CLI args available and their settings.

func (*Flags) Parse

func (f *Flags) Parse(args []string)

Parse turns CLI arguments into data structures. Called by Start() on startup.

type Input

type Input interface {
	Initialize(Logger) error           // Called once on startup to initialize the plugin.
	Metrics(*Filter) (*Metrics, error) // Called every time new metrics are requested.
	Events(*Filter) (*Events, error)   // This is new.
	RawMetrics(*Filter) ([]byte, error)
	DebugInput() (bool, error)
}

Input plugins must implement this interface.

type InputPlugin

type InputPlugin struct {
	Name   string
	Config any // Each config is passed into an unmarshaller later.
	Input
}

InputPlugin describes an input plugin's consumable interface.

type Logger

type Logger interface {
	Logf(m string, v ...any)
	LogErrorf(m string, v ...any)
	LogDebugf(m string, v ...any)
}

Logger is passed into input packages so they may write logs.

type Metrics

type Metrics struct {
	TS         time.Time
	Sites      []any
	Clients    []any
	SitesDPI   []any
	ClientsDPI []any
	Devices    []any
	RogueAPs   []any
}

Metrics is a type shared by the exporting and reporting packages.

func AppendMetrics

func AppendMetrics(existing *Metrics, m *Metrics) *Metrics

AppendMetrics combines the metrics from two sources.

type Output

type Output struct {
	Name   string
	Config any // Each config is passed into an unmarshaller later.
	OutputPlugin
}

Output defines the output data for a metric exporter like influx or prometheus. Output packages should call NewOutput with this struct in init().

type OutputPlugin

type OutputPlugin interface {
	Run(Collect) error
	Enabled() bool
	DebugOutput() (bool, error)
}

type Poller

type Poller struct {
	Plugins []string `json:"plugins" toml:"plugins" xml:"plugin" yaml:"plugins"`
	Debug   bool     `json:"debug" toml:"debug" xml:"debug,attr" yaml:"debug"`
	Quiet   bool     `json:"quiet" toml:"quiet" xml:"quiet,attr" yaml:"quiet"`
}

Poller is the global config values.

type UnifiPoller

type UnifiPoller struct {
	Flags *Flags
	*Config
}

UnifiPoller contains the application startup data, and auth info for UniFi & Influx.

func New

func New() *UnifiPoller

New returns a new poller struct.

func (*UnifiPoller) DebugIO

func (u *UnifiPoller) DebugIO() error

func (*UnifiPoller) Events

func (u *UnifiPoller) Events(filter *Filter) (*Events, error)

Events aggregates log messages (events) from one or more sources.

func (*UnifiPoller) InitializeInputs

func (u *UnifiPoller) InitializeInputs() error

InitializeInputs runs the passed-in initializer method for each input plugin.

func (*UnifiPoller) InitializeOutputs

func (u *UnifiPoller) InitializeOutputs() error

InitializeOutputs runs all the configured output plugins. If none exist, or they all exit an error is returned.

func (*UnifiPoller) Inputs

func (u *UnifiPoller) Inputs() (names []string)

Inputs allows output plugins to see the list of loaded input plugins.

func (*UnifiPoller) LoadPlugins

func (u *UnifiPoller) LoadPlugins() error

LoadPlugins reads-in dynamic shared libraries. Not used very often, if at all.

func (*UnifiPoller) LogDebugf

func (u *UnifiPoller) LogDebugf(m string, v ...any)

LogDebugf prints a debug log entry if debug is true and quite is false.

func (*UnifiPoller) LogErrorf

func (u *UnifiPoller) LogErrorf(m string, v ...any)

LogErrorf prints an error log entry.

func (*UnifiPoller) Logf

func (u *UnifiPoller) Logf(m string, v ...any)

Logf prints a log entry if quiet is false.

func (*UnifiPoller) Metrics

func (u *UnifiPoller) Metrics(filter *Filter) (*Metrics, error)

Metrics aggregates all the measurements from filtered inputs and returns them. Passing a null filter returns everything!

func (*UnifiPoller) Outputs

func (u *UnifiPoller) Outputs() (names []string)

Outputs allows other output plugins to see the list of loaded output plugins.

func (*UnifiPoller) ParseConfigs

func (u *UnifiPoller) ParseConfigs() error

ParseConfigs parses the poller config and the config for each registered output plugin.

func (*UnifiPoller) Poller

func (u *UnifiPoller) Poller() Poller

Poller returns the poller config.

func (*UnifiPoller) PrintPasswordHash

func (u *UnifiPoller) PrintPasswordHash() (err error)

PrintPasswordHash prints a bcrypt'd password. Useful for the web server.

func (*UnifiPoller) PrintRawMetrics

func (u *UnifiPoller) PrintRawMetrics() (err error)

PrintRawMetrics prints raw json from the UniFi Controller. This is currently tied into the -j CLI arg, and is probably not very useful outside that context.

func (*UnifiPoller) Run

func (u *UnifiPoller) Run() error

Run picks a mode and executes the associated functions. This will do one of three things: 1. Start the collector routine that polls unifi and reports to influx on an interval. (default) 2. Run the collector one time and report the metrics to influxdb. (lambda) 3. Start a web server and wait for Prometheus to poll the application for metrics.

func (*UnifiPoller) Start

func (u *UnifiPoller) Start() error

Start begins the application from a CLI. Parses cli flags, parses config file, parses env vars, sets up logging, then: - dumps a json payload OR - executes Run().