engine

Documentation

Overview

Package engine defines the check contract and the runner. A Check produces Findings; the runner executes every registered check with a shared timeout and aggregates results. Output rendering lives in internal/output, so checks stay pure and testable.

Index

• func StackPath(basePath, stack string) string
• func Summarize(findings []Finding) map[Status]int
• func Validate(cfg *Config) []string
• type CertsConfig
• type Check
• type ChecksConfig
• type Config
  • func LoadConfig(path string) (*Config, error)
  • func LoadConfigStack(basePath, stack string) (*Config, error)
• type ConsulConfig
• type DNSConfig
• type DNSTarget
• type FilterOptions
• type Finding
  • func Filter(findings []Finding, o FilterOptions) []Finding
• type GRPCConfig
• type GRPCTarget
• type HAProxyConfig
• type HTTPConfig
• type HTTPTarget
• type KafkaConfig
• type KeycloakConfig
• type LDAPConfig
• type LDAPTarget
• type NATSConfig
• type NTPConfig
• type Options
• type PatroniConfig
• type PostgresConfig
• type PostgresTarget
• type RabbitMQConfig
• type RedisConfig
• type Result
  • func Run(ctx context.Context, checks []Check, timeout time.Duration) Result
  • func RunWith(ctx context.Context, checks []Check, opts Options) Result
• type Status
  • func ParseStatus(s string) (Status, bool)
  • func Worst(findings []Finding) Status
• type StreamConfig
• type StreamTarget
• type TCPConfig
• type TCPTarget
• type TLSConfig

Functions

func StackPath

func StackPath(basePath, stack string) string

StackPath derives the per-stack config path from the base path: "checkfleet.yml" + "prod" → "checkfleet.prod.yml".

func Summarize

func Summarize(findings []Finding) map[Status]int

Summarize counts findings per status.

func Validate

func Validate(cfg *Config) []string

Validate checks a loaded config for problems without running any check. It returns a list of human-readable issues; empty means the config is usable. It runs on the defaulted config, so threshold checks compare effective values.

Types

type CertsConfig

type CertsConfig struct {
	WarnDays int `yaml:"warn_days"`
	CritDays int `yaml:"crit_days"`
	// Default port for targets and inventory hosts without an explicit one.
	Port int `yaml:"port"`
	// Explicit host[:port] targets.
	Targets []string `yaml:"targets"`
	// Optional Ansible INI inventory: every host becomes a target on Port.
	AnsibleInventory string `yaml:"ansible_inventory"`
}

CertsConfig configures the TLS certificate expiry check.

type Check

type Check interface {
	Name() string
	Run(ctx context.Context) []Finding
}

Check is implemented by every module (certs, http, ...).

type ChecksConfig

type ChecksConfig struct {
	Certs    *CertsConfig    `yaml:"certs"`
	HTTP     *HTTPConfig     `yaml:"http"`
	NATS     *NATSConfig     `yaml:"nats"`
	HAProxy  *HAProxyConfig  `yaml:"haproxy"`
	Stream   *StreamConfig   `yaml:"stream"`
	Patroni  *PatroniConfig  `yaml:"patroni"`
	Consul   *ConsulConfig   `yaml:"consul"`
	Postgres *PostgresConfig `yaml:"postgres"`
	DNS      *DNSConfig      `yaml:"dns"`
	Redis    *RedisConfig    `yaml:"redis"`
	Keycloak *KeycloakConfig `yaml:"keycloak"`
	TCP      *TCPConfig      `yaml:"tcp"`
	TLS      *TLSConfig      `yaml:"tls"`
	NTP      *NTPConfig      `yaml:"ntp"`
	RabbitMQ *RabbitMQConfig `yaml:"rabbitmq"`
	GRPC     *GRPCConfig     `yaml:"grpc"`
	LDAP     *LDAPConfig     `yaml:"ldap"`
	Kafka    *KafkaConfig    `yaml:"kafka"`
}

type Config

type Config struct {
	TimeoutSeconds int          `yaml:"timeout_seconds"`
	Retries        int          `yaml:"retries"`          // retry checks with ERROR findings
	RetryBackoffMS int          `yaml:"retry_backoff_ms"` // base backoff (default 500 when retries>0)
	Checks         ChecksConfig `yaml:"checks"`
}

Config is the root of checkfleet.yml.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads and validates checkfleet.yml, applying defaults.

func LoadConfigStack

func LoadConfigStack(basePath, stack string) (*Config, error)

LoadConfigStack loads a base config and overlays a per-stack file (checkfleet.<stack>.yml next to the base), applying defaults after the merge. A module present in the stack replaces the base's module wholesale.

type ConsulConfig

