health

package
v1.78.3 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2024 License: BSD-3-Clause Imports: 22 Imported by: 24

Documentation

Overview

Package health is a registry for other packages to report & check overall health status of the node.

Index

Constants

View Source 
const (
	// SysRouter is the name of the wgengine/router subsystem.
	SysRouter = Subsystem("router")

	// SysDNS is the name of the net/dns subsystem.
	SysDNS = Subsystem("dns")

	// SysDNSManager is the name of the net/dns manager subsystem.
	SysDNSManager = Subsystem("dns-manager")

	// SysTKA is the name of the tailnet key authority subsystem.
	SysTKA = Subsystem("tailnet-lock")
)
View Source 
const MetricLabelWarning = "warning"

Variables

View Source 
var IPNStateWarnable = Register(&Warnable{
	Code:     "wantrunning-false",
	Title:    "Tailscale off",
	Severity: SeverityLow,
	Text:     StaticMessage("Tailscale is stopped."),
})

IPNStateWarnable is a Warnable that warns the user that Tailscale is stopped.

View Source 
var LoginStateWarnable = Register(&Warnable{
	Code:     "login-state",
	Title:    "Logged out",
	Severity: SeverityMedium,
	Text: func(args Args) string {
		if args[ArgError] != "" {
			return fmt.Sprintf("You are logged out. The last login error was: %v", args[ArgError])
		} else {
			return "You are logged out."
		}
	},
	DependsOn: []*Warnable{IPNStateWarnable},
})

LoginStateWarnable is a Warnable that warns the user that they are logged out, and provides the last login error if available.

View Source 
var NetworkStatusWarnable = Register(&Warnable{
	Code:                "network-status",
	Title:               "Network down",
	Severity:            SeverityMedium,
	Text:                StaticMessage("Tailscale cannot connect because the network is down. Check your Internet connection."),
	ImpactsConnectivity: true,
	TimeToVisible:       5 * time.Second,
})

NetworkStatusWarnable is a Warnable that warns the user that the network is down.

Functions

func DebugHandler added in v1.20.0 

func DebugHandler(typ string) http.Handler

func RegisterDebugHandler added in v1.20.0 

func RegisterDebugHandler(typ string, h http.Handler)

func StaticMessage added in v1.70.0 

func StaticMessage(s string) func(Args) string

StaticMessage returns a function that always returns the input string, to be used in simple Warnables that do not use the Args map to generate their Text.

Types

type Arg added in v1.70.0 

type Arg string

Arg is a type for the key to be used in the Args of a Warnable. 

const (
	// ArgAvailableVersion provides an update notification Warnable with the available version of the Tailscale client.
	ArgAvailableVersion Arg = "available-version"

	// ArgCurrentVersion provides an update notification Warnable with the current version of the Tailscale client.
	ArgCurrentVersion Arg = "current-version"

	// ArgDuration provides a Warnable with how long the Warnable has been in an unhealthy state.
	ArgDuration Arg = "duration"

	// ArgError provides a Warnable with the underlying error behind an unhealthy state.
	ArgError Arg = "error"

	// ArgMagicsockFunctionName provides a Warnable with the name of the Magicsock function that caused the unhealthy state.
	ArgMagicsockFunctionName Arg = "magicsock-function-name"

	// ArgDERPRegionID provides a Warnable with the ID of a DERP server involved in the unhealthy state.
	ArgDERPRegionID Arg = "derp-region-id"

	// ArgDERPRegionName provides a Warnable with the name of a DERP server involved in the unhealthy state.
	// It is used to show a more friendly message like "the Seattle relay server failed to connect" versus
	// "relay server 10 failed to connect".
	ArgDERPRegionName Arg = "derp-region-name"

	// ArgServerName provides a Warnable with the hostname of a server involved in the unhealthy state.
	ArgServerName Arg = "server-name"

	// ArgServerName provides a Warnable with comma delimited list of the hostname of the servers involved in the unhealthy state.
	// If no nameservers were available to query, this will be an empty string.
	ArgDNSServers Arg = "dns-servers"
)

type Args added in v1.70.0 

type Args map[Arg]string

Args is a map of Args to string values that can be used to provide parameters regarding the unhealthy state of a Warnable. For instance, if you have a Warnable to track the health of DNS lookups, here you can include the hostname that failed to resolve, or the IP address of the DNS server that has been failing to respond. You can then use these parameters in the Text function of the Warnable to provide a detailed error message to the user.

