Documentation
¶
Index ¶
- Constants
- Variables
- func ActiveDeploymentErrorsByService(tasks []swarm.Task) map[string]string
- func AttemptOrder(t swarm.Task) time.Time
- func IsTerminal(state string) bool
- func LatestTasksByServiceKey(tasks []swarm.Task) []swarm.Task
- func TaskKeyForService(t swarm.Task) string
- func TaskRowStyle(t docker.TaskEntry, base lipgloss.Style) lipgloss.Style
- func TaskTimestamp(t swarm.Task) time.Time
- type HealthReason
- type HealthState
- type SwarmHealth
Constants ¶
const ( ReasonDeploymentError = "deployment-error" ReasonNode = "node" ReasonReplicas = "replicas" ReasonRollout = "rollout" )
Reason kinds. The first two make a swarm degraded, the last two converging.
Variables ¶
var ( // ConvergingStyle tints a service or stack row that is converging and not // failing (see AssessSwarm): the yellow a starting task already gets, so a // row and the tasks beneath it say the same thing. ConvergingStyle = taskStoppedStyle )
Functions ¶
func ActiveDeploymentErrorsByService ¶
ActiveDeploymentErrorsByService returns serviceID -> error text for every service with a slot whose failure nothing has since undone: an error task newer than that slot's last sign of life, or with no sign of life at all.
A slot shows a sign of life two ways. A task that both wants to run and is running is the rolling-update case — the outgoing generation failed, the old task is still up. A task that ran to completion is the run-to-completion case: a `..._init` service exits 0, is never restarted, and never has a running task for a later attempt to be compared against, so a failure before that success would otherwise be reported forever (PR #633 review).
Only errors within 5 minutes of that service's own newest task are considered, so a rollout that eventually settled stops being news. The window follows the service rather than the cluster: a service that broke weeks ago and has not been rescheduled since is still broken, however busy its neighbours are. When multiple slots error for the same service, the most recent error wins.
func AttemptOrder ¶ added in v2.0.1
AttemptOrder returns the clock that orders one slot's attempts against each other: when swarm created the task. Status.Timestamp answers a different question — when the task last changed state — and the two disagree whenever a finished task's status is touched again afterwards, which is how a service whose newest run succeeded kept reporting an older failure (PR #633 review). The task list sorts by CreatedAt too, so the service row and the rows beneath it cannot contradict each other. Falls back to Status.Timestamp for a task with no creation time.
func IsTerminal ¶ added in v2.0.1
IsTerminal reports whether a swarm task state means the task is over: it will not run again, and its container has exited if it ever started. The services view reads it to stop showing a container state that has nothing left to say — on a task that is already over, "exited" is not news, and whether the cell can say it at all turns on whether the node has pruned the container yet (issue #616).
func LatestTasksByServiceKey ¶
LatestTasksByServiceKey returns the most relevant task per slot. Tasks that want to be running are preferred over terminal tasks; within the same tier the most recently created task wins — attempt order, the same clock ActiveDeploymentErrorsByService and the task list use, so the two cannot disagree about which attempt is a slot's current one.
func TaskKeyForService ¶
TaskKeyForService returns a unique key for a task's slot within its service. For replicated services this is serviceID:slot, for global services serviceID:nodeID.
func TaskRowStyle ¶
TaskRowStyle tints one task row by what the row is telling the operator, and returns base for a task with nothing to say. Red is kept for a task that went wrong — it failed, was rejected, orphaned, recorded an error, or its healthcheck is failing. A task swarm stopped on purpose gets yellow: that happens on every update, scale-down and node drain, and the container's docker-ps state is "exited" for it exactly as it is for a crash, so the swarm task state is what tells the two apart (issue #601).
base is the caller's normal row style rather than a colour of ours: the three views showing tasks each render an ordinary row in their own colour, and only the two exceptional tints are shared.
Types ¶
type HealthReason ¶ added in v2.2.0
type HealthReason struct {
Kind string `json:"kind"`
ID string `json:"id"`
Name string `json:"name"`
Detail string `json:"detail"`
}
HealthReason names one service or node behind a verdict.
type HealthState ¶ added in v2.2.0
type HealthState string
HealthState is the swarm-level verdict: the colour a client gives the whole swarm, or the part of it a view shows.
const ( HealthHealthy HealthState = "healthy" // HealthConverging means nothing is failing, but swarm has not finished: // a service is short of its target or a rollout has not settled. HealthConverging HealthState = "converging" // HealthDegraded means something is failing — a service with an active // deployment error, or an unhealthy node. It wins over converging. HealthDegraded HealthState = "degraded" // HealthUnknown means there is nothing to judge: no snapshot, or a locked // swarm whose entity lists are empty until it is unlocked. HealthUnknown HealthState = "unknown" )
type SwarmHealth ¶ added in v2.2.0
type SwarmHealth struct {
State HealthState `json:"state"`
Failing []HealthReason `json:"failing"`
Converging []HealthReason `json:"converging"`
}
SwarmHealth is the verdict and every reason behind it, each list sorted by kind, then name, then ID. A service with an active deployment error is listed only as failing, never also as converging.
func AssessSwarm ¶ added in v2.2.0
func AssessSwarm(snap *docker.SwarmSnapshot) SwarmHealth
AssessSwarm judges a snapshot by the rules the views already apply, so the verdict cannot disagree with a row: ActiveDeploymentErrorsByService and NodeEntry.UnhealthyReason decide failing, and StackConvergence's counts — which already leave out drained and down nodes — decide converging.
A service is converging when it is not failing and either
- it has fewer tasks done than desired: running (or completed, for a restart-none/on-failure job) for a service, completed in the current iteration for a native job, so a finished job is settled and a running one is not; a one-shot whose task died is excluded, since it will never converge and is reported as a deployment error instead; or
- its rollout is unsettled: updating, rollback_started, paused or rollback_paused. A paused rollout counts because it is unfinished and nothing in it is failing any more — while its task still fails, the deployment error makes it degraded. A job's "paused" is ignored, as charts.ServiceState.Convergence ignores it: swarm pauses every re-run one-shot, so it says nothing about the job. So is a pause every slot has outgrown: swarm never clears the state itself, but once tasks created after the update started meet the target, running on active nodes, restarts have rolled the current spec out and nothing is left unfinished.
The monitor window is deliberately not consulted: it depends on the clock, and a verdict clients share must be a function of the snapshot alone.
Source Files