type ConsulConfig struct {
	// Consul HTTP API endpoints as host[:port]; Port applies when a target has
	// none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	Scheme  string   `yaml:"scheme"`
	// Optional Ansible INI inventory: every host becomes an API target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Optional expected number of raft peers; fewer than this is WARN.
	ExpectPeers int `yaml:"expect_peers"`
	// Optional ACL token, read from this env var (X-Consul-Token); never inline.
	TokenEnv string `yaml:"token_env"`
	// Optional KV keys that must exist; a missing key is BAD.
	KVKeys []string `yaml:"kv_keys"`
}

ConsulConfig configures the Consul cluster health check.

type DNSConfig

type DNSConfig struct {
	// Resolvers to query as host[:port] (default port 53). Empty → the system
	// resolvers from /etc/resolv.conf.
	Resolvers []string `yaml:"resolvers"`
	// WARN when any answer's TTL is below this many seconds. 0 disables.
	MinTTLSeconds uint32      `yaml:"min_ttl_seconds"`
	Targets       []DNSTarget `yaml:"targets"`
}

DNSConfig configures the DNS resolution health check.

type DNSTarget

type DNSTarget struct {
	// Domain name to resolve.
	Name string `yaml:"name"`
	// Record type: A, AAAA, CNAME, TXT, NS, SOA. Default A.
	Type string `yaml:"type"`
	// Optional expected value set; a different answer is BAD (drift). For SOA
	// this is compared against the serial.
	Expect []string `yaml:"expect"`
}

type FilterOptions

type FilterOptions struct {
	Only        map[string]bool // check names to keep; empty = all
	MinSeverity Status          // keep findings at or above this severity; "" = all
	TargetGlob  string          // path.Match glob on the target; "" = all
}

FilterOptions narrows a set of findings for output.

type Finding

type Finding struct {
	Check   string `json:"check"`
	Target  string `json:"target"`
	Status  Status `json:"status"`
	Message string `json:"message"`
}

Finding is one observation about one target.

func Filter

func Filter(findings []Finding, o FilterOptions) []Finding

Filter returns the findings that pass every set criterion, preserving order.

type GRPCConfig

type GRPCConfig struct {
	Targets []GRPCTarget `yaml:"targets"`
}

GRPCConfig configures the gRPC health-checking-protocol check (TLS/h2 only).

type GRPCTarget

type GRPCTarget struct {
	// Optional display label; defaults to Address (+ service).
	Name string `yaml:"name"`
	// host:port of the gRPC (TLS) endpoint. Required.
	Address string `yaml:"address"`
	// Optional gRPC service name to check; empty = whole-server health.
	Service string `yaml:"service"`
	// Skip TLS certificate verification (internal self-signed endpoints).
	InsecureSkipVerify bool `yaml:"insecure_skip_verify"`
}

type HAProxyConfig

type HAProxyConfig struct {
	// Stats endpoints as host[:port]; Port applies when a target has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	// Scheme (http/https) and path of the CSV stats export.
	Scheme string `yaml:"scheme"`
	Path   string `yaml:"path"`
	// Optional Ansible INI inventory: every host becomes a stats target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Optional WARN when a server/backend session usage reaches this percent
	// of its limit (scur/slim). 0 disables the check.
	SessionWarnPct int `yaml:"session_warn_pct"`
	// Optional HTTP basic auth. The password is read from the named env var —
	// never store it in the config file.
	AuthUser    string `yaml:"auth_user"`
	AuthPassEnv string `yaml:"auth_pass_env"`
}

HAProxyConfig configures the HAProxy backend/server health check.

type HTTPConfig

type HTTPConfig struct {
	Targets []HTTPTarget `yaml:"targets"`
}

HTTPConfig configures the HTTP probe check.

type HTTPTarget

type HTTPTarget struct {
	URL          string `yaml:"url"`
	ExpectStatus int    `yaml:"expect_status"`
	MaxLatencyMS int    `yaml:"max_latency_ms"`
	ExpectBody   string `yaml:"expect_body"`
}

type KafkaConfig

type KafkaConfig struct {
	Brokers []string `yaml:"brokers"`
	TLS     bool     `yaml:"tls"`
	// Optional SASL: mechanism plain|scram-sha-256|scram-sha-512; password from env.
	SASLUser        string `yaml:"sasl_user"`
	SASLMechanism   string `yaml:"sasl_mechanism"`
	SASLPasswordEnv string `yaml:"sasl_password_env"`
	// Optional expected broker count; fewer is WARN.
	ExpectBrokers int `yaml:"expect_brokers"`
	// Consumer groups whose lag to check.
	Groups  []string `yaml:"groups"`
	LagWarn int64    `yaml:"lag_warn"`
	LagCrit int64    `yaml:"lag_crit"`
}

KafkaConfig configures the Kafka cluster health check.

