health

package
v0.1.0-alpha.5 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 4 Imported by: 0

README

health

The health report a service gives (health.Status), and two functions that build one report from others: Aggregate rolls several reports into one, and FromComponentHealth turns a component's own report (component.HealthStatus) into a health.Status.

The package is a port of SemStreams' health; docs/admission-ledger.yaml (row health) records what was kept, what was dropped and what changed. It holds no state between calls, runs no goroutine and does no I/O.

import "github.com/c360studio/semengine/health"

The report

Field JSON Meaning
Component component What the report describes
Healthy healthy True only when Status is healthy
Status status healthy, degraded or unhealthy
Message message Text for a person to read
Timestamp timestamp When the report was made
SubStatuses sub_statuses The reports this one was built from, if any
Metrics metrics Uptime, error count and last activity, if known

Healthy and Status state one fact twice. NewHealthy, NewDegraded and NewUnhealthy set both, with the current time, so build reports with them. IsDegraded, IsUnhealthy and Aggregate read the Status word only.

The JSON field names are a wire format that operators read; keep them stable.

A Status is a plain value, but Metrics is a pointer, so a copy of a Status shares its Metrics.

Rolling reports up

overall := health.Aggregate("platform", []health.Status{
    health.NewHealthy("nats", "connected"),
    health.NewDegraded("cache", "running without a warm index"),
})
// overall.Status == "degraded", overall.Healthy == false, len(overall.SubStatuses) == 2

Aggregate takes the worst word among its inputs:

  • unhealthy if any input is unhealthy;
  • otherwise degraded if any input is degraded;
  • otherwise healthy.

It reads only each input's own word, one level deep: a degraded report nested inside an input's SubStatuses does not change the result. An input with any other word, the empty word included, counts as healthy, and an empty list gives healthy. The result's SubStatuses is a copy of the input list.

Converting a component's report

FromComponentHealth(name, ch):

  • The word comes from ch.Healthy alone: true gives healthy, false gives unhealthy. The component's own ch.Status is not read, so a component that reports itself degraded with Healthy false becomes unhealthy.
  • Healthy is ch.Healthy.
  • Metrics carries ch.Uptime, ch.ErrorCount and ch.LastCheck (as LastActivity).
  • Message is "Component healthy" or "Component unhealthy", following ch.Healthy, when ch.LastError is empty. SemStreams wrote "Component healthy" in both cases.
  • Otherwise Message is ch.LastError with likely secrets replaced.
What the error text loses

The replacements run in this order, on text:

Matches Becomes
http://, https://, nats://, ws://, wss:// URLs [URL]
Unix paths (any run starting with /) and Windows paths (C:\...) [PATH]
IPv4 addresses [IP]
: followed by two to five digits [PORT]
password, token, key, secret or credential, then : or = and a value [REDACTED]

Matching on text removes more than secrets:

Input Message
failed to bind to :8080 failed to bind to [PORT]
at 12:30:45 at 12[PORT][PORT]
graph/ingest graph[PATH]
invalid key=acme.prod.sensor.device.unit.one invalid [REDACTED]

The messages given to NewHealthy, NewDegraded and NewUnhealthy are used as given.

What this package does not do

It does not decide readiness; that is a separate question with its own endpoint (docs/adr/109-ready-after-boot.md). It keeps no list of components and does not watch them: the caller builds reports when it is asked for one.

Documentation

Overview

Package health holds the health report a service gives, and the two functions that turn several reports, or a component's own report, into one.

The report

A Status names what it describes (Component), says whether it is healthy in two fields, carries a human-readable Message and the time it was made, and may carry the reports it was built from (SubStatuses) and a few numbers (Metrics: uptime, error count, last activity).

The word in Status is one of "healthy", "degraded" or "unhealthy". Healthy is true only for "healthy". NewHealthy, NewDegraded and NewUnhealthy set both fields and the timestamp, so build reports with them. Status.IsDegraded, Status.IsUnhealthy and Aggregate read the word only, never Healthy.

