pagerduty
Provides a lightweight Ruby interface for calling the PagerDuty Events API.
Installation
Add this line to your application's Gemfile:
gem 'pagerduty'
And then execute:
$ bundle
Or install it yourself as:
$ gem install pagerduty
Usage
First, obtain an Events API integration key from PagerDuty. Follow the instructions in PagerDuty's documentation to procure one.
Events API V2
# Instantiate a Pagerduty service object providing an integration key and the
# desired API version: 2
pagerduty = Pagerduty.build(
integration_key: "<integration-key>",
api_version: 2
)
# Trigger an incident providing minimal details
incident = pagerduty.trigger(
summary: "summary",
source: "source",
severity: "critical"
)
# Trigger an incident providing full context
incident = pagerduty.trigger(
summary: "Example alert on host1.example.com",
source: "monitoringtool:cloudvendor:central-region-dc-01:852559987:cluster/api-stats-prod-003",
severity: %w[critical error warning info].sample,
timestamp: Time.now,
component: "postgres",
group: "prod-datapipe",
class: "deploy",
custom_details: {
ping_time: "1500ms",
load_avg: 0.75
},
images: [
{
src: "https://www.pagerduty.com/wp-content/uploads/2016/05/pagerduty-logo-green.png",
href: "https://example.com/",
alt: "Example text",
},
],
links: [
{
href: "https://example.com/",
text: "Link text",
},
],
client: "Sample Monitoring Service",
client_url: "https://monitoring.example.com"
)
# Acknowledge and/or resolve the incident
incident.acknowledge
incident.resolve
# Provide a client-defined incident key
# (this can be used to update existing incidents)
incident = pagerduty.incident("<incident-key>")
incident.trigger(
summary: "summary",
source: "source",
severity: "critical"
)
incident.acknowledge
incident.resolve
See the PagerDuty Events API V2 documentation for a detailed description on the parameters you can send when triggering an incident.
Events API V1
The following code snippet shows how to use the Pagerduty Events API version 1.
# Instantiate a Pagerduty with a service integration key
pagerduty = Pagerduty.build(
integration_key: "<integration-key>",
api_version: 1,
)
# Trigger an incident
incident = pagerduty.trigger(
"FAILURE for production/HTTP on machine srv01.acme.com",
)
# Trigger an incident providing context and details
incident = pagerduty.trigger(
"FAILURE for production/HTTP on machine srv01.acme.com",
client: "Sample Monitoring Service",
client_url: "https://monitoring.service.com",
contexts: [
{
type: "link",
href: "http://acme.pagerduty.com",
text: "View the incident on PagerDuty",
},
{
type: "image",
src: "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1",
}
],
details: {
ping_time: "1500ms",
load_avg: 0.75,
},
)
# Acknowledge the incident
incident.acknowledge
# Acknowledge, providing a description and extra details
incident.acknowledge(
"Engineers are investigating the incident",
{
ping_time: "1700ms",
load_avg: 0.71,
}
)
# Resolve the incident
incident.resolve
# Resolve, providing a description and extra details
incident.acknowledge(
"A fix has been deployed and the service has recovered",
{
ping_time: "120ms",
load_avg: 0.23,
}
)
# Provide a client defined incident key
# (this can be used to update existing incidents)
incident = pagerduty.incident("<incident-key>")
incident.trigger("Description of the event")
incident.acknowledge
incident.resolve
See the PagerDuty Events API V1 documentation for a detailed description of the parameters you can send when triggering an incident.
HTTP Proxy Support
One can explicitly define an HTTP proxy like this:
pagerduty = Pagerduty.build(
integration_key: "<integration-key>",
api_version: 2, # The HTTP proxy settings work with either API version
http_proxy: {
host: "my.http.proxy.local",
port: 3128,
username: "<my-proxy-username>",
password: "<my-proxy-password>",
}
)
# Subsequent API calls will then be sent via the HTTP proxy
incident = pagerduty.trigger(
summary: "summary",
source: "source",
severity: "critical"
)
Debugging Error Responses
The gem doesn't encapsulate HTTP error responses from PagerDuty. Here's how to go about debugging these unhappy cases:
begin
pagerduty.trigger(
summary: "summary",
source: "source",
severity: "critical"
)
rescue Net::HTTPClientException => error
error.response.code #=> "400"
error.response. #=> "Bad Request"
error.response.body #=> "{\"status\":\"invalid event\",\"message\":\"Event object is invalid\",\"errors\":[\"Service key is the wrong length (should be 32 characters)\"]}"
end
Contributing
- Fork it ( https://github.com/envato/pagerduty/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request