type KeycloakConfig

type KeycloakConfig struct {
	// Base URL (scheme + host [+ path prefix like /auth]), no trailing slash.
	BaseURL string `yaml:"base_url"`
	// Optional health endpoint (e.g. https://auth:9000/health/ready); checked
	// only when set (Keycloak often serves health on the management port).
	HealthURL string `yaml:"health_url"`
	// Realms to verify via their OIDC discovery document.
	Realms []string `yaml:"realms"`
}

KeycloakConfig configures the Keycloak health check.

type LDAPConfig

type LDAPConfig struct {
	Targets []LDAPTarget `yaml:"targets"`
}

LDAPConfig configures the LDAP bind + search check.

type LDAPTarget

type LDAPTarget struct {
	// Optional display label; defaults to URL.
	Name string `yaml:"name"`
	// ldap://host:389 or ldaps://host:636. Required.
	URL string `yaml:"url"`
	// Optional StartTLS on a plain ldap:// connection.
	StartTLS           bool `yaml:"start_tls"`
	InsecureSkipVerify bool `yaml:"insecure_skip_verify"`
	// Optional bind; empty BindDN = anonymous. Password from the env var.
	BindDN      string `yaml:"bind_dn"`
	PasswordEnv string `yaml:"password_env"`
	// Optional sanity search: at least MinEntries under BaseDN matching Filter.
	BaseDN     string `yaml:"base_dn"`
	Filter     string `yaml:"filter"`
	MinEntries int    `yaml:"min_entries"`
}

type NATSConfig

type NATSConfig struct {
	// Monitoring endpoints as host[:port]; Port applies when a target has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	// Optional Ansible INI inventory: every host becomes a monitoring target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Scheme for the monitoring endpoint (http or https). Default http.
	Scheme string `yaml:"scheme"`
	// Optional expected meta-leader (server_name); a mismatch is WARN.
	ExpectMetaLeader string `yaml:"expect_meta_leader"`
	// Optional expected peer set (server_name); unexpected peers are ghosts
	// (WARN), missing expected peers are BAD.
	ExpectPeers []string `yaml:"expect_peers"`
	// Raft peer lag thresholds (entries). WARN/BAD when a peer is at or above.
	LagWarn int `yaml:"lag_warn"`
	LagCrit int `yaml:"lag_crit"`
}

NATSConfig configures the NATS JetStream cluster health check.

type NTPConfig

type NTPConfig struct {
	Targets      []string `yaml:"targets"`
	Port         int      `yaml:"port"`
	OffsetWarnMS int      `yaml:"offset_warn_ms"`
	OffsetCritMS int      `yaml:"offset_crit_ms"`
}

NTPConfig configures the NTP clock-offset check.

type Options

type Options struct {
	Timeout time.Duration // per-check (and per-attempt) deadline
	Retries int           // extra attempts for a check that produced ERROR findings
	Backoff time.Duration // base backoff between attempts (doubles each retry)
}

Run executes the checks sequentially, each bounded by timeout. Findings are sorted by severity (worst first), then check, then target. Options tunes a run.

type PatroniConfig

type PatroniConfig struct {
	// Patroni REST API endpoints as host[:port]; Port applies when a target
	// has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	Scheme  string   `yaml:"scheme"`
	// Optional Ansible INI inventory: every host becomes an API target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Replica lag thresholds in bytes (WARN/BAD).
	LagWarnBytes int64 `yaml:"lag_warn_bytes"`
	LagCritBytes int64 `yaml:"lag_crit_bytes"`
}

PatroniConfig configures the Patroni cluster health check.

type PostgresConfig

type PostgresConfig struct {
	Targets []PostgresTarget `yaml:"targets"`
	// Replica lag thresholds in bytes (WARN/BAD).
	LagWarnBytes int64 `yaml:"lag_warn_bytes"`
	LagCritBytes int64 `yaml:"lag_crit_bytes"`
	// WARN when connections reach this percent of max_connections.
	ConnWarnPct int `yaml:"conn_warn_pct"`
	// Transaction-id age thresholds (WARN/BAD) for wraparound risk.
	WraparoundWarnAge int64 `yaml:"wraparound_warn_age"`
	WraparoundCritAge int64 `yaml:"wraparound_crit_age"`
	// Retained-WAL thresholds for inactive replication slots (WARN/BAD).
	SlotWarnBytes int64 `yaml:"slot_warn_bytes"`
	SlotCritBytes int64 `yaml:"slot_crit_bytes"`
}

PostgresConfig configures the PostgreSQL health check (read-only SQL).

type PostgresTarget

