{"id":21155636,"url":"https://github.com/locaweb/heartcheck-elixir","last_synced_at":"2025-09-14T04:24:14.927Z","repository":{"id":48433086,"uuid":"116728712","full_name":"locaweb/heartcheck-elixir","owner":"locaweb","description":"Web based health monitoring","archived":false,"fork":false,"pushed_at":"2024-12-09T18:30:29.000Z","size":300,"stargazers_count":33,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-16T00:24:57.193Z","etag":null,"topics":["elixir","hacktoberfest","monitoring"],"latest_commit_sha":null,"homepage":"","language":"Elixir","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/locaweb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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}},"created_at":"2018-01-08T21:12:46.000Z","updated_at":"2024-03-27T16:56:30.000Z","dependencies_parsed_at":"2025-03-15T04:05:18.474Z","dependency_job_id":"66f8cb58-1b52-4362-825c-ee1893fa19a4","html_url":"https://github.com/locaweb/heartcheck-elixir","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locaweb%2Fheartcheck-elixir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locaweb%2Fheartcheck-elixir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locaweb%2Fheartcheck-elixir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locaweb%2Fheartcheck-elixir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locaweb","download_url":"https://codeload.github.com/locaweb/heartcheck-elixir/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441053,"owners_count":20939239,"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":["elixir","hacktoberfest","monitoring"],"created_at":"2024-11-20T11:25:04.766Z","updated_at":"2025-04-06T06:11:23.858Z","avatar_url":"https://github.com/locaweb.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HeartCheck\n\n[![Build Status](https://travis-ci.org/locaweb/heartcheck-elixir.svg?branch=master)](https://travis-ci.org/locaweb/heartcheck-elixir)\n[![Module Version](https://img.shields.io/hexpm/v/heartcheck.svg)](https://hex.pm/packages/heartcheck)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/heartcheck/)\n[![Total Download](https://img.shields.io/hexpm/dt/heartcheck.svg)](https://hex.pm/packages/heartcheck)\n[![License](https://img.shields.io/hexpm/l/heartcheck.svg)](https://github.com/locaweb/heartcheck/blob/master/LICENSE.md)\n[![Last Updated](https://img.shields.io/github/last-commit/locaweb/heartcheck.svg)](https://github.com/locaweb/heartcheck/commits/master)\n\nChecks your application health.\n\n## Installation\n\nAdd `:heartcheck` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:heartcheck, \"~\u003e 0.4\"}\n  ]\nend\n```\n\nAdd `:jason` to `deps` too if you do not have it already:\n\n```elixir\n  {:jason, \"~\u003e 1.0\"},\n```\n\nIf you wish to use `:poison` or other compatible JSON library, add the dependency\nin `mix.exs` and to your `config.exs`:\n\n```elixir\nconfig :heartcheck, json_encoder: Poison\n```\n\nIf you are using elixir \u003c 1.5, ensure heartcheck is started before your\napplication:\n\n```elixir\ndef application do\n  [\n    applications: [:heartcheck]\n  ]\nend\n```\n\n## Usage\n\n### Defining your checks\n\nDefine your checks in module by using the `HeartCheck` macro module and invoking\nthe `HeartCheck.add/2` macro:\n\n```elixir\ndefmodule MyApp.HeartCheck do\n  use HeartCheck\n\n  add :some_check do\n    # TODO: perform some actual check here\n    :ok\n  end\n\n  add :another_check do\n    # TODO: perform some actual check here\n    {:error, \"something went wrong\"}\n  end\nend\n\n```\n\nThe checks can return one of the following terms:\n\n* `:ok`\n* `{:error, term}`\n* `:error`\n\nIn the `{error, term}` case, a representation of `term` will be used as the\nerror message.\n\n### Mounting in your web app\n\nThen you can mount `HeartCheck.Plug` using the module defined above in your app\nrouter (phoenix example below):\n\n```elixir\ndef MyApp.Router\n  use MyApp.Web, :router\n\n  # (...)\n\n  scope \"/\" do\n    pipe_through :browser\n\n    # (...)\n\n    forward \"/monitoring\", HeartCheck.Plug, heartcheck: MyApp.HeartCheck\n  end\nend\n\n```\n\nThen your checks will be available at the `/monitoring` endpoint.\n\nYou can define a another module using `HeartCheck` and use it as your functional\nmonitoring in the router:\n\n```elixir\n  forward \"/monitoring\", HeartCheck.Plug, heartcheck: MyApp.HeartCheck,\n    functional: MyApp.FunctionalHeartCheck\n```\n\nThis will be available in the `/monitoring/funcional` endpoint.\n\n## Other checks\n\n### Firewall Check\n\nUse firewall check inside your heartcheck file to ensure your application is\nable to connect to an external service. This will only open a TCP connection\nto the defined host/port in the url and assert it can connect.\n\nTimeout argument is optional and default is `1000` (1 second).\n\n```elixir\ndefmodule MyApp.HeartCheck do\n  use HeartCheck\n\n  firewall(service: \"http://service.acme.org:3200\",\n    another_service: Application.get_env(:my_app, :service_url))\n\n  firewall(my_domain: Application.get_env(:my_app, :url), timeout: 2000)\nend\n```\n\n## Extra HTTP Routes\n\n#### Very basic health check\n\nReturns a simple `ok` if the app is running. It does not execute any configured\nchecks:\n\n```console\n/monitoring/health_check\n```\n\n\n#### General info and dependencies\n\nReturns general of the environment. OS, dependencies names and versions, elixir version etc.\n\n```console\n/monitoring/environment\n```\n\n\n## Running tests and metrics:\n\nTo easily start a docker container with the currently supported version of Elixir, you can use this command:\n\n```console\n$ docker-compose run heartcheck bash\n```\n\nTo install dependencies, execute:\n\n```console\n$ mix deps.get\n```\n\nTo run the tests, simply execute:\n\n```console\n$ mix test\n```\n\nTo run coverage metrics and generate a html report in `cover/excoveralls.html`:\n\n```console\n$ mix coveralls.html\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocaweb%2Fheartcheck-elixir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocaweb%2Fheartcheck-elixir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocaweb%2Fheartcheck-elixir/lists"}