Documentation
¶
Overview ¶
Package health provides comprehensive health check functionality for Forge microservices.
The health package implements Kubernetes-compatible health checks with support for both liveness and readiness probes. It provides concurrent health check execution, configurable timeouts, and detailed status reporting.
Health Check Types ¶
The package supports two types of health checks:
- Liveness: Indicates whether the application is alive and responding
- Readiness: Indicates whether the application is ready to serve traffic
Basic Usage ¶
Implement the Check interface for your dependencies:
type DatabaseCheck struct {
db *sql.DB
}
func (c *DatabaseCheck) Name() string {
return "database"
}
func (c *DatabaseCheck) Liveness(ctx context.Context) error {
return c.db.PingContext(ctx)
}
func (c *DatabaseCheck) Readiness(ctx context.Context) error {
// More comprehensive readiness check
if err := c.db.PingContext(ctx); err != nil {
return err
}
// Check if migrations are up to date, etc.
return nil
}
Register checks with the health registry:
registry := health.NewRegistry(logger)
config := health.DefaultCheckConfig("database")
registry.Register(&DatabaseCheck{db: db}, config)
HTTP Endpoints ¶
The framework automatically exposes health endpoints:
- /health: Combined liveness and readiness status
- /health/live: Liveness probe endpoint
- /health/ready: Readiness probe endpoint
Concurrent Execution ¶
All health checks are executed concurrently with proper timeout handling. Failed non-required checks don't affect overall service health.
Index ¶
- type AlwaysHealthyCheck
- type AlwaysUnhealthyCheck
- type BasicCheck
- type Check
- type CheckConfig
- type CheckResult
- type HealthStatus
- func (h HealthStatus) FailedChecks() []CheckResult
- func (h HealthStatus) GetHealthySummary() HealthySummary
- func (h HealthStatus) HTTPStatus() int
- func (h HealthStatus) IsHealthy() bool
- func (h HealthStatus) IsLive() bool
- func (h HealthStatus) IsReady() bool
- func (h HealthStatus) JSON() ([]byte, error)
- func (h HealthStatus) RequiredFailedChecks() []CheckResult
- func (h HealthStatus) String() string
- func (h HealthStatus) WithService(service string) HealthStatus
- func (h HealthStatus) WithUptime(uptime time.Duration) HealthStatus
- func (h HealthStatus) WithVersion(version string) HealthStatus
- type HealthySummary
- type Logger
- type NoopLogger
- type Registry
- func (r *Registry) CheckHealth(ctx context.Context) HealthStatus
- func (r *Registry) CheckLiveness(ctx context.Context) HealthStatus
- func (r *Registry) CheckReadiness(ctx context.Context) HealthStatus
- func (r *Registry) GetCheckConfig(name string) (CheckConfig, bool)
- func (r *Registry) GetRegisteredChecks() []string
- func (r *Registry) IsReady() bool
- func (r *Registry) MustRegister(check Check, config CheckConfig)
- func (r *Registry) Register(check Check, config CheckConfig) error
- func (r *Registry) SetReady(ready bool)
- func (r *Registry) Unregister(name string)
- type Status
- type StatusResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AlwaysHealthyCheck ¶
type AlwaysHealthyCheck struct {
// contains filtered or unexported fields
}
AlwaysHealthyCheck is a check that always reports healthy status. Useful for testing or as a placeholder.
func NewAlwaysHealthyCheck ¶
func NewAlwaysHealthyCheck(name string) *AlwaysHealthyCheck
NewAlwaysHealthyCheck creates a check that always reports healthy.
func (*AlwaysHealthyCheck) Liveness ¶
func (c *AlwaysHealthyCheck) Liveness(ctx context.Context) error
Liveness always returns nil (healthy).
func (*AlwaysHealthyCheck) Name ¶
func (c *AlwaysHealthyCheck) Name() string
Name returns the name of the check.
type AlwaysUnhealthyCheck ¶
type AlwaysUnhealthyCheck struct {
// contains filtered or unexported fields
}
AlwaysUnhealthyCheck is a check that always reports unhealthy status. Useful for testing failure scenarios.
func NewAlwaysUnhealthyCheck ¶
func NewAlwaysUnhealthyCheck(name string, err error) *AlwaysUnhealthyCheck
NewAlwaysUnhealthyCheck creates a check that always reports unhealthy.
func (*AlwaysUnhealthyCheck) Liveness ¶
func (c *AlwaysUnhealthyCheck) Liveness(ctx context.Context) error
Liveness always returns an error (unhealthy).
func (*AlwaysUnhealthyCheck) Name ¶
func (c *AlwaysUnhealthyCheck) Name() string
Name returns the name of the check.
type BasicCheck ¶
type BasicCheck struct {
// contains filtered or unexported fields
}
BasicCheck provides a simple implementation of Check interface.
func NewBasicCheck ¶
func NewBasicCheck(config CheckConfig, liveness, readiness func(ctx context.Context) error) *BasicCheck
NewBasicCheck creates a new BasicCheck.
func (*BasicCheck) Config ¶
func (c *BasicCheck) Config() CheckConfig
Config returns the check configuration.
func (*BasicCheck) Liveness ¶
func (c *BasicCheck) Liveness(ctx context.Context) error
Liveness performs the liveness check.
func (*BasicCheck) Name ¶
func (c *BasicCheck) Name() string
Name returns the name of the health check.
type Check ¶
type Check interface {
// Name returns a unique name for this health check.
Name() string
// Liveness performs a liveness check. This should be a fast, lightweight
// check that indicates whether the dependency is alive and responding.
// A failed liveness check typically indicates a need for service restart.
Liveness(ctx context.Context) error
// Readiness performs a readiness check. This can be more comprehensive
// than liveness and indicates whether the dependency is ready to serve
// requests. A failed readiness check should result in the service being
// marked as not ready (but still alive).
Readiness(ctx context.Context) error
}
Check represents a health check that can be performed on a service dependency. Each check supports both liveness (is the dependency alive) and readiness (is the dependency ready to serve requests) semantics.
Implementations should be lightweight and fast, especially for liveness checks. Readiness checks can be more comprehensive but should still complete within the configured timeout.
Health checks are executed concurrently by the health registry, so implementations must be thread-safe.
type CheckConfig ¶
type CheckConfig struct {
// Name is the unique name of the health check
Name string
// Required indicates whether this check is required for readiness.
// If true, the service will not be marked as ready until this check passes.
Required bool
// Timeout is the maximum time to wait for the health check to complete.
Timeout time.Duration
// Interval is how often to perform the check (for periodic checks).
Interval time.Duration
// InitialDelay is how long to wait before performing the first check.
InitialDelay time.Duration
}
CheckConfig contains common configuration for health checks. Use DefaultCheckConfig() as a starting point and customize as needed.
The Required field determines whether a failed check affects overall service health:
- Required=true: Service is unhealthy if this check fails
- Required=false: Check failure is logged but doesn't affect service health
Timeout applies to both liveness and readiness checks for this specific check. The health registry also enforces an overall timeout for all checks combined.
func DefaultCheckConfig ¶
func DefaultCheckConfig(name string) CheckConfig
DefaultCheckConfig returns a CheckConfig with sensible defaults. All checks are marked as required by default with a 5-second timeout and 30-second check interval for periodic monitoring.
Customize the returned config as needed:
config := health.DefaultCheckConfig("database")
config.Required = false // Make non-critical
config.Timeout = 10 * time.Second // Longer timeout
type CheckResult ¶
type CheckResult struct {
Name string `json:"name"`
Status Status `json:"status"`
Message string `json:"message,omitempty"`
Error string `json:"error,omitempty"`
Duration string `json:"duration"`
Timestamp time.Time `json:"timestamp"`
Required bool `json:"required"`
}
CheckResult represents the result of executing a health check.
func NewCheckResult ¶
NewCheckResult creates a new CheckResult.
func (CheckResult) IsHealthy ¶
func (r CheckResult) IsHealthy() bool
IsHealthy returns true if the check result indicates a healthy status.
type HealthStatus ¶
type HealthStatus struct {
Status Status `json:"status"`
Message string `json:"message,omitempty"`
Timestamp time.Time `json:"timestamp"`
Details map[string]CheckResult `json:"details,omitempty"`
Service string `json:"service,omitempty"`
Version string `json:"version,omitempty"`
Uptime string `json:"uptime,omitempty"`
}
HealthStatus represents the overall health status of a service, including aggregated results from individual health checks.
func NewHealthyStatus ¶
func NewHealthyStatus(message string) HealthStatus
NewHealthyStatus creates a new healthy status with the given message.
func NewUnhealthyStatus ¶
func NewUnhealthyStatus(message string) HealthStatus
NewUnhealthyStatus creates a new unhealthy status with the given message.
func NewUnknownStatus ¶
func NewUnknownStatus(message string) HealthStatus
NewUnknownStatus creates a new unknown status with the given message.
func (HealthStatus) FailedChecks ¶
func (h HealthStatus) FailedChecks() []CheckResult
FailedChecks returns a slice of check results that failed.
func (HealthStatus) GetHealthySummary ¶
func (h HealthStatus) GetHealthySummary() HealthySummary
GetHealthySummary returns a summary of the health check results.
func (HealthStatus) HTTPStatus ¶
func (h HealthStatus) HTTPStatus() int
HTTPStatus returns the appropriate HTTP status code for this health status.
func (HealthStatus) IsHealthy ¶
func (h HealthStatus) IsHealthy() bool
IsHealthy returns true if the overall status is healthy.
func (HealthStatus) IsLive ¶
func (h HealthStatus) IsLive() bool
IsLive returns true if the status indicates the service is alive. For liveness checks, we consider the service live if it's not explicitly unhealthy.
func (HealthStatus) IsReady ¶
func (h HealthStatus) IsReady() bool
IsReady returns true if the status indicates the service is ready to serve requests. This is an alias for IsHealthy for readiness checks.
func (HealthStatus) JSON ¶
func (h HealthStatus) JSON() ([]byte, error)
JSON returns the JSON representation of the health status.
func (HealthStatus) RequiredFailedChecks ¶
func (h HealthStatus) RequiredFailedChecks() []CheckResult
RequiredFailedChecks returns a slice of required check results that failed.
func (HealthStatus) String ¶
func (h HealthStatus) String() string
String returns a string representation of the health status.
func (HealthStatus) WithService ¶
func (h HealthStatus) WithService(service string) HealthStatus
WithService sets the service name on the health status.
func (HealthStatus) WithUptime ¶
func (h HealthStatus) WithUptime(uptime time.Duration) HealthStatus
WithUptime sets the uptime on the health status.
func (HealthStatus) WithVersion ¶
func (h HealthStatus) WithVersion(version string) HealthStatus
WithVersion sets the version on the health status.
type HealthySummary ¶
type HealthySummary struct {
Total int `json:"total"`
Healthy int `json:"healthy"`
Unhealthy int `json:"unhealthy"`
Required int `json:"required"`
}
HealthySummary provides a summary of healthy vs unhealthy checks.
type Logger ¶
type Logger interface {
Debug(msg string, fields ...interface{})
Info(msg string, fields ...interface{})
Warn(msg string, fields ...interface{})
Error(msg string, fields ...interface{})
}
Logger interface for health check logging.
type NoopLogger ¶
type NoopLogger struct{}
NoopLogger is a logger that does nothing.
func (NoopLogger) Debug ¶
func (NoopLogger) Debug(msg string, fields ...interface{})
func (NoopLogger) Error ¶
func (NoopLogger) Error(msg string, fields ...interface{})
func (NoopLogger) Info ¶
func (NoopLogger) Info(msg string, fields ...interface{})
func (NoopLogger) Warn ¶
func (NoopLogger) Warn(msg string, fields ...interface{})
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages a collection of health checks and provides methods to check the overall health status of a service.
func NewRegistry ¶
NewRegistry creates a new health check registry.
func (*Registry) CheckHealth ¶
func (r *Registry) CheckHealth(ctx context.Context) HealthStatus
CheckHealth performs both liveness and readiness checks and returns combined results.
func (*Registry) CheckLiveness ¶
func (r *Registry) CheckLiveness(ctx context.Context) HealthStatus
CheckLiveness performs liveness checks on all registered health checks.
func (*Registry) CheckReadiness ¶
func (r *Registry) CheckReadiness(ctx context.Context) HealthStatus
CheckReadiness performs readiness checks on all registered health checks.
func (*Registry) GetCheckConfig ¶
func (r *Registry) GetCheckConfig(name string) (CheckConfig, bool)
GetCheckConfig returns the configuration for a specific check.
func (*Registry) GetRegisteredChecks ¶
GetRegisteredChecks returns the names of all registered checks.
func (*Registry) MustRegister ¶
func (r *Registry) MustRegister(check Check, config CheckConfig)
MustRegister registers a health check and panics if registration fails.
func (*Registry) Register ¶
func (r *Registry) Register(check Check, config CheckConfig) error
Register registers a health check with the registry.
func (*Registry) SetReady ¶
SetReady marks the service as ready. This affects the overall readiness status.
func (*Registry) Unregister ¶
Unregister removes a health check from the registry.
type StatusResponse ¶
type StatusResponse struct {
Status Status `json:"status"`
Message string `json:"message,omitempty"`
}
StatusResponse is a simplified response for basic health checks.
func NewStatusResponse ¶
func NewStatusResponse(status HealthStatus) StatusResponse
NewStatusResponse creates a new status response from a health status.
func (StatusResponse) HTTPStatus ¶
func (s StatusResponse) HTTPStatus() int
HTTPStatus returns the appropriate HTTP status code.
func (StatusResponse) JSON ¶
func (s StatusResponse) JSON() ([]byte, error)
JSON returns the JSON representation of the status response.
Source Files