type ReceiveFunc added in v1.66.0 

type ReceiveFunc int

ReceiveFunc is one of the three magicsock Receive funcs (IPv4, IPv6, or DERP). 

const (
	ReceiveIPv4 ReceiveFunc = 0
	ReceiveIPv6 ReceiveFunc = 1
	ReceiveDERP ReceiveFunc = 2
)

ReceiveFunc indices for Tracker.MagicSockReceiveFuncs.

func (ReceiveFunc) String added in v1.66.0 

func (f ReceiveFunc) String() string

type ReceiveFuncStats added in v1.8.0 

type ReceiveFuncStats struct {
	// contains filtered or unexported fields
}

ReceiveFuncStats tracks the calls made to a wireguard-go receive func.

func (*ReceiveFuncStats) Enter added in v1.8.0 

func (s *ReceiveFuncStats) Enter()

func (*ReceiveFuncStats) Exit added in v1.8.0 

func (s *ReceiveFuncStats) Exit()

func (*ReceiveFuncStats) Name added in v1.72.0 

func (s *ReceiveFuncStats) Name() string

Name returns the name of the receive func ("ReceiveIPv4", "ReceiveIPv6", etc).

type Severity added in v1.70.0 

type Severity string

Severity represents how serious an error is. Each GUI interprets this severity value in different ways, to surface the error in a more or less visible way. For instance, the macOS GUI could change its menubar icon to display an exclamation mark and present a modal notification for SeverityHigh warnings, but not for SeverityLow messages, which would only appear in the Settings window. 

const (
	// SeverityHigh is the highest severity level, used for critical errors that need immediate attention.
	// On platforms where the client GUI can deliver notifications, a SeverityHigh Warnable will trigger
	// a modal notification.
	SeverityHigh Severity = "high"
	// SeverityMedium is used for errors that are important but not critical. This won't trigger a modal
	// notification, however it will be displayed in a more visible way than a SeverityLow Warnable.
	SeverityMedium Severity = "medium"
	// SeverityLow is used for less important notices that don't need immediate attention. The user will
	// have to go to a Settings window, or another "hidden" GUI location to see these messages.
	SeverityLow Severity = "low"
)

type State added in v1.70.0 

type State struct {
	// Each key-value pair in Warnings represents a Warnable that is currently
	// unhealthy. If a Warnable is healthy, it will not be present in this map.
	// When a Warnable is unhealthy and becomes healthy, its key-value pair
	// disappears in the next issued State. Observers should treat the absence of
	// a WarnableCode in this map as an indication that the Warnable became healthy,
	// and may use that to clear any notifications that were previously shown to the user.
	// If Warnings is nil, all Warnables are healthy and the backend is overall healthy.
	Warnings map[WarnableCode]UnhealthyState
}

State contains the health status of the backend, and is provided to the client UI via LocalAPI through ipn.Notify.

type Subsystem deprecated added in v1.6.0 

type Subsystem string

Subsystem is the name of a subsystem whose health can be monitored.

Deprecated: Registering a Warnable using Register() and updating its health state with SetUnhealthy() and SetHealthy() should be preferred.

func (Subsystem) Warnable added in v1.70.0 

func (s Subsystem) Warnable() *Warnable

Warnable returns a Warnable representing a legacy Subsystem. This is used temporarily (2024-06-14) while we migrate the old health infrastructure based on Subsystems to the new Warnables architecture.

type Tracker added in v1.66.0 

type Tracker struct {
	// MagicSockReceiveFuncs tracks the state of the three
	// magicsock receive functions: IPv4, IPv6, and DERP.
	MagicSockReceiveFuncs [3]ReceiveFuncStats // indexed by ReceiveFunc values
	// contains filtered or unexported fields
}

Tracker tracks the health of various Tailscale subsystems, comparing each subsystems' state with each other to make sure they're consistent based on the user's intended state.

func (*Tracker) AppendWarnableDebugFlags added in v1.66.0 

func (t *Tracker) AppendWarnableDebugFlags(base []string) []string

AppendWarnableDebugFlags appends to base any health items that are currently in failed state and were created with MapDebugFlag.

func (*Tracker) CurrentState added in v1.70.0 

