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 ¶
- Variables
- func Fixed(names ...string) func(context.Context) ([]string, error)
- func ParseIntervals(setting string, defaults map[string]time.Duration) (map[string]time.Duration, error)
- func Partial(err error) error
- type Answer
- type Kept
- type Options
- type Poller
- func (p *Poller[T]) Collect(ch chan<- prometheus.Metric)
- func (p *Poller[T]) Describe(ch chan<- *prometheus.Desc)
- func (p *Poller[T]) Names() map[string]string
- func (p *Poller[T]) Poll(ctx context.Context, schedule string) error
- func (p *Poller[T]) PollAll(ctx context.Context) error
- func (p *Poller[T]) Round(key, schedule string) Round
- func (p *Poller[T]) Run(ctx context.Context)
- func (p *Poller[T]) Schedule(name string, every time.Duration) *Schedule[T]
- func (p *Poller[T]) SetRound(key, schedule string, r Round)
- func (p *Poller[T]) SetTarget(t Target[T])
- func (p *Poller[T]) Target(key string) Target[T]
- func (p *Poller[T]) Targets() []string
- type Round
- type Schedule
- type Target
Constants ¶
This section is empty.
Variables ¶
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 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.
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.
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.
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 ¶
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 ¶
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 ¶
Poll polls one schedule once, and says what failed and why: for a test of what that schedule asks.
func (*Poller[T]) PollAll ¶
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]) Run ¶
Run polls until the context ends: every schedule at once on start, then each on its own interval.
func (*Poller[T]) Schedule ¶
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 ¶
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 ¶
SetTarget makes a target known as given, Key included: for a test's made-up state.
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.