Documentation
¶
Overview ¶
Package health answers a question the container runtime cannot: is this service actually EARNING, as distinct from merely running?
Desktop's status column is built from the container's own state, which is computed from starts, stops and crashes. A service that has produced nothing for a month still shows a green "running" pill, because from the runtime's point of view nothing is wrong. "It runs but earns nothing" is the most common complaint in this whole product category, and container state is structurally incapable of seeing it.
So this is a SEPARATE verdict, deliberately. A service can be a perfectly healthy container and a dead producer, and collapsing the two hides exactly the case the user cares about. It ports the idea from the web sibling's app/producer_state.py.
Two signals feed it, and they are the two Desktop can actually observe:
- Log signals — the per-service regexes declared in the service catalog (docker.health_signals). Service-specific knowledge lives in the catalog, never here, and for the catalogued services with no earnings collector this is the only signal there is.
- Restart loops — a container the runtime itself reports as "restarting" spends most of its life starting up rather than working. This is the runtime's own observation, not a tally kept here: Desktop records an event for a user action that failed, never for a container that exited on its own, so counting those events would accuse a healthy service of looping because the user clicked Deploy three times while the container runtime was off.
What is NOT here matters just as much. There is no "producing" verdict: nothing Desktop can see from a container proves money moved, and a green "earning" badge that means "we found no problem" is the false confidence this package exists to remove. The worst answer is a confident one we cannot support, so anything we could not check says so.
Index ¶
- Constants
- func Collect(ctx context.Context, logs LogReader, services ServiceLookup, ...) map[string]Report
- func IsWindowed(s catalog.HealthSignal) bool
- func WindowedHit(lines string, s catalog.HealthSignal) bool
- type Deployed
- type Hit
- type Input
- type LogReader
- type Report
- type ServiceLookup
- type State
- type WindowReader
Constants ¶
const NativeRuntime = "native"
NativeRuntime is the runtime kind for a service supervised as a process on the user's own machine (internal/runtime.NativeRuntimeKind). It is repeated here rather than imported so this package stays a leaf with no runtime dependency.
Variables ¶
This section is empty.
Functions ¶
func Collect ¶
func Collect(ctx context.Context, logs LogReader, services ServiceLookup, deployed []Deployed) map[string]Report
Collect returns the producer verdict for every deployed service, keyed by slug.
Logs are read ONLY for a service whose catalog entry declares signals to match them against, and only while its container is up — reading a log tail nobody has a pattern for would be a container-runtime round trip per service per refresh, spent to learn nothing. A natively supervised process is skipped for a second reason: the catalog's signals sit under its docker: stanza and explain themselves in terms of a container, so matching them there produces advice the user cannot act on.
The log reads run at the same time, each under its own logTimeout, so the whole collection costs one timeout at most rather than one per service: ten deployed services on a wedged runtime used to hold a dashboard refresh for thirty seconds.
func IsWindowed ¶ added in v0.25.3
func IsWindowed(s catalog.HealthSignal) bool
IsWindowed reports whether a signal is judged over hours of logs, not the tail.
func WindowedHit ¶ added in v0.25.3
func WindowedHit(lines string, s catalog.HealthSignal) bool
WindowedHit is true when the pattern matches at least MinMatches lines of the window and the unless pattern none. No line at all is no hit: a node nobody has used has nothing to judge.
Types ¶
type Deployed ¶
type Deployed struct {
Slug string
// ContainerState is the runtime's word for it; empty means it could not be asked.
ContainerState string
// Runtime is which backend is running it: "docker", "podman" or NativeRuntime.
Runtime string
}
Deployed is one deployed service as the caller sees it, before any judgement.
type Hit ¶
Hit is one declared signal that was found in the logs.
func MatchSignals ¶
func MatchSignals(logs string, signals []catalog.HealthSignal) []Hit
MatchSignals returns the declared signals whose pattern appears in the logs. An invalid regex is skipped rather than fatal: a typo in one service's catalog entry must not break the verdict for every other service.
type Input ¶
type Input struct {
Slug string
// ContainerState is the runtime's own word for the container: "running",
// "restarting", "exited", "created". An EMPTY string means we could not ask,
// which is not the same claim as "it is stopped" — telling a user their service
// is down when we simply could not look sends them to restart something that is
// probably up.
ContainerState string
// Native says this service runs as a supervised process on the user's own
// machine rather than in a container. The catalog's signals live under its
// docker: stanza and their explanations are written about a container -- the
// mysterium one tells the user to redeploy a container that, here, does not
// exist -- so they are not matched against a native process's logs.
Native bool
// Signals are the log patterns this service's catalog entry declares. None is the
// normal case: most services declare none, and that makes them not-checked rather
// than fine.
Signals []catalog.HealthSignal
// Logs is the recent log tail. LogsRead says whether reading them actually worked,
// because an empty string is both "the read failed" and "the service is quiet",
// and only one of those is worth telling the user about.
Logs string
LogsRead bool
// WindowHits are the windowed signals that held at their last check.
WindowHits []Hit
}
Input is everything Assess is allowed to reason from, gathered by the caller.
type LogReader ¶
LogReader reads a deployed service's recent log tail. It is the one-method slice of the services manager this package needs, so the collection can be tested without a container runtime.
type Report ¶
type Report struct {
Slug string `json:"slug"`
State State `json:"state"`
Reasons []string `json:"reasons"`
}
Report is the producer verdict for one service, ready to hand to the UI. Reasons is what the user is shown; it is populated for every state, including not-checked, because "why don't you know?" is the first question a bare "not checked" provokes.
type ServiceLookup ¶
ServiceLookup finds a catalog entry by slug: *catalog.Catalog, narrowed.
type State ¶
type State string
State is a producer verdict. There are only three, and the missing fourth is the point: "earning" is not among them because no signal here can prove it.
const ( // StateNotChecked means we have no basis for a claim either way: the container is // not running, its service declares no log signals, its logs could not be read, or // they were read and showed nothing known. Not a clean bill of health. StateNotChecked State = "not-checked" // StateIdle means a declared signal says the service is up but doing no paid work. StateIdle State = "idle" // StateFailing means a declared signal says it is broken, or it is restart-looping. StateFailing State = "failing" )
func (State) NotEarning ¶
NotEarning reports whether this verdict is a positive finding that the service is running without earning. StateNotChecked is deliberately false: we did not find it healthy, we found nothing.
type WindowReader ¶ added in v0.25.3
type WindowReader interface {
LogsMatching(ctx context.Context, slug string, since time.Duration, match *regexp.Regexp, lines int) (string, error)
SignalVars(slug string) map[string]string
}
WindowReader reads hours of a service's logs, filtered, and the values its signal texts are filled from. *services.Manager, narrowed.