func (t *Tracker) CurrentState() *State

CurrentState returns a snapshot of the current health status of the backend. It returns a State with nil Warnings if the backend is healthy (all Warnables have no issues). The returned State is a snapshot of shared memory, and the caller should not mutate the returned value.

func (*Tracker) DNSHealth deprecated added in v1.66.0 

func (t *Tracker) DNSHealth() error

DNSHealth returns the net/dns.Manager error state.

Deprecated: Warnables should be preferred over Subsystem errors.

func (*Tracker) GetDERPRegionReceivedTime added in v1.66.0 

func (t *Tracker) GetDERPRegionReceivedTime(region int) time.Time

GetDERPRegionReceivedTime returns the last time that a frame was received from the given DERP region, or the zero time if no communication with that region has occurred.

func (*Tracker) GetInPollNetMap added in v1.66.0 

func (t *Tracker) GetInPollNetMap() bool

GetInPollNetMap reports whether the client has an open HTTP long poll open to the control plane.

func (*Tracker) GotStreamedMapResponse added in v1.66.0 

func (t *Tracker) GotStreamedMapResponse()

GotStreamedMapResponse notes that we got a tailcfg.MapResponse message in streaming mode, even if it's just a keep-alive message.

This also notes that a map poll is in progress. To unset that, call SetOutOfPollNetMap().

func (*Tracker) LastNoiseDialWasRecent added in v1.76.0 

func (t *Tracker) LastNoiseDialWasRecent() bool

LastNoiseDialWasRecent notes that we're attempting to dial control via the ts2021 noise protocol and reports whether the prior dial was "recent" (currently defined as 2 minutes but subject to change).

If t is nil, it reports false.

func (*Tracker) NoteDERPRegionReceivedFrame added in v1.66.0 

func (t *Tracker) NoteDERPRegionReceivedFrame(region int)

NoteDERPRegionReceivedFrame is called to note that a frame was received from the given DERP region at the current time.

func (*Tracker) NoteMapRequestHeard added in v1.66.0 

func (t *Tracker) NoteMapRequestHeard(mr *tailcfg.MapRequest)

NoteMapRequestHeard notes whenever we successfully sent a map request to control for which we received a 200 response.

func (*Tracker) OverallError added in v1.66.0 

func (t *Tracker) OverallError() error

OverallError returns a summary of the health state.

If there are multiple problems, the error will be of type multierr.Error.

func (*Tracker) ReceiveFuncStats added in v1.66.0 

func (t *Tracker) ReceiveFuncStats(which ReceiveFunc) *ReceiveFuncStats

ReceiveFuncStats returns the ReceiveFuncStats tracker for the given func type.

If t is nil, it returns nil.

func (*Tracker) RegisterWatcher added in v1.66.0 

func (t *Tracker) RegisterWatcher(cb func(w *Warnable, r *UnhealthyState)) (unregister func())

RegisterWatcher adds a function that will be called whenever the health state of any Warnable changes. If a Warnable becomes unhealthy or its unhealthy state is updated, the callback will be called with its current Representation. If a Warnable becomes healthy, the callback will be called with ws set to nil. The provided callback function will be executed in its own goroutine. The returned function can be used to unregister the callback.

func (*Tracker) RouterHealth deprecated added in v1.66.0 

func (t *Tracker) RouterHealth() error

RouterHealth returns the wgengine/router.Router error state.

Deprecated: Warnables should be preferred over Subsystem errors.

func (*Tracker) SetAnyInterfaceUp added in v1.66.0 

func (t *Tracker) SetAnyInterfaceUp(up bool)

SetAnyInterfaceUp sets whether any network interface is up.

func (*Tracker) SetAuthRoutineInError added in v1.66.0 

func (t *Tracker) SetAuthRoutineInError(err error)

SetAuthRoutineInError records the latest error encountered as a result of a login attempt. Providing a nil error indicates successful login, or that being logged in w/coordination is not currently desired.

func (*Tracker) SetAutoUpdatePrefs added in v1.70.0 

func (t *Tracker) SetAutoUpdatePrefs(check bool, apply opt.Bool)

SetAutoUpdatePrefs sets the client auto-update preferences. The arguments match the fields of ipn.AutoUpdatePrefs, but we cannot pass that struct directly due to a circular import.

func (*Tracker) SetControlHealth added in v1.66.0 

