Contact Routing

Reference documentation

• What is contact routing?
• How does contact routing work?
• Contact Routing configuration
  • Example Contact Routing definition
  • Contact Routing definition specification
    • CONTACT attributes
    • Severities

What is contact routing?

Every incident or outage has an ideal first responder, a team or individual with the knowledge to triage and address the issue. Sensu Enterprise contact routing makes it possible to assign checks to specific teams and/or individuals, reducing mean time to response and recovery (MTTR). Contact routing works with all of the Sensu Enterprise third-party notification and metric integrations.

NOTE: Sensu Enterprise supports contact routing for all integrations except EC2, Puppet, Chef, Flapjack, and Event Stream.

How does contact routing work?

Sensu Enterprise contacts are defined in JSON configuration files, which we recommend to store in the /etc/sensu/conf.d/contacts/ directory. A contact is composed of a name and configuration overrides for one or more of Sensu Enterprise’s built-in integrations. A contact in Sensu Enterprise is not too dissimilar from a contact on your phone, which usually have a name and one or more identifiers for various communication channels (e.g. a phone number, email address, Twitter username, etc).

The following example contact definition provides overrides for the Sensu Enterprise email and Slack integration default configuration settings.

{
  "contacts": {
    "support": {
      "email": {
        "to": "support@sensuapp.com"
      },
      "slack": {
        "channel": "#support"
      }
    }
  }
}

Once defined, Sensu Enterprise contacts are used the same way in which you use contacts on your phone – by selecting a communication channel (e.g. phone call, SMS, email, etc) – and then selecting the contact. With Sensu Enterprise contact routing, the communication channels are built-in handlers (integrations), and the selection of which channel to use is managed by a check definition (or client definition).

The following example check definition will use the built-in Sensu Enterprise email integration (event handler), notifying the support contact for any corresponding events.

{
  "checks": {
    "example_check": {
      "command": "do_something.rb",
      "interval": 30,
      "handler": "email",
      "contact": "support"
    }
  }
}

Contact routing configuration

Example contact routing definition

The following is an example contact routing definition (i.e. a “contact”), a JSON configuration file located at /etc/sensu/conf.d/contacts/ops.json.

{
  "contacts": {
    "support": {
      "pagerduty": {
        "routing_key": "r3FPuDvNOTEDyQYCc7trBkymIFcy2NkE"
      },
      "slack": {
        "channel": "#support",
        "username": "sensu"
      }
    }
  }
}

Contact Routing definition specification

Contact names

Each contact routing definition has a unique contact name, used for the definition key. All contacts must be defined within the "contacts": {} configuration scope, and comply with the following requirements:

• A unique string used to name/identify the check
• Cannot contain special characters or spaces
• Validated with Ruby regex /^[\w\.-]+$/.match("check-name")

CONTACT attributes

Contact routing attributes are configured within the { "contacts": { "CONTACT": {} } } configuration scope (where CONTACT is a valid contact name). Contact definition attributes are configuration overrides for built-in integrations (e.g. Email, Slack, PagerDuty, ServiceNow etc; see the built-in handlers reference documentation for a complete listing).

EXAMPLES

In most cases, contact definitions are used to provide partial integration handler attribute overrides. The following example only provides a "to" (recipient) attribute to override the default email integration configuration:

{
  "contacts": {
    "support": {
      "email": {
        "to": "support@example.com"
      }
    }
  }
}

However, contact definitions are not limited to providing a single attribute — they can be used to provide multiple attributes or even complete integration handler definitions (potentially overriding the entire default definition). For example, a contact could be used to provide an email integration definition to use an alternate SMTP server from the default configuration:

{
  "contacts": {
    "support": {
      "email": {
        "smtp": {
          "address": "smtp.support.example.com",
          "port": 587,
          "openssl_verify_mode": "none",
          "enable_starttls_auto": true,
          "authentication": "plain",
          "user_name": "postmaster@support.example.com",
          "password": "SECRET"
        },
        "to": "support@support.example.com",
        "from": "noreply@support.example.com"
      }
    }
  }
}

Severities

You can use the severities attribute to configure the event severities that Sensu Enterprise will route to a contact. However, unlike other contact attributes, the severities attribute doesn’t override severities configured in the integration handler definition. Sensu Enterprise processes contact-configured severities after integration-configured severities, so contacts can only access severities allowed by the integration configuration.

For example, the following PagerDuty integration configuration sends alerts for only warning and critical severities.

{
  "pagerduty": {
    "routing_key": "r3FPuDvNOTEDyQYCc7trBkymIFcy2NkE",
    "timeout": 10,
    "severities": ["warning", "critical"]
  }
}

Therefore, contacts using the integration above only have access to warning and critical alerts. The following example shows a contact configured to receive alerts through the PagerDuty integration shown above, but filtered for only critical alerts. As with integration-configured severities, event resolution bypasses this filtering.

{
  "contacts": {
    "support": {
      "pagerduty": {
        "routing_key": "s2TZrJmMTTTHDfSMFe3woPqenBCxa7WtY",
        "severities": ["critical"]
      }
    }
  }
}

 "severities": ["critical", "unknown"]