Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/locaweb/heartcheck-elixir
Web based health monitoring
https://github.com/locaweb/heartcheck-elixir
elixir hacktoberfest monitoring
Last synced: about 1 month ago
JSON representation
Web based health monitoring
- Host: GitHub
- URL: https://github.com/locaweb/heartcheck-elixir
- Owner: locaweb
- License: mit
- Created: 2018-01-08T21:12:46.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-10-28T11:57:29.000Z (about 2 years ago)
- Last Synced: 2024-04-16T18:21:21.734Z (9 months ago)
- Topics: elixir, hacktoberfest, monitoring
- Language: Elixir
- Homepage:
- Size: 293 KB
- Stars: 33
- Watchers: 5
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# HeartCheck
[](https://travis-ci.org/locaweb/heartcheck-elixir)
[](https://hex.pm/packages/heartcheck)
[](https://hexdocs.pm/heartcheck/)
[](https://hex.pm/packages/heartcheck)
[](https://github.com/locaweb/heartcheck/blob/master/LICENSE.md)
[](https://github.com/locaweb/heartcheck/commits/master)
Checks your application health.
## Installation
Add `:heartcheck` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:heartcheck, "~> 0.4"}
]
end
```
Add `:jason` to `deps` too if you do not have it already:
```elixir
{: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`:
```elixir
config :heartcheck, json_encoder: Poison
```
If you are using elixir < 1.5, ensure heartcheck is started before your
application:
```elixir
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:
```elixir
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):
```elixir
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:
```elixir
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).
```elixir
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:
```console
/monitoring/health_check
```
#### General info and dependencies
Returns general of the environment. OS, dependencies names and versions, elixir version etc.
```console
/monitoring/environment
```
## Running tests and metrics:
To easily start a docker container with the currently supported version of Elixir, you can use this command:
```console
$ docker-compose run heartcheck bash
```
To install dependencies, execute:
```console
$ mix deps.get
```
To run the tests, simply execute:
```console
$ mix test
```
To run coverage metrics and generate a html report in `cover/excoveralls.html`:
```console
$ mix coveralls.html
```