poller

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: GPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package poller asks what a tool reports on about its state, on schedules of the tool's own, and keeps the last good answer to each question, so a metrics page is written from memory however slow or gone the thing asked is. It says how the asking goes as readings of its own.

Index

Constants

This section is empty.

Variables

View Source
var ErrNothing = errors.New("nothing could be asked")

ErrNothing is what a question gives back when there was nothing it could ask, sensors only root may read say. A round in which every question had nothing to ask is counted neither as a success nor as a failure.

Functions

func Fixed

func Fixed(names ...string) func(context.Context) ([]string, error)

Fixed is a list of targets that never changes: the servers the settings name, say.

func ParseIntervals

func ParseIntervals(setting string, defaults map[string]time.Duration) (map[string]time.Duration, error)

ParseIntervals reads how often to ask each schedule from a setting written name=duration with commas between them, as --intervals sessions=15s is: every schedule in defaults at its default unless the setting names it. A name that is not a schedule, or a length of time that cannot be read or is nothing, or a schedule named twice, is an error that says which.

func Partial

func Partial(err error) error

Partial marks an error as coming with an answer worth keeping: what could be read, one phy of many that would not say. The answer is kept and the round still fails. Nil is nil.

Types

type Answer

type Answer[V any] struct {
	Value V
	// At is when it was given, and the zero time for a question never answered.
	At time.Time
}

Answer is the last good answer to one question, and when it was given.

func (Answer[V]) Known

func (a Answer[V]) Known() bool

Known says whether there is an answer to serve.

type Kept

type Kept[V any] struct {
	// contains filtered or unexported fields
}

Kept is where a question's last good answer about each target is kept.

func Ask

func Ask[T, V any](s *Schedule[T], what string, question func(ctx context.Context, target T) (V, error)) *Kept[V]

Ask adds a question to the schedule, put to each target every round, and is where its last good answer is kept. An answer that comes with an error is not kept, unless the error is Partial. What names the question in an error.

func AskOne

func AskOne[T, V any](s *Schedule[T], what string, question func(ctx context.Context) (V, error)) *Kept[V]

AskOne is Ask for a question that needs no target, in a tool that asks about one thing.

func (*Kept[V]) Answer

func (k *Kept[V]) Answer() Answer[V]

Answer is For the one thing a tool with no list of targets asks about.

func (*Kept[V]) For

func (k *Kept[V]) For(key string) Answer[V]

For is the last good answer about one target, or none once it is older than three of its schedule's intervals: whatever was asked has stopped answering, and what it last said is no longer worth showing as current. A nil Kept, for a schedule a tool left out, has none.

func (*Kept[V]) Set

func (k *Kept[V]) Set(key string, a Answer[V])

Set keeps an answer about one target as given: for a test's made-up state.

type Options

type Options[T any] struct {
	// Namespace starts the name of each reading the poller writes: "sas" gives sas_poll_duration_seconds.
	Namespace string
	// Label is the label the poller's readings name each target under: "card". Empty for a tool that asks about one thing.
	Label string
	// Kind is what a target is, for the log: "SAS card", or "NAS" for a tool that asks about one.
	Kind string
	// Targets lists the things to ask about, at the start of each round. Fixed is a list that never changes; nil is one thing, with the key "".
	Targets func(ctx context.Context) ([]T, error)
	// Key tells targets apart: a card's name in the kernel. A target that is a string is its own key.
	Key func(T) string
	// Names is what each target is called on the page and in the log, given every target ever seen, gone ones too. Nil calls each by its key.
	Names func(targets map[string]Target[T]) map[string]string
}

Options says what is asked about and how it is named.

type Poller

type Poller[T any] struct {
	// contains filtered or unexported fields
}

Poller asks about each target on each schedule, and remembers the last good answer to each question and how each round went.

func New

func New[T any](o Options[T]) (*Poller[T], error)

New is a poller that asks nothing until Run or Poll, and has no schedules until Schedule adds them.

func (*Poller[T]) Collect

func (p *Poller[T]) Collect(ch chan<- prometheus.Metric)

Collect writes how the asking is going: for each target and schedule that has finished a round, how often it is asked, how long the last round took, how many have failed, and when one last succeeded. A schedule that has not finished a round has none, so a tool just started does not show a round that took nothing or a success in 1970.

func (*Poller[T]) Describe

func (p *Poller[T]) Describe(ch chan<- *prometheus.Desc)

Describe names the readings the poller writes of its own asking.

func (*Poller[T]) Names

func (p *Poller[T]) Names() map[string]string

Names is what each target is called on the page, by its key: for the label on a tool's own readings, the same as on the poller's.

func (*Poller[T]) Poll

func (p *Poller[T]) Poll(ctx context.Context, schedule string) error

Poll polls one schedule once, and says what failed and why: for a test of what that schedule asks.

func (*Poller[T]) PollAll

func (p *Poller[T]) PollAll(ctx context.Context) error

PollAll polls every schedule once, all at once, and says which rounds failed, target by target: for a tool that prints its page once. Why each failed is in the log, one line each, so it is not said twice.

func (*Poller[T]) Round

func (p *Poller[T]) Round(key, schedule string) Round

Round is how the last round of one schedule went for one target.

func (*Poller[T]) Run

func (p *Poller[T]) Run(ctx context.Context)

Run polls until the context ends: every schedule at once on start, then each on its own interval.

func (*Poller[T]) Schedule

func (p *Poller[T]) Schedule(name string, every time.Duration) *Schedule[T]

Schedule adds a schedule: questions asked together every so often, which is also how long a round is given to finish. Ask adds its questions, before the poller runs. An interval of nothing or a name used twice is a mistake in the tool, and panics; ParseIntervals refuses one in a setting.

func (*Poller[T]) SetRound

func (p *Poller[T]) SetRound(key, schedule string, r Round)

SetRound records a round of one schedule for one target as given, Ran included: for a test's made-up state.

func (*Poller[T]) SetTarget

func (p *Poller[T]) SetTarget(t Target[T])

SetTarget makes a target known as given, Key included: for a test's made-up state.

func (*Poller[T]) Target

func (p *Poller[T]) Target(key string) Target[T]

Target is what is known of one target, and the zero Target for one never seen.

func (*Poller[T]) Targets

func (p *Poller[T]) Targets() []string

Targets is the key of every target seen since the start, gone ones too, in order.

type Round

type Round struct {
	// Ran says a round has finished since the start; until one has, the rest says nothing.
	Ran bool
	// OK says every question of the last round was answered.
	OK   bool
	Took time.Duration
	// LastSuccess is the zero time until a round succeeds.
	LastSuccess time.Time
	// Failures counts the rounds that failed since the start.
	Failures int
}

Round is how the last round of one schedule went for one target.

type Schedule

type Schedule[T any] struct {
	// contains filtered or unexported fields
}

Schedule is a set of questions asked of each target together, every so often.

type Target

type Target[T any] struct {
	Key    string
	Value  T
	Listed bool
	At     time.Time
}

Target is one thing asked about: its key, what the last listing said of it, whether the latest listing named it, and when it was last named.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL