eol-sensu-wrapper Cookbook

EOL Sensu cookbook installs and configures a Sensu server and clients to monitor servers' state and collect statistical metrics. This cookbook requires creation of 2 data bags sensu and sensu_checks (see description below)

Requirements

• sensu -- Sensu cookbook provides all the resources required by eol-sensu-wrapper

Attributes

eol-sensu-cookbook::default

Key	Type	Description	Default
["sensu"]["use_embedded_ruby"]	Boolean	Sensu relies on embedded Ruby	true
["sensu"]["version"]	String	Version of Sensu to install	0.16.0-1
["uchiwa"]["version"]	String	Version of Uchiva (Web GUI) to install	0.7.1-1
["eol_sensu_wrapper"]["roles"]	Array	Sets roles which define which checks and metrics to run	Empty

Included plugins

Sensu plugins either monitor some system parameters and warn about close to critical and critical conditions for these parameters. For example check-disk.rb plugin monitors percentage of disk space left on each partition of the servers.

You can find included plugins in files/default/plugins. A comment on top of of every plugin file explains it's purpose

Build-in "plugin"

Keepalive is an internal Sensu service which gets signals from sensu clients from all the machines. If server is down or sensu-slient stopped working -- server generates alert message and sends it the alerts to all keepalive handlers. These handlers are setup differently from checks, and are described further below.

Included handlers

Sensu handlers allow send alerts from Sensu checks and metrics to various communication channels -- Twitter, Email, Hipchat, Gitter etc. For example ponymailer.rb handler sends alerts by email to subscribed administrators.

You can find included handlers in files/default/handlers. A comment on top of of every handler file explains it's purpose

Adding new plugins and handlers

If you want to check for additional system paramters, collect different metrics or to send alert to a new service -- you can start by looking at existing Sensu community plugins. You can modify scripts to your needs or write your own.

Usage

To configure your Sensu installation decide which machine will host Sensu's server, API, and GUI.

For this example lets assume the following:

• Your future Sensu node has name sensu.example.org and it's IP is 10.0.0.1
• A node which will be monitored has name myserver.example.org and IP 10.0.0.2
• You are interested in one check plugin check-disk.rb
• You are interested in one metric plugin metric-sysopia.rb
• You want to send alerts to hipchat using hipchat.rb handler

In your own cookbook include the default eol-sensu-wrapper recipe:

include_recipe "eol-sensu-wrapper"

You can also include the recipe into a node's or a role's run_list:

{"run_list":
  ["recipe[eol-sensu-wrapper]"]
}

Use knife to create a data bags for sensu and sensu_checks.

$ knife data bag create sensu
$ knife data bag create sensu_checks

In sensu data bag create items config and handlers. In sensu_checks create items corresponding to your checks in our case check-disk.

$ knife data bag create sensu config
$ knife data bag create sensu handlers
$ knife data bag create sensu ssl
$ knife data bag create sensu_checks check-disk

Item sensu -> config

Item config contains general information about Sensu:

{
  "id": "config",
  "master_address": "10.0.0.1",
  "uchiwa_user": "uchiwa",
  "uchiwa_password": "secret",
  "additional": {
    "keepalive": {
      "handlers": ["ponymailer"]
    }
  },
  "sensu.example.com": {
    "roles": ["sensu", "server"]
  },
  "eol-db-master1.si.edu": {
    "roles": ["server"]
  }
}

Parameter	Description
master_address	Tells where to install sensu server and where client listen
uchiva_user	User for web interface (uchiva app)
uchiva_password	Password for web interface (uchiva app)
keepalive	Instrucions for built-in keepalive check (sets handlers)

Config data bag also assigns roles to nodes. Later you can assign plugins to work only for specific role/roles.

Item sensu -> handlers

Item handlers contains configuration about handlers of the system. In our case ponymailer.

{
  "id": "handlers",
  "ponymailer": {
    "recipients": [
      "user1@example.org",
      "user2@example.org",
      "user3@example.org"
    ],
    "from": "alerts@example.org",
    "fromname": "Sensu alert",
    "hostname": "localhost",
    "port": 25
  },
  "hipchat": {
    "apikey": "124",
    "room": "Ops"
  },
  "postfix": {
    "mydomain": "sensu.example.org",
    "myorigin": "sensu.example.org",
    "smtp_use_tls": "no",
    "smtpd_use_tls": "no"
  },
  "sysopia": {
    "mysqlini": "/etc/sensu/my_sysopia.cnf"
  }
}

Data from this file set parameters for handlers

Item sensu -> ssl

Sensu uses ssl protocol to communicate between servers. To generate ssl databag in your file system you can use a script provided in sensu cookbook:

Item sensu_checks -> check-disk

Item check-disk explains how this particular check should be used with Sensu clients.

{
  "id": "check_disk",
  "command": "check-disk.rb -c 95 -w 85",
  "handlers": [ "ponymailer", "hipchat" ],
  "subscribers": [ "all" ],
  "interval": 3600
}

Read Sensu documentation how to configure checks and handlers

Contributing

1. Fork the repository on Github
2. Create a named feature branch (like add_component_x)
3. Write your change
4. Write tests for your change (if applicable)
5. Run the tests, ensuring they all pass
6. Submit a Pull Request using Github

License and Authors

Authors: Dmitry Mozzherin, Jeremy Rice

Copyright: 2015, Marine Biological Laboratory

Licensed under the MIT License