func (t *Tracker) SetControlHealth(problems []string)

func (*Tracker) SetDERPMap added in v1.70.0 

func (t *Tracker) SetDERPMap(dm *tailcfg.DERPMap)

SetDERPMap sets the last fetched DERP map in the Tracker. The DERP map is used to provide a region name in user-facing DERP-related warnings.

func (*Tracker) SetDERPRegionConnectedState added in v1.66.0 

func (t *Tracker) SetDERPRegionConnectedState(region int, connected bool)

func (*Tracker) SetDERPRegionHealth added in v1.66.0 

func (t *Tracker) SetDERPRegionHealth(region int, problem string)

SetDERPRegionHealth sets or clears any problem associated with the provided DERP region.

func (*Tracker) SetDNSHealth deprecated added in v1.66.0 

func (t *Tracker) SetDNSHealth(err error)

SetDNSHealth sets the state of the net/dns.Manager

Deprecated: Warnables should be preferred over Subsystem errors.

func (*Tracker) SetDNSManagerHealth deprecated added in v1.66.0 

func (t *Tracker) SetDNSManagerHealth(err error)

SetDNSManagerHealth sets the state of the Linux net/dns manager's discovery of the /etc/resolv.conf situation.

Deprecated: Warnables should be preferred over Subsystem errors.

func (*Tracker) SetHealthy added in v1.70.0 

func (t *Tracker) SetHealthy(w *Warnable)

SetHealthy removes any warningState for the given Warnable.

func (*Tracker) SetIPNState added in v1.66.0 

func (t *Tracker) SetIPNState(state string, wantRunning bool)

state is an ipn.State.String() value: "Running", "Stopped", "NeedsLogin", etc.

func (*Tracker) SetLatestVersion added in v1.66.0 

func (t *Tracker) SetLatestVersion(v *tailcfg.ClientVersion)

SetLatestVersion records the latest version of the Tailscale client. v can be nil if unknown.

func (*Tracker) SetLocalLogConfigHealth added in v1.66.0 

func (t *Tracker) SetLocalLogConfigHealth(err error)

SetLocalLogConfigHealth sets the error state of this client's local log configuration.

func (*Tracker) SetMagicSockDERPHome added in v1.66.0 

func (t *Tracker) SetMagicSockDERPHome(region int, homeless bool)

SetMagicSockDERPHome notes what magicsock's view of its home DERP is.

The homeless parameter is whether magicsock is running in DERP-disconnected mode, without discovering and maintaining a connection to its home DERP.

func (*Tracker) SetMetricsRegistry added in v1.76.0 

func (t *Tracker) SetMetricsRegistry(reg *usermetric.Registry)

SetMetricsRegistry sets up the metrics for the Tracker. It takes a usermetric.Registry and registers the metrics there.

func (*Tracker) SetOutOfPollNetMap added in v1.66.0 

func (t *Tracker) SetOutOfPollNetMap()

SetOutOfPollNetMap records that the client is no longer in an HTTP map request long poll to the control plane.

func (*Tracker) SetRouterHealth deprecated added in v1.66.0 

func (t *Tracker) SetRouterHealth(err error)

SetRouterHealth sets the state of the wgengine/router.Router.

Deprecated: Warnables should be preferred over Subsystem errors.

func (*Tracker) SetTKAHealth deprecated added in v1.66.0 

func (t *Tracker) SetTKAHealth(err error)

SetTKAHealth sets the health of the tailnet key authority.

Deprecated: Warnables should be preferred over Subsystem errors.

func (*Tracker) SetTLSConnectionError added in v1.66.0 

func (t *Tracker) SetTLSConnectionError(host string, err error)

SetTLSConnectionError sets the error state for connections to a specific host. Setting the error to nil will clear any previously-set error.

func (*Tracker) SetUDP4Unbound added in v1.66.0 

func (t *Tracker) SetUDP4Unbound(unbound bool)

SetUDP4Unbound sets whether the udp4 bind failed completely.

func (*Tracker) SetUnhealthy added in v1.70.0 

func (t *Tracker) SetUnhealthy(w *Warnable, args Args)

SetUnhealthy sets a warningState for the given Warnable with the provided Args, and should be called when a Warnable becomes unhealthy, or its unhealthy status needs to be updated. SetUnhealthy takes ownership of args. The args can be nil if no additional information is needed for the unhealthy state.

