HeartCheck
Checks your application health
Installation
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
Usage
Defining your checks
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.
Mounting in your web app
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.
Other checks
Firewall Check
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
Extra HTTP Routes
Very basic health check
Returns a simple ok
if the app is running. It does not execute any configured
checks:
/monitoring/health_check
General info and dependencies
Returns general of the environment. OS, dependencies names and versions, elixir version etc.
/monitoring/environment
Running tests and metrics:
To run the tests, simply execute:
$ mix test
To run coverage metrics and generate a html report in cover/excoveralls.html
:
$ mix coveralls.html