PagerDuty Responder user guide - snowplow-archive/sauna GitHub Wiki

HOME > GUIDE FOR ANALYSTS > RESPONDERS > PagerDuty Responder user guide

This responder has not yet been implemented.

See also: PagerDuty Responder setup guide

• 1. Overview
• 2. Responder actions
  • 2.1 Create event (real-time)
    • 2.1.1 Overview
    • 2.1.2 Command format
    • 2.1.3 Example command
    • 2.1.4 Response algorithm
    • 2.1.5 Usage examples
      • 2.1.5.1 Kinesis stream

This responder lets you send events to the PagerDuty incident management platform. These events can either trigger a new incident, forwarding it to various monitoring tools and ticketing systems, or acknowledge and fix existing incidents.

Currently this responder only supports one action:

This responder command lets you send an event using the PagerDuty event format. PagerDuty events have three different types:

• trigger - either open a new incident or add a new log entry to an existing incident. Should be used to report a new problem.
• acknowledge - marks an incident as acknowledged, preventing it from generating additional notifications. Should be used to notify PagerDuty that someone is currently working on a problem.
• resolve - marks an incident as resolved. Should be used to mark a problem as fixed.

Like all real-time responder actions, this action is triggered by a well-structured JSON command being received by a compatible observer.

The command must be configured using a self-describing JSON Schema which validates against this schema:

iglu:com.pagerduty.sauna.commands/create_event/jsonschema/1-0-0

A simple PagerDuty command will look as follows:

{
  "schema": "iglu:com.pagerduty.sauna.commands/create_event/jsonschema/1-0-0",

  "data": {
    "service_key": "e93facc04764012d7bfb002500d5d1a6",
    "event_type": "trigger",
    "description": "Awesome Project build failing! [ReferenceError - UI is not defined]",
    "client": "Sauna RT",
    "client_url": "https://example.com",
    "details": {
      "project": "Awesome Project",
      "changeset": "d190bf4"
    },
    "contexts": [ 
      {
        "type": "link",
        "href": "https://example.com/logs/d190bf4",
        "text": "View the build's changeset"
      }
    ]
  }
}

Where:

• service_key is the GUID of your API integration - it is located on the integration's details page.
• event_type is the type of the event. trigger means that this event will open a new incident and return its' incident_key as a response.
• description is the text associated with this event that will appear in an incident log.
• client and client_url are the name and URL of the monitoring client that is triggering this event.
• details is an arbitrary JSON object containing any data you'd like to include in the incident log.
• context is an array of objects to be included in the trigger event, such as links or images.

As with all RT responders, Sauna will take each command and:

1. Validate it as a valid PagerDuty event command
2. If it is not valid, this will be reported to any configured Sauna loggers
3. If it is valid, Sauna will attempt to POST the event to https://events.pagerduty.com/generic/2010-04-15/create_event.json using the command's data
4. If the API reports success (200), this will be reported to any configured Sauna loggers
5. If the API reports failure (400/403/etc), this will be reported to any configured Sauna loggers but no retry will be attempted

In the case of failure, we do not attempt retry, even in the case of us temporarily exceeding API rate limits, because this could block other non-PagerDuty-related commands in the observed stream from executing.

Assuming that the Amazon Kinesis Observer receives the following command:

{
  "schema": "iglu:com.snowplowanalytics.sauna.commands/command/jsonschema/1-0-0",

  "data": {
    "envelope": {
      "schema": "iglu:com.snowplowanalytics.sauna.commands/envelope/jsonschema/1-0-0",
      "data": {
        "commandId": "9dadfc92-9311-43c7-9cee-61ab590a6e81",
        "whenCreated": "2017-01-02T19:14:42Z",
        "execution": {
          "semantics": "AT_LEAST_ONCE",
          "timeToLive": 1200000
        },
        "tags": {}
      }
    },
    "command": {
      "schema": "iglu:com.pagerduty.sauna.commands/create_event/jsonschema/1-0-0",
      "data": {
        "service_key": "e93facc04764012d7bfb002500d5d1a6",
        "event_type": "acknowledge",
        "incident_key": "srv01/HTTP"
      }
    }
  }
}

And assuming that the current time is within 20 minutes (1,200,000 ms) of 2017-01-02T19:14:42Z, then:

• Sauna will send a new acknowledge event to PagerDuty. The event will mark an incident identified by incident_key as being worked on - this will prevent it from sending new notifications, but won't close it.
• Whether or not the event was successfully send wil be reported to any configured Sauna loggers.