{"id":20908979,"url":"https://github.com/jaredpetersen/go-health","last_synced_at":"2025-10-24T03:37:14.918Z","repository":{"id":46421796,"uuid":"416586125","full_name":"jaredpetersen/go-health","owner":"jaredpetersen","description":"🏥 Barebones, detailed health check library for Go","archived":false,"fork":false,"pushed_at":"2021-10-14T21:39:04.000Z","size":36,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-19T14:57:37.260Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaredpetersen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null},"funding":{"github":"jaredpetersen","custom":["https://cash.app/$jaredtpetersen","https://paypal.me/jaredtpetersen"]}},"created_at":"2021-10-13T04:16:46.000Z","updated_at":"2021-10-19T16:11:13.000Z","dependencies_parsed_at":"2022-09-06T03:01:34.477Z","dependency_job_id":null,"html_url":"https://github.com/jaredpetersen/go-health","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpetersen%2Fgo-health","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpetersen%2Fgo-health/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpetersen%2Fgo-health/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpetersen%2Fgo-health/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaredpetersen","download_url":"https://codeload.github.com/jaredpetersen/go-health/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243301129,"owners_count":20269286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-11-18T14:09:42.706Z","updated_at":"2025-10-24T03:37:09.875Z","avatar_url":"https://github.com/jaredpetersen.png","language":"Go","funding_links":["https://github.com/sponsors/jaredpetersen","https://cash.app/$jaredtpetersen","https://paypal.me/jaredtpetersen"],"categories":[],"sub_categories":[],"readme":"# go-health\n#### 🏥 Barebones, detailed health check library for Go\n[![Build](https://github.com/jaredpetersen/go-health/actions/workflows/build.yaml/badge.svg)](https://github.com/jaredpetersen/go-health/actions/workflows/build.yaml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/jaredpetersen/go-health/health.svg)](https://pkg.go.dev/github.com/jaredpetersen/go-health/health)\n\ngo-health does away with the kitchen sink mentality of other health check libraries. You aren't getting a default HTTP\nhandler out of the box that is router dependent or has opinions about the shape or format of the health data being\npublished. You aren't getting pre-built health checks. But you do get a simple system for checking the health of\nresources asynchronously with built-in caching and timeouts. Only what you absolutely need, and nothing else.\n\n## Quickstart\nInstall the package:\n```sh\ngo get github.com/jaredpetersen/go-health/health\n```\n\nExample:\n```go\n// Create the health monitor that will be polling the resources.\nhealthMonitor := health.New()\n\n// Prepare the context -- this can be used to stop async monitoring.\nctx := context.Background()\n\n// Create your health checks.\nfooHealthCheckFunc := func(ctx context.Context) health.Status {\n    return health.Status{State: health.StateDown}\n}\nfooHealthCheck := health.NewCheck(\"foo\", fooHealthCheckFunc)\nfooHealthCheck.Timeout = time.Second * 2\nhealthMonitor.Monitor(ctx, fooHealthCheck)\n\nbarHealthCheckFunc := func(ctx context.Context) health.Status {\n    return health.Status{State: health.StateUp}\n}\nbarHealthCheck := health.NewCheck(\"bar\", barHealthCheckFunc)\nbarHealthCheck.Timeout = time.Second * 2\nhealthMonitor.Monitor(ctx, barHealthCheck)\n\n// Wait for goroutines to kick off\ntime.Sleep(time.Millisecond * 100)\n\n// Retrieve the most recent cached result for all of the checks.\nhealthMonitor.Check()\n```\n\n## Asynchronous Checking and Caching\nHealth checks in this package are only asynchronous for security purposes. Health endpoints in HTTP services can be a\nlucrative target for bad actors looking to execute a Denial of Service (DOS) attack. Some checks that your application\nperforms to determine health may be somewhat expensive and a health endpoint centralizes all of those checks in a\nsingle convenient location for an attacker. This attacker can conveniently direct significant amount of traffic to your\nhealth check endpoints in an attempt to abuse and take down multiple systems in one go.\n\nThe best defense against this is to perform those checks on your schedule asynchronously, not the caller's schedule.\nResults from those checks should be cached and returned upon request.\n\nThis package spins up a goroutine for each configured health check that polls the check function. Each check has its\nown, individually configurable Time To Live (TTL) that dictates the duration between those polls. For example, if you\nspecify a check with a TTL of two seconds, the check will execute, wait two seconds, and then execute again. This will\ngo on forever until the context is closed.\n\nBy default, all checks created via `health.NewCheck()` are configured with a default TTL of one second.\n\n## Timeouts\nYou can optionally configure a timeout for each check. If set, the context provided to the check function will have a\ndeadline set. When the deadline expires, the context will close the Done channel, just like the normal context\nbehavior. go-health does not kill the check function execution, it only leverages the context to communicate that\nthe configured timeout deadline has been exceeded. It is your responsibility to handle the context appropriately. For\nmore information on context with deadline, see the [context documentation](https://pkg.go.dev/context#WithDeadline).\n\n## Additional Information\nThe return type of the health check function supports adding arbitrary information to the status. This could be\ninformation like active database connections, response time for an HTTP request, etc.\n\n```go\ntype HTTPHealthCheckDetails struct {\n    ResponseTime time.Duration\n}\n```\n\n```go\nreturn health.Status{\n    State:   health.StateUp,\n    Details: HTTPHealthCheckDetails{ResponseTime: responseTime},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredpetersen%2Fgo-health","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaredpetersen%2Fgo-health","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredpetersen%2Fgo-health/lists"}