{"id":29170188,"url":"https://github.com/manifoldco/healthz","last_synced_at":"2025-07-01T12:39:35.591Z","repository":{"id":47740948,"uuid":"112202866","full_name":"manifoldco/healthz","owner":"manifoldco","description":"Easily add health checks to your go services","archived":false,"fork":false,"pushed_at":"2021-08-15T18:23:26.000Z","size":196,"stargazers_count":23,"open_issues_count":1,"forks_count":2,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-08T08:03:24.200Z","etag":null,"topics":["go","golang","healthcheck","reliability"],"latest_commit_sha":null,"homepage":"https://www.manifold.co","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manifoldco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2017-11-27T13:58:31.000Z","updated_at":"2023-05-01T03:08:13.000Z","dependencies_parsed_at":"2022-09-26T20:00:57.296Z","dependency_job_id":null,"html_url":"https://github.com/manifoldco/healthz","commit_stats":null,"previous_names":["manifoldco/go-healthcheck"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/manifoldco/healthz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldco%2Fhealthz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldco%2Fhealthz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldco%2Fhealthz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldco%2Fhealthz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manifoldco","download_url":"https://codeload.github.com/manifoldco/healthz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manifoldco%2Fhealthz/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262964043,"owners_count":23391937,"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":["go","golang","healthcheck","reliability"],"created_at":"2025-07-01T12:39:24.029Z","updated_at":"2025-07-01T12:39:35.529Z","avatar_url":"https://github.com/manifoldco.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Healthz\n\n[Code of Conduct](./.github/CODE_OF_CONDUCT.md) |\n[Contribution Guidelines](./.github/CONTRIBUTING.md)\n\n[![GitHub release](https://img.shields.io/github/tag/manifoldco/healthz.svg?label=latest)](https://github.com/manifoldco/healthz/releases)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/manifoldco/healthz)\n[![Build Status](https://travis-ci.org/manifoldco/healthz.svg?branch=master)](https://travis-ci.org/manifoldco/healthz)\n[![Go Report Card](https://goreportcard.com/badge/github.com/manifoldco/healthz)](https://goreportcard.com/report/github.com/manifoldco/healthz)\n[![License](https://img.shields.io/badge/license-BSD-blue.svg)](./LICENSE.md)\n\nThis is a package that allows you to set up health checks for your services. By\ndefault, the health checks will be available at the `/_healthz` endpoint but can\nbe configured with the `Prefix` and `Endpoint` variables.\n\nBy default, the health check package will add a single default test. This test\ndoesn't validate anything, it simply returns no error.\n\n## Registering additional tests\n\nIf you want to add more tests in case your service/worker depends on a specific\nset of tools (like a JWT key mounted on a volume), you can register a new test\nas follows:\n\n```go\nfunc init() {\n\thealthz.RegisterTest(\"jwt-key\", jwtCheck)\n}\n\nfunc jwtCheck(ctx context.Context) error {\n\t_, err := os.Stat(\"/jwt/ecdsa-private.pem\")\n\treturn err\n}\n```\n\n## Attaching the endpoints to an existing server\n\nIf you have an existing server running, you can attach the `/_healthz` endpoint\nto it without having to start a separate server.\n\n```go\nfunc main() {\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(\"/hello\", func(w http.ResponseWriter, _ *http.Request) {\n\t\tw.WriteHeader(http.StatusOK)\n\t})\n\n\thandler := healthz.NewHandler(mux)\n\thttp.ListenAndServe(\":3000\", handler)\n}\n```\n\nThis will create a new mux which listens to the `/hello` request. We then attach\nthe healthcheck handler by using `healthz.NewHandler(mux)`.\n\n\n## Creating a standalone server\n\nWhen your application isn't a web server, but you still want to add health\nchecks, you can use the provided server implementation.\n\n```go\nfunc main() {\n\tstop := make(chan os.Signal, 1)\n\tsignal.Notify(stop, os.Interrupt)\n\n\tsrv := healthz.NewServer(\"0.0.0.0\", 3000)\n\tgo srv.Start()\n\n\t\u003c-stop\n\n\tctx, _ := context.WithTimeout(context.Background(), 5*time.Second)\n\tsrv.Shutdown(ctx)\n}\n```\n\n## Using middleware\n\nWith both the `NewHandler` and `NewServer` implementation, we've provided a way\nto add middleware. This allows you to add logging to your health checks for\nexample.\n\nThe middleware functions are respectively `NewHandlerWithMiddleware` and\n`NewServerWithMiddleware`. They accept the arguments of their parent function\nbut also a set of middlewares as variadic arguments.\n\n```go\nfunc main() {\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(\"/hello\", func(w http.ResponseWriter, _ *http.Request) {\n\t\tw.WriteHeader(http.StatusOK)\n\t})\n\n\thandler := healthz.NewHandlerWithMiddleware(mux, logMiddleware)\n\thttp.ListenAndServe(\":3000\", handler)\n}\n\nfunc logMiddleware(next http.Handler) http.Handler {\n\treturn http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\tlog.Print(\"start request\")\n\t\tnext.ServeHTTP(w, r)\n\t\tlog.Print(\"end request\")\n\t})\n}\n```\n\n## Output\n\nOn the health check endpoint, we return a set of values useful to us. Extending\nthe example from above, these are both return values (one where the file is\npresent, one where it isn't).\n\n### 200 OK\n```json\n{\n  \"checked_at\": \"2017-11-22T14:18:50.339Z\",\n  \"duration_ms\": 0,\n  \"result\": \"success\",\n  \"tests\": {\n    \"default\": {\n      \"duration_ms\": 0,\n      \"result\": \"success\"\n    },\n    \"jwt-key\": {\n      \"duration_ms\": 0,\n      \"result\": \"success\"\n    }\n  }\n}\n```\n\n### 503 Service Unavailable\n```json\n{\n  \"checked_at\": \"2017-11-22T14:18:50.339Z\",\n  \"duration_ms\": 1,\n  \"result\": \"failure\",\n  \"tests\": {\n    \"default\": {\n      \"duration_ms\": 0,\n      \"result\": \"success\"\n    },\n    \"jwt-key\": {\n      \"duration_ms\": 0,\n      \"result\": \"failure\"\n    }\n  }\n}\n```\n\n## Middlewares\n\nWe've included a set of standard middlewares that can be useful for general use.\n\n### Cache\n\nThe cache middleware allows you to cache a response for a specific duration.\nThis prevents the health check to overload due to different sources asking for\nthe health status. This is especially useful when the health checks are used to\ncheck the health of other services as well.\n\nTo use this middleware, simply add it to the chain:\n\n```go\nfunc main() {\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(\"/hello\", func(w http.ResponseWriter, _ *http.Request) {\n\t\tw.WriteHeader(http.StatusOK)\n\t})\n\n\thandler := healthz.NewHandlerWithMiddleware(\n\t\tmux,\n\t\thealthz.CacheMiddleware(5*time.Second),\n\t)\n\thttp.ListenAndServe(\":3000\", handler)\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanifoldco%2Fhealthz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanifoldco%2Fhealthz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanifoldco%2Fhealthz/lists"}