# PoisonPill

PoisonPill runs a series of system health checks on a fixed interval,
and upon failing a health check, waits a jittered amount of time and
then runs a specified command to kill or restart the VM.

The health check functions are found in `PoisonPill.Checks`.

Config options can be set for the `:poison_pill` app, either at the
top level or under the name of one of the health check functions.
See `@config_defaults` below for details.

A typical configuration might be:
```
config :poison_pill,
  kill_mfa: {System, :cmd, ["sh", ["-c", "bin/my_app restart &"]]}

## When RAM's getting high, restart some time in the next five minutes
config :poison_pill, :ram_percent,
  max: 80,
  jitter_ms: 5 * 60_000

## When run queue is seriously backed up, restart immediately
config :poison_pill, :run_queue,
  max: 1000,
  jitter_ms: 0
```

Config defaults:
```
%{
  ## Interval between each round of checks
  refresh_ms: 60_000,

  ## Between 0-100% of jitter_ms will be added before killing
  jitter_ms: 5 * 60_000,

  ## Set this to the `{module, function, args}` that should be
  ## invoked to perform the kill.
  kill_mfa: nil,

  ## Kill after this many milliseconds since launch
  lifetime_ms: [max: nil, jitter_ms: nil],

  ## Kill when more than this percent (0-100) of RAM is used
  ram_percent: [max: nil, jitter_ms: nil],

  ## Kill when more than this many kilobytes of RAM is used
  ram_kb: [max: nil, jitter_ms: nil],

  ## Kill when the run queue total is too deep
  run_queue: [max: nil, jitter_ms: nil],

  ## Kill when the 1, 5, or 15 minute load average is too high
  ## `max` is absolute load
  ## `ratio` is absolute load divided by System.schedulers_online()
  load_average: [max: nil, ratio: nil, period: 5, jitter_ms: nil],

  ## Set true for more copious output.
  debug: false

  ## Set false to disable Poison Pill (useful for dev, etc)
  enabled: true
}
```

## Authorship and License

Copyright 2020-2022, Appcues, Inc.

This software is released under the MIT License.