Why Health Checks Matter

Features

Installation

go get -u github.com/kazhuravlev/healthcheck

Quick Start

package mainimport ("context""errors""math/rand""time""github.com/kazhuravlev/healthcheck")funcmain() {ctx:=context.TODO()// 1. Create healthcheck instancehc,_:=healthcheck.New()// 2. Register a simple checkhc.Register(ctx,healthcheck.NewBasic("redis",time.Second,func(ctx context.Context)error {ifrand.Float64()>0.5 {returnerrors.New("service is not available")}returnnil}))// 3. Start HTTP serverserver,_:=healthcheck.NewServer(hc,healthcheck.WithPort(8080))_=server.Run(ctx)// 4. Check health at http://localhost:8080/readyselect {}}

Types of Health Checks

1. Basic Checks (Synchronous)

// Database connectivity checkdbCheck:=healthcheck.NewBasic("postgres",time.Second,func (ctx context.Context)error {returndb.PingContext(ctx)})

2. Background Checks (Asynchronous)

// External API health check - runs every 30 secondsapiCheck:=healthcheck.NewBackground("payment-api",nil,// initial error state5*time.Second,// initial delay30*time.Second,// check interval5*time.Second,// timeout per checkfunc (ctx context.Context)error {resp,err:=client.Get("https://api.payment.com/health")iferr!=nil {returnerr    }deferresp.Body.Close()ifresp.StatusCode!=200 {returnerrors.New("unhealthy")    }returnnil  },)

3. Manual Checks

// Cache warming checkcacheCheck:=healthcheck.NewManual("cache-warmed")hc.Register(ctx,cacheCheck)// Set unhealthy during startupcacheCheck.SetErr(errors.New("cache warming in progress"))// After cache is warmedcacheCheck.SetErr(nil)

Best Practices

1. Choose the Right Check Type

2. Set Appropriate Timeouts

// ❌ Bad: Too long timeout blocks readiness. Timeout should less than timeout in k8shealthcheck.NewBasic("db",30*time.Second,checkFunc)// ✅ Good: Short timeouthealthcheck.NewBasic("db",1*time.Second,checkFunc)

3. Use Status Codes Correctly

4. Add Context to Errors

funccheckDatabase(ctx context.Context)error {iferr:=db.PingContext(ctx);err!=nil {// Use fmt.Errorf to add context. It will be available in /ready reportreturnfmt.Errorf("postgres connection failed: %w",err)  }returnnil}

5. Graceful Shutdown

// Create healthcheck instancehc,_:=healthcheck.New()// Register your normal checkshc.Register(ctx,healthcheck.NewBasic("database",time.Second,checkDB))// Start HTTP serverserver,_:=healthcheck.NewServer(hc,healthcheck.WithPort(8080))_=server.Run(ctx)// In your graceful shutdown handlerfuncgracefulShutdown(hc*healthcheck.Healthcheck) {// Mark application as shutting down - /ready will return 500hc.Shutdown()// Continue with your normal shutdown process// - Stop accepting new requests// - Complete existing requests// - Close database connections, etc.}

6. Monitor Checks

hc,_:=healthcheck.New(healthcheck.WithCheckStatusHook(func (namestring,status healthcheck.Status) {// hcMetric can be a prometheus metric - it is up to your infrastructurehcMetric.WithLabelValues(name,string(status)).Set(1)  }),)

Complete Example

package mainimport ("context""database/sql""fmt""log""time""github.com/kazhuravlev/healthcheck"_"github.com/lib/pq")funcmain() {ctx:=context.Background()// Initialize dependenciesdb,err:=sql.Open("postgres","postgres://localhost/myapp")iferr!=nil {log.Fatal(err)}// Create healthcheckhc,_:=healthcheck.New()// 1. Database check - synchronous, criticalhc.Register(ctx,healthcheck.NewBasic("postgres",time.Second,func(ctx context.Context)error {returndb.PingContext(ctx)}))// 2. Cache warmup - manual controlcacheReady:=healthcheck.NewManual("cache")hc.Register(ctx,cacheReady)cacheReady.SetErr(fmt.Errorf("warming up"))// 3. External API - background checkhc.Register(ctx,healthcheck.NewBackground("payment-provider",nil,10*time.Second,// initial delay30*time.Second,// check interval5*time.Second,// timeoutcheckPaymentProvider,))// Start health check serverserver,_:=healthcheck.NewServer(hc,healthcheck.WithPort(8080))iferr:=server.Run(ctx);err!=nil {log.Fatal(err)}// Simulate cache warmup completiongofunc() {time.Sleep(5*time.Second)cacheReady.SetErr(nil)log.Println("Cache warmed up")}()// Graceful shutdown examplegofunc() {time.Sleep(30*time.Second)log.Println("Initiating graceful shutdown...")hc.Shutdown()// /ready will now return 500, stopping new trafficlog.Println("Application marked as shutting down")}()log.Println("Health checks available at:")log.Println("  - http://localhost:8080/live")log.Println("  - http://localhost:8080/ready")select {}}funccheckPaymentProvider(ctx context.Context)error {// Implementation of payment provider checkreturnnil}

Integration with Kubernetes

apiVersion:v1kind:Podspec:containers:    -name:applivenessProbe:httpGet:path:/liveport:8080initialDelaySeconds:10periodSeconds:10timeoutSeconds:5failureThreshold:3readinessProbe:httpGet:path:/readyport:8080initialDelaySeconds:5periodSeconds:5timeoutSeconds:3failureThreshold:2

Response Format

{"status":"up","checks": [{"name":"postgres","state": {"status":"up","error":"","timestamp":"2024-01-15T10:30:00Z"},"history": [{"status":"up","error":"","timestamp":"2024-01-15T10:29:55Z"}]}]}

{"status":"down","checks": [{"name":"postgres","state": {"status":"up","error":"","timestamp":"2024-01-15T10:30:00Z"}},{"name":"__shutting_down__","state": {"status":"down","error":"The application in shutting down process","timestamp":"2024-01-15T10:30:05Z"},"history":null}]}