alerty

A pluggable CLI utility to send an alert if a given command failed.

How Useful?

I use alerty to run commands in cron to send alerts if cron commands fail.

0 * * * * alerty -c /etc/alerty/alerty.yml -- /path/to/script --foo FOO --bar

Installation

gem install alerty

Configuration

You can write a configuration file located at /etc/alerty/alerty.yml (You can configure this path by ALERTY_CONFIG_FILE environment variable, or -c option):

log_path: /var/tmp/alerty.log
log_level: 'info'
log_shift_age: 10
log_shift_size: 10485760
timeout: 10
lock_path: /tmp/lock
retry_limit: 2
retry_wait: 10
plugins:
  - type: stdout

example.yml

CLI Example

$ alerty -c example.yml -- ls -l /something_not_exist

CLI Help

Usage: alerty [options] -- command
    -c, --config CONFIG_FILE         config file path (default: /etc/alerty/alerty.yml)
        --log LOG_FILE               log file path (default: STDOUT)
    -l, --log-level LOG_LEVEL        log level (default: warn)
        --log-shift-age SHIFT_AGE    Number of old log files to keep (default: 0 which means no log rotation)
        --log-shift-size SHIFT_SIZE  Maximum logfile size in bytes (default: 1048576)
    -t, --timeout SECONDS            timeout the command (default: no timeout)
        --lock LOCK_FILE             exclusive lock file to prevent running a command duplicatedly (default: no lock)
        --retry-limit NUMBER         number of retries (default: 0)
        --retry-wait SECONDS         retry interval = retry wait +/- 12.5% randomness (default: 1.0)
    -d, --debug                      debug mode
        --dotenv                     Load environment variables from .env file with dotenv

Experimental: Send alert from STDIN

This interface allows us to send notification even if a command does not fail.

CLI Example:

$ echo 'this is a test' | alerty -c example.yml

Plugins

Following plugins are available:

• stdout
• file
• exec
• sonots/alerty-plugin-ikachan
• sonots/alerty-plugin-amazon_sns
• sonots/alerty-plugin-slack
• civitaspo/alerty-plugin-mail
• inokappa/alerty-plugin-datadog_event
• inokappa/alerty-plugin-amazon_cloudwatch_logs
• inokappa/alerty-plugin-post_im_kayac
• potato2003/alerty-plugin-stackdriver
• is2ei/alerty-plugin-typetalk

Plugin Architecture

Naming Convention

You must follow following naming conventions:

• gem name: alerty-plugin-xxx (xxx_yyy)
• file name: lib/alerty/plugin/xxx.rb (xxx_yyy.rb)
• class name: Alerty::Plugin:Xxx (XxxYyy)

Interface

What you have to implement is #initialize and #alert methods. Here is an example of file plugin:

require 'json'

class Alerty
  class Plugin
    class File
      def initialize(config)
        raise ConfigError.new('file: path is not configured') unless config.path
        @path = config.path
      end

      def alert(record)
        ::File.open(@path, 'a') do |io|
          io.puts record.to_json
        end
      end
    end
  end
end

config

config is created from the configuration file:

plugins:
  - type: foobar
    key1: val1
    key2: val2

config.key1 and config.key2 are availabe in the above config.

record

record is a hash whose keys are symbols of followings:

• hostname: hostname
• command: the executed command
• exitstatus: the exit status of the executed command
• output: the output of the exectued command
• started_at: the time when command executed in epoch time.
• duration: the duration which the command execution has taken in seconds.
• retries: the number of retries

ChangeLog

See CHANGELOG.md for details.

Licenses

See LICENSE