func (*Tracker) Strings added in v1.70.0 

func (t *Tracker) Strings() []string

Strings() returns a string array containing the Text of all Warnings currently known to the Tracker. These strings can be presented to the user, although ideally you would use the Code property on each Warning to show a localized version of them instead. This function is here for legacy compatibility purposes and is deprecated.

func (*Tracker) TKAHealth deprecated added in v1.66.0 

func (t *Tracker) TKAHealth() error

TKAHealth returns the tailnet key authority error state.

Deprecated: Warnables should be preferred over Subsystem errors.

type UnhealthyState added in v1.70.0 

type UnhealthyState struct {
	WarnableCode        WarnableCode
	Severity            Severity
	Title               string
	Text                string
	BrokenSince         *time.Time     `json:",omitempty"`
	Args                Args           `json:",omitempty"`
	DependsOn           []WarnableCode `json:",omitempty"`
	ImpactsConnectivity bool           `json:",omitempty"`
}

UnhealthyState contains information to be shown to the user to inform them that a Warnable is currently unhealthy.

type Warnable added in v1.34.0 

type Warnable struct {
	// Code is a string that uniquely identifies this Warnable across the entire Tailscale backend,
	// and can be mapped to a user-displayable localized string.
	Code WarnableCode
	// Title is a string that the GUI uses as title for any message involving this Warnable. The title
	// should be short and fit in a single line.
	Title string
	// Text is a function that generates an extended string that the GUI will display to the user when
	// this Warnable is in an unhealthy state. The function can use the Args map to provide dynamic
	// information to the user.
	Text func(args Args) string
	// Severity is the severity of the Warnable, which the GUI can use to determine how to display it.
	// For instance, a Warnable with SeverityHigh could trigger a modal view, while a Warnable with
	// SeverityLow could be displayed in a less intrusive way.
	// TODO(angott): turn this into a SeverityFunc, which allows the Warnable to change its severity based on
	// the Args of the unhappy state, just like we do in the Text function.
	Severity Severity
	// DependsOn is a set of Warnables that this Warnable depends, on and need to be healthy
	// before this Warnable can also be healthy again. The GUI can use this information to ignore
	// this Warnable if one of its dependencies is unhealthy.
	DependsOn []*Warnable

	// MapDebugFlag is a MapRequest.DebugFlag that is sent to control when this Warnable is unhealthy
	//
	// Deprecated: this is only used in one case, and will be removed in a future PR
	MapDebugFlag string

	// ImpactsConnectivity is whether this Warnable in an unhealthy state will impact the user's
	// ability to connect to the Internet or other nodes on the tailnet. On platforms where
	// the client GUI supports a tray icon, the client will display an exclamation mark
	// on the tray icon when ImpactsConnectivity is set to true and the Warnable is unhealthy.
	ImpactsConnectivity bool

	// TimeToVisible is the Duration that the Warnable has to be in an unhealthy state before it
	// should be surfaced as unhealthy to the user. This is used to prevent transient errors from being
	// displayed to the user.
	TimeToVisible time.Duration
}

A Warnable is something that we might want to warn the user about, or not. A Warnable is either in an healthy or unhealth state. A Warnable is unhealthy if the Tracker knows about a WarningState affecting the Warnable. In most cases, Warnables are components of the backend (for instance, "DNS" or "Magicsock"). Warnables are similar to the Subsystem type previously used in this package, but they provide a unique identifying code for each Warnable, along with more metadata that makes it easier for a GUI to display the Warnable in a user-friendly way.

func Register added in v1.70.0 

func Register(w *Warnable) *Warnable

Register registers a new Warnable with the health package and returns it. Register panics if the Warnable was already registered, because Warnables should be unique across the program.

func (*Warnable) IsVisible added in v1.70.0 

func (w *Warnable) IsVisible(ws *warningState) bool

IsVisible returns whether the Warnable should be visible to the user, based on the TimeToVisible field of the Warnable and the BrokenSince time when the Warnable became unhealthy.

type WarnableCode added in v1.70.0 

type WarnableCode string

WarnableCode is a string that distinguishes each Warnable from others. It is globally unique within the program.

Source Files

View all Source files

Directories

Path Synopsis
Package healthmsg contains some constants for health messages.
 Package healthmsg contains some constants for health messages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.