# Fettle
Runs health-check functions periodically, and aggregates health status reports.
(AKA Elixir implementation of FT Health-Check standard).
[](https://hex.pm/packages/fettle) [](http://inch-ci.org/github/Financial-Times/fettle) [](https://travis-ci.org/Financial-Times/fettle)
> **fettle**
*noun* - "his best players were in fine fettle": shape, trim, fitness, physical fitness, health, state of health; condition, form, repair, state of repair, state, order, working order, way; informal: kilter; British informal: nick.
This library implents an asynchronous periodic check mechanism, and defines a way of configuring checks, and getting reports in a particular format. It is intended for use with monitoring and dashboards.
Ships with the [FT Health Check V1](https://github.com/Financial-Times/fettle/blob/master/FTHealthcheckstandard.pdf) schema format for report generation, but the schema is configurable.
## See also
* [`fettle_plug`](https://github.com/Financial-Times/fettle_plug) - integration with [Plug](https://github.com/elixir-lang/plug) to expose to HTTP.
* [`fettle_checks`](https://github.com/Financial-Times/fettle_checks) - a small library of commonly useful checks.
## Getting Started
### Installation
Add a dependency in your `mix.exs` config:
```elixir
def deps do
[
{:fettle, "~> 1.0"}
]
end
```
For the bleeding edge:
```elixir
def deps do
[
{:fettle, github: "Financial-Times/fettle"}
]
end
```
### Starting
Add `Fettle.Supervisor` to your supervision tree<sup>1</sup>, e.g. in your `Application.start/2`:
```elixir
def start(_type, _args) do
children = [
{Fettle.Supervisor, []},
...
]
Supervisor.start_link(children, strategy: :one_for_one)
end
```
or otherwise call `Fettle.Supervisor.start_link/1`.
By default Fettle will load configuration from the `:fettle` application config key, the minimum
required configuration for start-up is:
```elixir
config :fettle,
system_code: "my_app"
```
where `system_code` is a code used in reports; see below for other options.
* [1] - this changed in v1.0.0 - was auto-starting OTP application.
### Defining checks
The [`fettle_checks`](https://github.com/Financial-Times/fettle_checks) module provides pre-canned checks, but to write your own, implement a module with the `Fettle.Checker` `@behaviour` that runs a check, and returns a `Fettle.Check.Result` struct:
```elixir
defmodule MyCheck do
@behaviour Fettle.Checker
def check(args) do
case do_check(args) do # assume do_check/1 does something useful!
:ok ->
Fettle.Checker.Result.ok()
{:error, message} ->
Fettle.Checker.Result.error(message)
end
end
end
```
Then configure this check, with some required metadata, in the `:fettle` configuration:
```elixir
config :fettle,
system_code: "my_app", # required (for reports)
checks: [
%{
name: "my-check",
panic_guide_url: "https://...",
business_impact: "...",
technical_summary: "..."
checker: MyCheck, # name of our check module
args: "url_or_something" # arguments to the checker module (optional)
},
...
]
```
On start-up, Fettle will start running your check, by default every 30 seconds, and you can retrieve the results using `Fettle.report/1`.
[`fettle_plug`](https://github.com/Financial-Times/fettle_plug) can then be used to expose the results over an HTTP end-point.
See module docs for full details.
