power

README

power

Power infrastructure health sampling and monitoring.

A Docker image is available on Docker Hub.

Example Docker Invocation

docker run -d --name=power-monitor --restart=always -e SOURCE=lcy-rack2n-ups,lcy-rack2s-ups -e COMMUNITY=tripplite -e INTERVAL=1m -e RECIPIENT=stathat:STATHATKEY scjalliance/power

Documentation

Index

• Constants
• Variables
• func IsNotSupported(err error) bool
• func RegisterRecipientType(parser RecipientParser, names ...string)
• type ErrorHandler
• type Recipient
  • func ParseRecipient(s string) (recipient Recipient, err error)
  • func ParseRecipients(s []string) (recipients []Recipient, err error)
• type RecipientParser
• type Source
  • func ParseSource(s string) (src Source, err error)
  • func ParseSources(s []string) (sources []Source, err error)
  • func (s Source) HostPort() string
  • func (s Source) String() (value string)
• type SourceHandler
• type Statistic
  • func ParseStatistic(s string) (stat Statistic, err error)
  • func ParseStatistics(s []string) (stats []Statistic, err error)
• type Value
  • func Query(ctx context.Context, source Source, stats ...Statistic) (results []Value, err error)
  • func (v Value) StatName() string
  • func (v Value) String() string

Constants

const (
	OutputSourceOther = iota + 1
	OutputSourceNone
	OutputSourceNormal
	OutputSourceBypass
	OutputSourceBattery
	OutputSourceBooster
	OutputSourceReducer
)

Output Source Enumeration

Variables

var (
	EstimatedMinutesRemaining = Statistic{
		Name:   "EstimatedMinutesRemaining",
		Unit:   "minutes",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.2.3.0")},
		Mapper: snmpvar.Ident,
	}
	EstimatedChargeRemaining = Statistic{
		Name:   "EstimatedChargeRemaining",
		Unit:   "%",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.2.4.0")},
		Mapper: snmpvar.Ident,
	}
	BatteryVoltage = Statistic{
		Name:   "BatteryVoltage",
		Unit:   "volts (DC)",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.2.5.0")},
		Mapper: snmpvar.Div(10),
	}
	BatteryTemperature = Statistic{
		Name:   "BatteryTemperature",
		Unit:   "°C",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.2.7.0")},
		Mapper: snmpvar.Ident,
	}
	InputVoltage = Statistic{
		Name:   "InputVoltage",
		Unit:   "volts",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.3.3.1.3.1")},
		Mapper: snmpvar.Ident,
	}
	InputCurrent = Statistic{
		Name:   "InputCurrent",
		Unit:   "volts",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.3.3.1.4.1")},
		Mapper: snmpvar.Ident,
	}
	OnBattery = Statistic{
		Name:   "OnBattery",
		Unit:   "yes/no",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.4.1.0")},
		Mapper: snmpvar.Match(OutputSourceBypass),
	}
	OutputVoltage = Statistic{
		Name:   "OutputVoltage",
		Unit:   "volts",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.4.4.1.2.1")},
		Mapper: snmpvar.Ident,
	}
	OutputCurrent = Statistic{
		Name:   "OutputCurrent",
		Unit:   "amps",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.4.4.1.3.1")},
		Mapper: snmpvar.Div(10),
	}
	OutputPower = Statistic{
		Name:   "OutputPower",
		Unit:   "watts",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.4.4.1.4.1")},
		Mapper: snmpvar.Ident,
	}
	OutputPercentLoad = Statistic{
		Name:   "OutputPercentLoad",
		Unit:   "%",
		OID:    snmpgo.Oids{snmpgo.MustNewOid("1.3.6.1.2.1.33.1.4.4.1.5.1")},
		Mapper: snmpvar.Ident,
	}
)

Preconfigured power management statistics

var (
	ErrNoSuchInstance = errors.New("not supported (no such instance)")
	ErrNoSuchObject   = errors.New("not supported (no such object)")
)

