{"id":46557606,"url":"https://github.com/botchris/go-health","last_synced_at":"2026-03-07T05:04:10.050Z","repository":{"id":322431512,"uuid":"1089450155","full_name":"botchris/go-health","owner":"botchris","description":"Package that provides simple health-checking for applications","archived":false,"fork":false,"pushed_at":"2025-11-26T10:18:27.000Z","size":167,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-28T23:14:45.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/botchris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T11:08:24.000Z","updated_at":"2025-11-26T10:17:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/botchris/go-health","commit_stats":null,"previous_names":["botchris/go-health"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/botchris/go-health","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/botchris%2Fgo-health","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/botchris%2Fgo-health/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/botchris%2Fgo-health/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/botchris%2Fgo-health/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/botchris","download_url":"https://codeload.github.com/botchris/go-health/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/botchris%2Fgo-health/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30208730,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T03:24:23.086Z","status":"ssl_error","status_checked_at":"2026-03-07T03:23:11.444Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-07T05:04:09.398Z","updated_at":"2026-03-07T05:04:10.029Z","avatar_url":"https://github.com/botchris.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go Health\n\n[![go test](https://github.com/botchris/go-health/actions/workflows/go-test.yml/badge.svg)](https://github.com/botchris/go-health/actions/workflows/go-test.yml)\n[![golangci-lint](https://github.com/botchris/go-health/actions/workflows/golangci-lint.yml/badge.svg)](https://github.com/botchris/go-health/actions/workflows/golangci-lint.yml)\n\nA simple Golang package for performing health checks within your Go applications.\n\n---\n\n## Installation\n\n```sh\ngo get github.com/botchris/go-health\n```\n\n## Example Usage\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\t\"os/signal\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/botchris/go-health\"\n\t\"github.com/botchris/go-health/reporters/strwriter\"\n)\n\nfunc main() {\n\t// 1. Create a context that is canceled on SIGINT or SIGTERM\n\tctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)\n\tdefer cancel()\n\n\t// 2. Create a new health checker.\n\tchecker, err := health.NewChecker(health.WithPeriod(time.Second))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// 3. Add a simple probe.\n\tchecker.AddProbe(\"mysql-db01\", health.ProbeFunc(func(context.Context) error {\n\t\ttime.Sleep(100 * time.Millisecond) // Simulate a database check\n\n\t\treturn nil // return an error if the check fails\n\t}), time.Second)\n\n\t// 4. Add string writer reporter to output health status to console.\n\tchecker.AddReporter(strwriter.New(os.Stdout))\n\n\t// 5. Start the health checker and listen for status updates.\n\tfor status := range checker.Start(ctx) {\n\t\tif statusErr := status.AsError(); statusErr != nil {\n\t\t\tfmt.Printf(\"Check failed: %s\\n\", statusErr)\n\t\t} else {\n\t\t\tfmt.Printf(\"Check passed\\n\")\n\t\t}\n\t}\n}\n\n```\n\n## Concepts\n\nThis section explains the main concepts used in the `go-health` package.\n\n- [Probe](#probe)\n- [Checker](#checker)\n- [Reporter](#reporter)\n\n### Probe\n\nA Probe is anything that implements the `Probe` interface. The simplest way to create a probe is to use\nthe `ProbeFunc` type, which allows you to define a probe using a function.\n\nProbes are expected to return an error if the check fails, or `nil` if the check passes.\n\n#### Built-in Probes\n\n- **DynamoDB**: A probe that checks the health of an AWS DynamoDB table.\n- **gRPC**: A probe that performs a gRPC health check on a specified gRPC server.\n- **HTTP**: A probe that performs an HTTP request to a specified URL and checks the response status code.\n- **RabbitMQ**: A probe that checks the health of a RabbitMQ server by connecting and optionally checking a queue.\n- **Redis**: A probe that pings a Redis server to check its availability, and optionally checks for a specific keys.\n- **S3**: A probe that checks the health of an AWS S3 bucket.\n- **SQL**: A probe that pings a SQL database to check its availability.\n\n#### Building Custom Probes\n\nYou can create custom probes by implementing the `Probe` interface. Here's an example of a simple custom probe:\n\n```go\npackage custom\n\nimport \"context\"\n\ntype CustomProbe struct {\n    // Add any fields you need for your probe.\n}   \n\nfunc (p *CustomProbe) Check(context.Context) error {\n    // Implement your custom health check logic here.\n    return nil // return an error if the check fails.\n}\n\n```\n\n### Checker\n\nA Checker is responsible for managing and executing probes at specified intervals. You can register multiple probes\nwith a Checker, all of which are executed concurrently for generating health status updates. If a probe fails, the\nChecker will report the failure in the health status.\n\n#### Configuration Options\n\nThe Checker can be configured using various options, such as the check period, timeout duration, and more.\nThese options can be set when creating a new Checker using the `NewChecker` function.\n\nYou can configure the Checker using the following functional options:\n\n- **InitialDelay**: Sets an initial delay before the first health check is performed.  \n  If the duration is between 0 and 1 second, it is rounded up to 1 second. Defaults to 0 (no delay).\n\n- **Period**: Sets the period between consecutive health checks.  \n  The minimum allowed value is 1 second; smaller values are rounded up.  \n  Defaults to 10 seconds.\n\n- **SuccessThreshold**: Sets the number of consecutive successful checks required to consider the system healthy.  \n  The minimum allowed value is 1. Defaults to 1.\n\n- **FailureThreshold**: Sets the number of consecutive failed checks required to consider the system unhealthy.  \n  The minimum allowed value is 1. Defaults to 3.\n\n- **ProbeDefaultTimeout**: Sets the default timeout duration for probes that do not have a specific timeout set.  \n  The minimum allowed value is 1 second; smaller values are rounded up.  \n  Defaults to 5 seconds.\n\n- **ReporterTimeout**: Sets the timeout duration for reporter operations.  \n  The minimum allowed value is 1 second; smaller values are rounded up.  \n  Defaults to 30 seconds.\n\nYou can combine these options when creating a new Checker:\n\n```go\nchecker, err := health.NewChecker(\n    health.WithPeriod(5 * time.Second),\n    health.WithInitialDelay(2 * time.Second),\n    health.WithSuccessThreshold(2),\n    health.WithFailureThreshold(3),\n\thealth.WithProbeDefaultTimeout(7 * time.Second),\n    health.WithReporterTimeout(10 * time.Second),\n)\n```\n\nIn the example above the Checker is configured to perform health checks every 5 seconds,\nwith an initial delay of 2 seconds before the first check.\n\nIt requires 2 consecutive successful checks to consider the system healthy and 3 consecutive\nfailed checks to consider it unhealthy. The status won't be reported until any of these thresholds are met.\n\nEch probe will use a default timeout of 7 seconds unless a specific timeout is set for that probe.\nThe reporter will have a timeout of 10 seconds to handle each status update.\n\n### Reporter\n\nA reporter is anything capable of reporting the status changes reported by the `Checker`. For example,\nlogging the status changes to the console, sending alerts, updating a dashboard, an HTTP endpoint, etc.\n\nNOTE: reporters may not receive a status update on startup until threshold conditions\nare met. So you may want to initialize your reporter with an initial \"unknown\" status.\n\n#### Built-in Reporters\n\n- **HTTP**: An HTTP reporter that exposes an endpoint for health status checks.\n- **Proto Buffer**: A reporter that exposes health status service using the Health Checking Protocol defined in gRPC.\n- **String Writer**: A reporter that writes health status updates to an `io.StringWriter`, such as `os.Stdout` or a log file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbotchris%2Fgo-health","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbotchris%2Fgo-health","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbotchris%2Fgo-health/lists"}