The JSON field names are a wire format: operators read these reports as JSON, so keep the names stable.

A Status is a plain value, but Metrics is a pointer: copying a Status, or aggregating it, shares the same Metrics with the copy.

Rolling reports up

Aggregate makes one report from several. Its word is "unhealthy" when any input's word is "unhealthy", otherwise "degraded" when any input's word is "degraded", otherwise "healthy". It looks one level deep: it reads each input's word and never looks into the input's own SubStatuses. An input with any other word, the empty word included, counts as healthy, and no inputs at all give "healthy". The result carries a copy of the inputs as its SubStatuses.

overall := health.Aggregate("platform", []health.Status{
	health.NewHealthy("nats", "connected"),
	health.NewDegraded("cache", "running without a warm index"),
})
// overall.Status == "degraded", overall.Healthy == false

Converting a component's report

FromComponentHealth turns a component.HealthStatus into a Status. The word comes from Healthy alone: true gives "healthy" and false gives "unhealthy". The component's own Status word is not read, so a component that reports itself "degraded" with Healthy false is reported "unhealthy". Healthy is copied as is, and Metrics carries the component's Uptime, ErrorCount and LastCheck (as LastActivity).

When the component's LastError is empty, Message is "Component healthy" or "Component unhealthy", following Healthy. Otherwise Message is LastError with likely secrets replaced, in this order:

  • http, https, nats, ws and wss URLs become [URL];
  • Unix paths (any run starting with "/") and Windows paths (C:\...) become [PATH];
  • IPv4 addresses become [IP];
  • ":" followed by two to five digits becomes [PORT];
  • password, token, key, secret or credential followed by ":" or "=" and a value becomes [REDACTED].

The replacement works on text and can remove more than a secret: "at 12:30:45" becomes "at 12[PORT][PORT]", "graph/ingest" becomes "graph[PATH]", and "key=acme.prod.sensor.device.unit.one" becomes "[REDACTED]". The messages passed to NewHealthy, NewDegraded and NewUnhealthy are used as given.

What this package does not do

It does not decide readiness, which is a separate question with its own endpoint (ADR-109). It runs no goroutine, keeps no state between calls and does no I/O.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Metrics

type Metrics struct {
	Uptime       time.Duration `json:"uptime"`
	ErrorCount   int           `json:"error_count"`
	LastActivity time.Time     `json:"last_activity,omitempty"`
}

Metrics contains health-related metrics

type Status

type Status struct {
	Component   string    `json:"component"`
	Healthy     bool      `json:"healthy"` // true if status is "healthy"
	Status      string    `json:"status"`  // "healthy", "unhealthy", "degraded"
	Message     string    `json:"message"`
	Timestamp   time.Time `json:"timestamp"`
	SubStatuses []Status  `json:"sub_statuses,omitempty"`
	Metrics     *Metrics  `json:"metrics,omitempty"`
}

Status represents the health state of a component or system

func Aggregate

func Aggregate(component string, subStatuses []Status) Status

Aggregate creates a status by aggregating sub-statuses The aggregation rules are: - If all sub-statuses are healthy, the aggregate is healthy - If any sub-status is unhealthy, the aggregate is unhealthy - If no sub-status is unhealthy but at least one is degraded, the aggregate is degraded

func FromComponentHealth

func FromComponentHealth(name string, ch component.HealthStatus) Status

FromComponentHealth converts a component.HealthStatus to a health.Status

func NewDegraded

func NewDegraded(component, message string) Status

NewDegraded creates a new degraded status

func NewHealthy

func NewHealthy(component, message string) Status

NewHealthy creates a new healthy status

func NewUnhealthy

func NewUnhealthy(component, message string) Status

NewUnhealthy creates a new unhealthy status

func (Status) IsDegraded

func (s Status) IsDegraded() bool

IsDegraded returns true if the status is degraded

func (Status) IsUnhealthy

func (s Status) IsUnhealthy() bool

IsUnhealthy returns true if the status is unhealthy

Jump to

Keyboard shortcuts

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