Checks your application health.

Add :heartcheck to your list of dependencies in mix.exs:

def deps do
  [
    {:heartcheck, "~> 0.4"}
  ]
end

Add :jason to deps too if you do not have it already:

  {:jason, "~> 1.0"},

If you wish to use :poison or other compatible JSON library, add the dependency in mix.exs and to your config.exs:

config :heartcheck, json_encoder: Poison

If you are using elixir < 1.5, ensure heartcheck is started before your application:

def application do
  [
    applications: [:heartcheck]
  ]
end

Define your checks in module by using the HeartCheck macro module and invoking the HeartCheck.add/2 macro:

defmodule MyApp.HeartCheck do
  use HeartCheck

  add :some_check do
    # TODO: perform some actual check here
    :ok
  end

  add :another_check do
    # TODO: perform some actual check here
    {:error, "something went wrong"}
  end
end

The checks can return one of the following terms:

• :ok
• {:error, term}
• :error

In the {error, term} case, a representation of term will be used as the error message.

Then you can mount HeartCheck.Plug using the module defined above in your app router (phoenix example below):

def MyApp.Router
  use MyApp.Web, :router

  # (...)

  scope "/" do
    pipe_through :browser

    # (...)

    forward "/monitoring", HeartCheck.Plug, heartcheck: MyApp.HeartCheck
  end
end

Then your checks will be available at the /monitoring endpoint.

You can define a another module using HeartCheck and use it as your functional monitoring in the router:

  forward "/monitoring", HeartCheck.Plug, heartcheck: MyApp.HeartCheck,
    functional: MyApp.FunctionalHeartCheck

This will be available in the /monitoring/funcional endpoint.

Use firewall check inside your heartcheck file to ensure your application is able to connect to an external service. This will only open a TCP connection to the defined host/port in the url and assert it can connect.

Timeout argument is optional and default is 1000 (1 second).

defmodule MyApp.HeartCheck do
  use HeartCheck

  firewall(service: "http://service.acme.org:3200",
    another_service: Application.get_env(:my_app, :service_url))

  firewall(my_domain: Application.get_env(:my_app, :url), timeout: 2000)
end

Returns a simple ok if the app is running. It does not execute any configured checks:

/monitoring/health_check

Returns general of the environment. OS, dependencies names and versions, elixir version etc.

/monitoring/environment

To easily start a docker container with the currently supported version of Elixir, you can use this command:

$ docker-compose run heartcheck bash

To install dependencies, execute:

$ mix deps.get

To run the tests, simply execute:

$ mix test

To run coverage metrics and generate a html report in cover/excoveralls.html:

$ mix coveralls.html