sources

Documentation

Overview

Package sources runs polled alert producers alongside the informer-driven Kubernetes watchers. A watcher reacts to an object event stream; a Source is polled on a fixed interval because the systems it inspects - cloud provider control planes (AWS, Azure, GCP) - are request/response, not watchable.

Sources are deliberately stateless. Each Poll reports the *current* state of the world: it emits a firing alert for every unhealthy resource and a resolved alert (Resolved=true) for every healthy one. Firing state lives in the alert.Store, not the Source, so re-emitting the full picture every cycle is both cheap and correct:

• a still-firing alert is deduped by the mute window, and the muted re-fire refreshes its resolve TTL (see makeEmitter), so it stays active for as long as the condition holds;
• a resolve for a resource that has no active alert is a no-op (Store.ResolveObject only fires for matches), so emitting resolves for every healthy resource every cycle never produces spurious "resolved" notifications.

This is the same Emit contract the watchers use, so cloud alerts flow through the identical dedupe -> route -> group -> sink pipeline with no special-casing downstream.

Index

• func EmitFiring(emit Emit, k alert.Kind, scope, name, reason, summary string, ...)
• func EmitResolve(emit Emit, k alert.Kind, scope, name string)
• func PollErr(source, scope string, err error)
• func RegisterProvider(p Provider)
• func Run(ctx context.Context, interval time.Duration, emit Emit, srcs ...Source)
• func Scope(parent, location string) string
• func StrVal(s *string) string
• type Emit
• type Provider
  • func Providers() []Provider
• type Source
  • func Compact(srcs []Source) []Source

Functions

func EmitFiring

func EmitFiring(emit Emit, k alert.Kind, scope, name, reason, summary string, sev alert.Severity, labels, details map[string]string)

EmitFiring publishes a firing cloud alert. labels are attached verbatim (e.g. {"provider":"aws","region":"us-east-1"}); empty detail values are dropped so sinks never render blank rows.

func EmitResolve

func EmitResolve(emit Emit, k alert.Kind, scope, name string)

EmitResolve clears any active alert for one cloud resource. Identity only, Resolved=true, no reason/severity - the store resolves every active alert for kind+scope+name. A resolve for a resource with no active alert is a no-op, so callers may emit it for every healthy resource each poll without producing spurious "resolved" notifications.

func PollErr

func PollErr(source, scope string, err error)

PollErr records a per-source poll failure on the shared metric and logs it, so a blinded cloud source is observable without crashing the controller.

func RegisterProvider

func RegisterProvider(p Provider)

RegisterProvider adds a cloud provider to the registry. Called from each provider package's init.

func Run

func Run(ctx context.Context, interval time.Duration, emit Emit, srcs ...Source)

Run polls every source on its own goroutine until ctx is cancelled, then blocks until all in-flight polls return. Add it to the controller WaitGroup so the shutdown sequence waits for a clean drain.

Each source gets its own ticker so a slow provider API cannot delay the others. time.Ticker coalesces ticks (its channel buffers at most one), so a poll that overruns the interval simply skips the missed ticks instead of piling up a backlog of overlapping polls. The first poll runs after a small bounded jitter so many sources do not stampede the provider API at once.

func Scope

func Scope(parent, location string) string

Scope joins a provider parent scope (Azure subscription, GCP project) with a location qualifier (region/zone) into the alert-identity scope, omitting the separator when the location is unknown so identities stay stable.

func StrVal

func StrVal(s *string) string

StrVal dereferences a *string, returning "" for nil. Cloud SDK response fields are overwhelmingly *string; this is the shared nil-safe accessor.

Types

type Emit

type Emit = func(*alert.Alert)

Emit publishes an alert into the controller pipeline. It is structurally identical to watchers.Emit (both are func(*alert.Alert)); the controller hands the same emitter to watchers and sources alike, so this package need not import internal/watchers.

type Provider

type Provider struct {
	// Name identifies the provider in logs (e.g. "aws").
	Name string
	// Enabled reports whether the provider is turned on in config.
	Enabled func(*config.Config) bool
	// PollSeconds is the provider's configured poll interval.
	PollSeconds func(*config.Config) int
	// Build constructs the enabled sources for the provider. A construction
	// error (bad credentials/config) is logged by the caller and the provider
	// skipped, so a cloud-auth problem never takes down the Kubernetes watchers.
	Build func(context.Context, *config.Config) ([]Source, error)
}

Provider describes a cloud provider's source set (AWS, Azure, GCP, ...). Each provider package registers one in its init via RegisterProvider, so wiring a new cloud is a self-contained package - the controller iterates the registry instead of hardcoding each provider (mirrors the sink self-registration).

func Providers

func Providers() []Provider

Providers returns the registered cloud providers.

type Source

type Source interface {
	// Name identifies the source in logs and in the cloud-poll-error metric
	// (e.g. "aws-eks").
	Name() string
	// Poll inspects current state once and emits firing/resolved alerts. It
	// must return promptly when ctx is cancelled. It must not rely on the
	// caller to recover panics for correctness: the runner does recover them
	// so one provider bug cannot crash the controller, but Poll is expected
	// to handle its own API errors and surface them via
	// metrics.CloudPollErrors rather than panicking.
	Poll(ctx context.Context, emit Emit)
}

Source is a pollable alert producer that lives beside the Kubernetes watchers.

func Compact

func Compact(srcs []Source) []Source

Compact drops the nil entries a disabled source toggle leaves behind, so a provider's Build can list every candidate source unconditionally - one line per service, in a fixed order - and filter once at the end instead of guarding each append.