SNMP errors

var (
	DefaultCommunity = "public"
	DefaultPort      = 161
	DefaultRetries   = uint(1)
)

Default source configuration

Functions

func IsNotSupported

func IsNotSupported(err error) bool

IsNotSupported returns true if the error indicates an unsupported SNMP object type.

func RegisterRecipientType

func RegisterRecipientType(parser RecipientParser, names ...string)

RegisterRecipientType registers the given recipient type for name.

Name is case insensitive.

Types

type ErrorHandler

type ErrorHandler interface {
	SendQueryError(i int, s Source, err error)
}

ErrorHandler is a recipient that handles query errors.

type Recipient

type Recipient interface {
	Send(Value)
}

Recipient is something to which a power management value can be sent.

func ParseRecipient

func ParseRecipient(s string) (recipient Recipient, err error)

ParseRecipient parses the given string as a recipient definition in one of the following forms:

type
type:address

The format of address depends on the value of type.

func ParseRecipients

func ParseRecipients(s []string) (recipients []Recipient, err error)

ParseRecipients takes the given set of strings and attempts to parse each one as a recipient.

type RecipientParser

type RecipientParser func(address string) (Recipient, error)

RecipientParser is capable of parsing a given recipient address.

type Source

type Source struct {
	Name      string
	Host      string
	Port      string
	Community string // SNMP community name
	Retries   uint
}

Source describes a source of power statists data. It holds the necessary information to perform an SNMP query.

Sources are queried to produce statistics, which are then fed to destinations.

func ParseSource

func ParseSource(s string) (src Source, err error)

ParseSource parses the given string as a power source description.

The address is expected to be in one of these forms:

community@host:port~name
community@host~name
host:port~name
host~name
community@host:port
community@host
host:port
host

func ParseSources

func ParseSources(s []string) (sources []Source, err error)

ParseSources takes the given set of strings and attempts to parse each one as a power source description.

func (Source) HostPort

func (s Source) HostPort() string

HostPort returns the combination of "host:port". Its format matches that of net.JoinHostPort().

func (Source) String

func (s Source) String() (value string)

String returns a string encoded representation of the power source.

type SourceHandler

type SourceHandler interface {
	SendSource(i int, s Source)
}

SourceHandler is a recipient that performs processing for each source.

type Statistic

type Statistic struct {
	Name   string          // Name of statistic
	Unit   string          // Unit of measurement
	OID    snmpgo.Oids     // One or more possible OID values for this statistic
	Mapper snmpvar.Float64 // SNMP value mapper
}

Statistic describes a single power management statistic.

func ParseStatistic

func ParseStatistic(s string) (stat Statistic, err error)

ParseStatistic parses a statistic in string format and returns the parsed value.

The statistic string format is a comma-separated list of optional elements, with a well-known statistic key followed by a series of property/value pairs:

KEY,name:NAME,oid:OID,unit:UNIT

The format is intended to meet three goals:

1. Easy use of well known statistics with preconfigured values 2. Overriding properties in preconfigured values with custom variations 3. Specification of custom, proprietary or otherwise unspported statistics

Examples:

"EstimatedMinutesRemaining"
"name:WidgetDuration,oid:OID"
"EstimatedMinutesRemaining,name:ZomboMinutes,oid:OID,unit:Unit"

func ParseStatistics

func ParseStatistics(s []string) (stats []Statistic, err error)

ParseStatistics takes the given set of strings and attempts to parse each one as a power statistic.

type Value

type Value struct {
	Source Source
	Stat   Statistic
	Time   time.Time
	Value  float64
	Err    error
}

Value represents a single statistical value from a device or power source.

func Query

func Query(ctx context.Context, source Source, stats ...Statistic) (results []Value, err error)

Query will attempt to retrieve the source's statistics via SNMP.

func (Value) StatName

func (v Value) StatName() string

StatName returns the name of the statistic.

func (Value) String

func (v Value) String() string

String returns a string representation of the value.