Sensu Enterprise Integration Guide

Sensu Enterprise is a monitoring framework for servers, services, application health, and business KPIs. Sensu was designed from the ground up to monitor systems in the cloud, such as AWS EC2 instances, and to discover systems rather than have them specified in your configuration beforehand. Sensu Enterprise builds on Sensu Core by providing built-in integrations for services like PagerDuty, LDAP authentication, enterprise support and more.

This guide will walk you through the process of integrating Sensu Enterprise with PagerDuty. If you have any trouble completing the integration please contact us.

Note: The steps in this guide are applicable only to Sensu Enterprise. The free version, Sensu Core, does not include built-in PagerDuty integration, so there is a different Sensu Core Integration Guide which you should use if you do not have the enterprise version.

In PagerDuty

  1. From the Configuration menu, select Services.

  2. On your Services page:

    If you are creating a new service for your integration, click +Add New Service.

    If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the +New Integration button.

  3. RS-Add-New-Service
    RS-Add-Integration-Existing-Service

  4. Select Sensu from the Integration Type menu and enter an Integration Name.

    If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.

  5. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.
    RS-Integration-Settings
  6. Copy the Integration Key for your new integration: RS_API_pd_3

On Your Sensu Server

  1. Create a new file for your PagerDuty handler in your Sensu configuration directory with the Integration Key you copied in step 3 above:

    /etc/sensu/conf.d/pagerduty_handler.json
    {
      "pagerduty": {
        "service_key": "YOUR-INTEGRATION-KEY-HERE"
      }
    }
  2. If you want to make PagerDuty a default handler, meaning any check without a specific handler defined will notify PagerDuty when there is an alert, open the default handler configuration file and add pagerduty to the set of handlers:

    /etc/sensu/conf.d/default_handler.json
    {
      "handlers": {
        "default": {
          "type": "set",
          "handlers": [
            "pagerduty"
          ]
        }
      }
    }

    If you do not want PagerDuty to be a default handler, meaning you only want alerts from specifically defined checks to be sent to PagerDuty, open the configuration file for each check you want to send alerts to PagerDuty and add pagerduty to the check’s handlers:

    /etc/sensu/conf.d/YOUR-CHECK.json
    {
      "checks": {
        "YOUR-CHECK-NAME": {
          "command": "YOUR-CHECK-COMMAND",
          "subscribers": [
            "YOUR-SUBSCRIBERS"
          ],
          "interval": YOUR-INTERVAL,
          "handlers": ["default", "pagerduty"]
        }
      }
    }
    
  3. Reload Sensu’s configuration so that the changes take effect: service sensu-enterprise reload

Verify the Integration Works

  1. Create a standard check that monitors the cron service as outlined in the Sensu guide, Getting Started with Checks. Your check will look like this if you made PagerDuty a default handler as outlined in step 2 above:

    /etc/sensu/conf.d/check_cron.json
    {
      "checks": {
        "cron": {
          "command": "/etc/sensu/plugins/check-procs.rb -p cron",
          "subscribers": [
            "test"
          ],
          "interval": 60,
          "handlers": "default"
        }
      }
    }
    

    If you did not make PagerDuty a default handler, you’ll need to specify pagerduty as a in handlers like this:

          "handlers": ["default", "pagerduty"]
    
  2. Reload Sensu’s configuration so that the changes take effect: service sensu-enterprise reload

  3. Confirm that Sensu is working, the cron check you’ve created is OK, and there are no other alerts that have been triggered. Your Dashboard should look like this:

  4. Stop the crond service: service crond stop

  5. Within 60 seconds you should see an alert in Sensu and a new incident triggered in PagerDuty:

FAQ

Can I configure Sensu Enterprise to work with multiple PagerDuty services?

Yes, using Sensu’s Contact Routing feature, you can specify multiple contacts in Sensu, each with a different PagerDuty Integration Key, then update your checks to specify the Sensu contact with the PagerDuty Integration Key you want to receive alerts.