Pagerduty API service (alert)

Posted on Thursday, October 9, 2014


This guide will walk through setting up a RESTful API service in pagerduty and call it using Advanced REST client tool.  You could of course use curl, but I prefer the Google Chrome Extension Advanced RESTClient.  If you are unfamiliar with the Advanced REST client tool I did a write up on it at http://www.whiteboardcoder.com/2014/10/chrome-extensions-advanced-rest-client.html


This guide assumes you already have a pagerduty account and understand the basics, like how to create an escalation policy.  If you don’t check out my guide at http://www.whiteboardcoder.com/2014/08/pagerduty-getting-started.html




For more detailed information about pagerduty's APIs check out these links http://developer.pagerduty.com/documentation/integration/events [1]
And very specific info on the json format for triggering events can be found at http://developer.pagerduty.com/documentation/integration/events/trigger [2]




Create the service



Login to pagerduty





Click on Services







Click on "+ Add New Service









Give it a name and select an escalation Policy.









Select "Use our API directly and click on Add Service.












Copy the Service API Key.  






Use the REST API


To trigger the event you need to POST a JSON file to pagerduty's REST API.

The URL to POST to is
https://events.pagerduty.com/generic/2010-04-15/create_event.json


I am going to use the Google Chrome Extension "Advanced Rest Client API" to POST to the given pagerduty URL







Here is the JSON payload I sent. 



{
    "service_key": "59XXXXXXXXXXd",
    "event_type": "trigger",
    "incident_key": "server-01-issue",
    "description": "FAILURE for production server open http://www.example.com",
    "client":"http://www.example.com",
    "client_url": "http://www.example.com",
    "details": {
        "ping time": ">1500ms",
        "load avg": 0.75,
        "message": "I'm gonna sing the doom song http://youtu.be/LQKag_OBHqc"
    }
}



Put your own service API key in this JSON and POST it.







If you are using Advanced Rest Client just click Send.








You should get back this response.

Which means you successfully triggered the event.





CURL


Here is an example using the curl command line tool.  (put in your own API service_key)



   >  curl -H "Content-type: application/json" -X POST \
    -d '{   
      "service_key": "59XXXXXXXd",
      "event_type": "trigger",
      "incident_key": "server-01-issue",
      "description": "FAILURE for production server open http://www.example.com",
      "client": "http://www.example.com",
      "client_url": "http://www.example.com",
      "details": {
        "ping time": "1500ms",
        "load avg": 0.75,
        "message": "I\u0027m gonna sing the doom song http://youtu.be/LQKag_OBHqc"
      }
    }' \
    "https://events.pagerduty.com/generic/2010-04-15/create_event.json"





JSON format


Let me go into a little detail on the JSON format.


{
    "service_key": "59XXXXXXXXXXd",
    "event_type": "trigger",
    "incident_key": "server-01-issue",
    "description": "FAILURE for production server open http://www.example.com",
    "client":"http://www.example.com",
    "client_url": "http://www.example.com",
    "details": {
        "ping time": ">1500ms",
        "load avg": 0.75,
        "message": "I'm gonna sing the doom song http://youtu.be/LQKag_OBHqc"
    }
}


client and client_url

After creating an incident, if you look at the Pagerduty dashboard






You will see in the details the linkfrom client_url!  This can be very useful!  I recommend using putting in a good URL that can help you diagnose your systems (maybe a link to your Sensu/Nagios/Splunk Servers)







{
    "service_key": "59XXXXXXXXXXd",
    "event_type": "trigger",
    "incident_key": "server-01-issue",
    "description": "FAILURE for production server open http://www.example.com",
    "client":"http://www.example.com",
    "client_url": "http://www.example.com",
    "details": {
        "ping time": ">1500ms",
        "load avg": 0.75,
        "message": "I'm gonna sing the doom song http://youtu.be/LQKag_OBHqc"
    }
}



Use the details section to put information in the message!






Open the incident and click on View Message










The JSON is within the message and URL links even work from the WebApp and from iOS and I believe the android app.







Looking at the iOS you need to open the message then the links are clickable (even though they don't look like it…. Maybe something that needs to be tweaked in the next Pagerduty app update…)



If your contact info is set up to email you and you happen to use Gmail, your email will look like this when you open it.






It's even smart enough to show the YouTube video I linked to.





That's it for this write up I hope it helps you create your own Pagerduty API services (alerts). 




Future Development


I hope to work with Twilio and Parse Cloud code in the next few weeks to get a Twilio phone number to trigger a Pagerduty API service (alert).  I already did a write up on how to use Twilio and Twimlets to trigger an email Pagerduty service (alert), which you can read here http://www.whiteboardcoder.com/2014/10/setting-up-phone-number-to-activate.html

 I think using Twilio with Parse Cloud Code to trigger a Pagerduty API service will be much cleaner and give you a lot more capabilities, especially on the Twilio side.






References
[1]        Pagerduty Developer Integration API
                        http://developer.pagerduty.com/documentation/integration/events
                Accessed 10/2014
[2]        Pagerduty Developer Trigger Events
                        http://developer.pagerduty.com/documentation/integration/events/trigger

                Accessed 10/2014 





This post is a part of and epic, the pagerduty and twilio epic.

Epic Goal:   Set up a phone number, via twillio, that when called will set off a pagerduty event.

No comments:

Post a Comment