Skip to content

Hero

Heartbeat

A Go package for HTTP health checks, designed for Kubernetes readiness and liveness probes. It monitors HTTP endpoints and custom dependencies with parallel evaluation and timeout protection. View the repository.

Why I Built It

Every Go service needs a health endpoint. Kubernetes needs to know if your service is ready to accept traffic and whether it's still alive. The boilerplate is always the same: check dependencies, aggregate status, return JSON.

I got tired of copy-pasting health check code across projects. Instead of reimplementing this every time, I packaged it once. Now every service gets the same reliable health checks without the repetitive setup work.

How It Works

Heartbeat provides two types of dependency monitoring. HTTP endpoints get automatic timeout-protected requests with configurable timeouts (defaults to 10 seconds). Custom handler functions let you check application-specific dependencies like databases or message queues.

All dependencies are evaluated in parallel. Custom handlers get automatic panic recovery so a bug in your check code won't crash the entire service. The overall health reflects the most severe dependency status using four health states: NotSet, OK, Warning, and Critical.

graph LR
    A[Health Check Request] --> B[Parallel Dependency Evaluation]
    B --> C1[HTTP Endpoint Checks]
    B --> C2[Custom Handler Checks]
    C1 --> D[Aggregate Results]
    C2 --> D
    D --> E{Worst Status?}
    E -->|OK or Warning| F[Return 200 OK]
    E -->|Critical| G[Return 503 Service Unavailable]
    F --> H[JSON Response]
    G --> H

The HTTP status code maps to the overall health: 200 for OK or Warning, 503 for Critical. The JSON response includes the service name, hostname, UTC timestamp, request duration, and detailed results for each dependency.

Each dependency result shows its status, resource identifier, request duration, HTTP status code (for HTTP dependencies), and a descriptive message. This gives you complete visibility into what's healthy and what's not.

Built With the Agent Setup

This project was built by hand a few years back, and recently refined using the claude-code-setup agent ecosystem. The Go software engineer agent wrote the core package. The E2E test engineer validated the HTTP endpoints. The DevOps engineer created the Dockerfiles and CI builds. The code review skill caught issues before they were committed.

Early Validation Project

Heartbeat was one of the first projects used to validate and tune the agent ecosystem. The consistency of the generated code and tests proved that specialized agents with shared patterns produce better results than asking Claude to improvise.

Production Ready

Heartbeat requires Go 1.24+ and is released under the MIT License. Version 1.0.0 is production ready. Check the repository for usage examples and integration instructions.