type PostgresTarget struct {
	// Display label; defaults to the DSN host.
	Name string `yaml:"name"`
	// libpq DSN or URL, WITHOUT the password.
	DSN string `yaml:"dsn"`
	// Password read from this env var (never store it in the config).
	PasswordEnv string `yaml:"password_env"`
}

type RabbitMQConfig

type RabbitMQConfig struct {
	// Management API endpoints as host[:port]; Port applies when none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	Scheme  string   `yaml:"scheme"`
	// HTTP basic auth. Password from the env var; never inline.
	Username    string `yaml:"username"`
	PasswordEnv string `yaml:"password_env"`
	// Queue depth thresholds (messages ready+unacked).
	QueueWarnDepth int `yaml:"queue_warn_depth"`
	QueueCritDepth int `yaml:"queue_crit_depth"`
}

RabbitMQConfig configures the RabbitMQ management-API health check.

type RedisConfig

type RedisConfig struct {
	// Endpoints as host[:port]; Port applies when a target has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	// Optional Ansible INI inventory: every host becomes a target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Optional TLS (rediss) and ACL auth. Password comes from the env var.
	TLS         bool   `yaml:"tls"`
	Username    string `yaml:"username"`
	PasswordEnv string `yaml:"password_env"`
	// WARN when used_memory reaches this percent of maxmemory (0 disables).
	MemWarnPct int `yaml:"mem_warn_pct"`
	// Replica offset lag thresholds in bytes (WARN/BAD).
	LagWarnBytes int64 `yaml:"lag_warn_bytes"`
	LagCritBytes int64 `yaml:"lag_crit_bytes"`
}

RedisConfig configures the Redis/Valkey health check.

type Result

type Result struct {
	Findings []Finding     `json:"findings"`
	Started  time.Time     `json:"started"`
	Duration time.Duration `json:"duration_ns"`
}

Result aggregates the findings of a run.

func Run

func Run(ctx context.Context, checks []Check, timeout time.Duration) Result

Run executes the checks with only a timeout (no retries).

func RunWith

func RunWith(ctx context.Context, checks []Check, opts Options) Result

RunWith executes the checks concurrently under opts. Results are collected per-check by index and flattened in check order, so the output is deterministic regardless of completion order (the stable sort below then orders by severity). Checks whose result contains an ERROR finding are retried up to opts.Retries times with exponential backoff.

type Status

type Status string

Status of a single finding. Severity order: OK < WARN < BAD < ERROR.

const (
	OK    Status = "OK"
	WARN  Status = "WARN"
	BAD   Status = "BAD"
	ERROR Status = "ERROR" // the check itself could not run against the target
)

func ParseStatus

func ParseStatus(s string) (Status, bool)

ParseStatus maps a case-insensitive name to a Status ("" input → ("", true)).

func Worst

func Worst(findings []Finding) Status

Worst returns the most severe status present (OK for an empty list).

type StreamConfig

type StreamConfig struct {
	Targets []StreamTarget `yaml:"targets"`
}

StreamConfig configures the HLS/DASH stream health check.

type StreamTarget

type StreamTarget struct {
	// Manifest URL: an HLS .m3u8 (master or media) or a DASH .mpd.
	URL string `yaml:"url"`
	// Optional display label; defaults to the URL.
	Name string `yaml:"name"`
	// Expected minimum ladder size (variants/representations). 0 disables.
	MinVariants int `yaml:"min_variants"`
	// Expect a live stream: check live-edge freshness and warn if it's VOD.
	Live bool `yaml:"live"`
	// Live-edge age thresholds in seconds (WARN/BAD). Applied when Live is set.
	MaxAgeWarnSeconds int `yaml:"max_age_warn_seconds"`
	MaxAgeCritSeconds int `yaml:"max_age_crit_seconds"`
}

type TCPConfig

type TCPConfig struct {
	Targets []TCPTarget `yaml:"targets"`
}

TCPConfig configures the generic TCP reachability check.

type TCPTarget

type TCPTarget struct {
	// Optional display label; defaults to Address.
	Name string `yaml:"name"`
	// host:port to connect to. Required.
	Address string `yaml:"address"`
	// Optional TLS handshake instead of a plain TCP connect.
	TLS bool `yaml:"tls"`
	// Optional substring the server banner must contain (first bytes read).
	ExpectBanner string `yaml:"expect_banner"`
	// Optional WARN when the connect takes longer than this.
	MaxLatencyMS int `yaml:"max_latency_ms"`
}

type TLSConfig

type TLSConfig struct {
	Targets          []string `yaml:"targets"`
	Port             int      `yaml:"port"`
	WarnDays         int      `yaml:"warn_days"`
	CritDays         int      `yaml:"crit_days"`
	AnsibleInventory string   `yaml:"ansible_inventory"`
}

TLSConfig configures the deep TLS check (chain validity, expiry, protocol).