Documentation
¶
Overview ¶
Package health provides upstream health monitoring with active probes, passive failure tracking, and health check history.
Index ¶
- Constants
- type CheckResult
- type Config
- type Event
- type HealthPathProvider
- type History
- func (hh *History) Get(targetID string) []CheckResult
- func (hh *History) GetSince(targetID string, since time.Time) []CheckResult
- func (hh *History) Record(result CheckResult)
- func (hh *History) Summary(targetID string) Summary
- func (hh *History) Targets() []string
- func (hh *History) UptimePercent(targetID string, window time.Duration) float64
- type Monitor
- func (hm *Monitor) Deregister(targetID string)
- func (hm *Monitor) Health(_ context.Context) error
- func (hm *Monitor) RecordPassiveFailure(targetID string)
- func (hm *Monitor) RecordPassiveSuccess(targetID string)
- func (hm *Monitor) Register(routeID string, target Target)
- func (hm *Monitor) SetMetrics(m *observability.Metrics)
- func (hm *Monitor) SetOnHealthChange(fn func(event Event))
- func (hm *Monitor) Start(ctx context.Context)
- func (hm *Monitor) Stop()
- func (hm *Monitor) Tracks(targetID string) bool
- type Summary
- type Target
Constants ¶
const DefaultPath = "/_/health"
DefaultPath is the path probed when neither Config.Path nor the target names one. It is the path Forge services serve their health on.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CheckResult ¶
type CheckResult struct {
TargetID string `json:"targetId"`
TargetURL string `json:"targetUrl"`
Healthy bool `json:"healthy"`
Latency time.Duration `json:"latency"`
Error string `json:"error,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
CheckResult records a single health check outcome.
type Config ¶
type Config struct {
Enabled bool `json:"enabled" yaml:"enabled"`
Interval time.Duration `json:"interval" yaml:"interval"`
Timeout time.Duration `json:"timeout" yaml:"timeout"`
Path string `json:"path" yaml:"path"`
FailureThreshold int `json:"failureThreshold" yaml:"failure_threshold"`
SuccessThreshold int `json:"successThreshold" yaml:"success_threshold"`
EnablePassive bool `json:"enablePassive" yaml:"enable_passive"`
PassiveFailThreshold int `json:"passiveFailThreshold" yaml:"passive_fail_threshold"`
}
Config configures upstream health checking.
Path is the health endpoint probed on every target that does not name its own (see HealthPathProvider). Leave it empty and the monitor still probes DefaultPath, but more leniently: any status below 500 counts as up, so an upstream that doesn't serve DefaultPath (and answers 404 or 401) keeps its route. A 5xx, a refused connection or a timeout still counts as a failure, which keeps a Forge service reporting 503 on its health endpoint out of rotation. Set Path, or give the target a health path, and the probe is strict: a status outside 200-399 fails it.
type Event ¶
type Event struct {
TargetID string `json:"targetId"`
TargetURL string `json:"targetUrl"`
Healthy bool `json:"healthy"`
Previous bool `json:"previous"`
RouteID string `json:"routeId"`
Timestamp time.Time `json:"timestamp"`
}
Event represents an upstream health change.
type HealthPathProvider ¶
type HealthPathProvider interface {
HealthPath() string
}
HealthPathProvider is an optional interface that targets can implement to specify a custom health check path instead of the global default. If a target implements this interface and returns a non-empty string, that path is used for health checks instead of the monitor's global Config.Path.
type History ¶
type History struct {
// contains filtered or unexported fields
}
History keeps a fixed-size ring buffer of health check results per upstream target. It is safe for concurrent use.
func NewHistory ¶
NewHistory creates a history tracker that stores up to capacity results per target.
func (*History) Get ¶
func (hh *History) Get(targetID string) []CheckResult
Get returns all recorded results for a target in chronological order.
func (*History) GetSince ¶
func (hh *History) GetSince(targetID string, since time.Time) []CheckResult
GetSince returns results for a target after the given time.
func (*History) Record ¶
func (hh *History) Record(result CheckResult)
Record stores a health check result.
type Monitor ¶
type Monitor struct {
// contains filtered or unexported fields
}
Monitor monitors the health of upstream targets.
func NewMonitor ¶
NewMonitor creates a new health monitor.
func (*Monitor) Deregister ¶
Deregister removes a target from health monitoring.
func (*Monitor) Health ¶
Health returns an error if no targets are healthy (for HealthManager integration).
func (*Monitor) RecordPassiveFailure ¶
RecordPassiveFailure records a passive health check failure.
func (*Monitor) RecordPassiveSuccess ¶
RecordPassiveSuccess records a passive health check success.
func (*Monitor) SetMetrics ¶
func (hm *Monitor) SetMetrics(m *observability.Metrics)
SetMetrics sets where the monitor records its metrics: the duration of each check cycle and how many targets are healthy. Nil records none.
func (*Monitor) SetOnHealthChange ¶
SetOnHealthChange sets the health change callback.
type Summary ¶
type Summary struct {
TargetID string `json:"targetId"`
TotalChecks int `json:"totalChecks"`
HealthyChecks int `json:"healthyChecks"`
UptimePercent float64 `json:"uptimePercent"`
AvgLatency time.Duration `json:"avgLatency"`
LastCheck *CheckResult `json:"lastCheck,omitempty"`
}
Summary provides a summary of health check history for a target.