Table of Contents¶

Introduction¶

pagerduty-api is a package for easily interacting with PagerDuty’s API.

Why?¶

There are several other libraries interacting with the PagerDuty API, however none of them include tests and documentation.

Installation¶

To install the latest release, type:

pip install pagerduty-api

To install the latest code directly from source, type:

pip install git+git://github.com/ambitioninc/pagerduty-api.git

Requirements¶

Python 2.7, 3.3, 3,4
requests >= 2.0.0

Usage¶

Configuring Alerts¶

Alerts has an environment variable will need to configure before using.

Using Alerts¶

pagerduty_api comes with an interface for PagerDuty called Alert. All an alert needs to be instantiated is a service_key. This Service API Key is a unique ID generated in PagerDuty for a Generic API Service.

from pagerduty_api import Alert

alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')

Trigger Alert¶

To trigger an alert, use .trigger() on the interface. If you don’t pass in an incident_key, one will be computed as the md5 hash of the description

from pagerduty_api import Alert


alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
alert.trigger(
    description='No data received',
    client='My Client',
    client_url='http://mysite.com',
    details={'some_key': 'some_value'}
)

Acknowledge Alert¶

To acknowledge an alert, use .acknowledge() on the interface. If you created this alert with .trigger(), you won’t need to provide an incident_key.

from pagerduty_api import Alert

alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
alert.acknowledge(
    incident_key='0ace123ba99999160f35ea3bd381a318',
    description='Working on it.',
    details={'some_key': 'some_value'}
)

Resolve Alert¶

To resolve an alert, use .resolve() on the interface. If you created this alert with .trigger(), you won’t need to provide an incident_key.

from pagerduty_api import Alert

alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
alert.resolve(
    incident_key='0ace123ba99999160f35ea3bd381a318',
    description='Fixed it.',
    details={'some_key': 'some_value'}
)

Code Documentation¶

Alert¶

class pagerduty_api.Alert(service_key, *args, **kwargs)¶

An interface for interacting with PagerDuty alerts.

Instantiate with a service API key (A unique id for the service you want to trigger an alert for)

__init__(service_key, *args, **kwargs)¶

Parameters:	service_key (str) – Service API Key is a unique ID generated in PagerDuty for a Generic API Service

trigger(description, incident_key=None, client=None, client_url=None, details=None)¶

Triggers a PagerDuty Alert. See the PagerDuty API trigger docs for more details.

Parameters:

description (str) – A Description of the alert. 1024 character max
incident_key (str) – A unique ID to de-duplicate incident reports. If no key is present, an MD5 hash of the description is used.
client (str) – The name of the monitoring client that is triggering this event. Optional
client_url (str) – The URL of the monitoring client that is triggering this event. Optional
details (dict) – An arbitrary JSON object containing any data you’d like included in the incident log. Optional

Return type:

dict

Returns:

The JSON response of the API

{
    "status": "success",
    "message": "Event processed",
    "incident_key": "srv01/HTTP"
}

acknowledge(incident_key=None, description=None, details=None)¶

Acknowledges a PagerDuty Alert. See the PagerDuty API ack docs for more details.

Parameters:	incident_key (str) – The key for the incident to acknowledge. If None, it will use the incident key assigned when you triggered the alert. description (str) – Text that will appear in the incident’s log associated with this event. Optional details (dict) – An arbitrary JSON object containing any data you’d like included in the incident log. Optional
Raises:	An `IncidentKeyException` if the Alert doesn’t have an incident key and one is not passed to the method
Return type:	dict
Returns:	The JSON response of the API { "status": "success", "message": "Event processed", "incident_key": "srv01/HTTP" }

resolve(incident_key=None, description=None, details=None)¶

Resolves a PagerDuty Alert. See the PagerDuty API resolve docs for more details.

Parameters:	incident_key (str) – The key for the incident to resolve. If None, it will use the incident key assigned when you triggered the alert. description (str) – Text that will appear in the incident’s log associated with this event. Optional details (dict) – An arbitrary JSON object containing any data you’d like included in the incident log. Optional
Raises:	An `IncidentKeyException` if the Alert doesn’t have an incident key and one is not passed to the method
Return type:	dict
Returns:	The JSON response of the API { "status": "success", "message": "Event processed", "incident_key": "srv01/HTTP" }

Internal Resources¶

ConfigurationException¶

class pagerduty_api.exceptions.ConfigurationException¶: An exception for Configuration errors

IncidentKeyException¶

class pagerduty_api.exceptions.IncidentKeyException¶: An exception when no Incident Key exists

PagerDutyAPIServerException¶

class pagerduty_api.exceptions.PagerDutyAPIServerException¶: An exception for Pager Duty server errors

Resource¶

class pagerduty_api.base.Resource¶: A base class for API resources

AuthorizedResource¶

class pagerduty_api.base.AuthorizedResource(api_key=None, *args, **kwargs)¶

A base class for authorized API resources

__init__(api_key=None, *args, **kwargs)¶

Parameters:	api_key (str) – The API key. If no key is passed, the environment variable PAGERDUTY_API_KEY is used.
Raises:	If the api_key parameter is not present, and no environment variable is present, a `ConfigurationException` is raised.

Contributing¶

Contributions and issues are most welcome! All issues and pull requests are handled through github on the ambitioninc repository. Also, please check for any existing issues before filing a new one. If you have a great idea but it involves big changes, please file a ticket before making a pull request! We want to make sure you don’t spend your time coding something that might not fit the scope of the project.

Running the tests¶

To get the source source code and run the unit tests, run:

$ git clone git://github.com/ambitioninc/pagerduty-api.git
$ cd pagerduty-api
$ virtualenv env
$ . env/bin/activate
$ pip install nose
$ python setup.py install
$ python setup.py nosetests

While 100% code coverage does not make a library bug-free, it significantly reduces the number of easily caught bugs! Please make sure coverage is at 100% before submitting a pull request!

Code Quality¶

For code quality, please run flake8:

$ pip install flake8
$ flake8 .

Code Styling¶

Please arrange imports with the following style

# Standard library imports
import os

# Third party package imports
from mock import patch

# Local package imports
from pagerduty_api.version import __version__

Please follow Google’s python style guide wherever possible.

Building the docs¶

When in the project directory:

$ pip install -r requirements/docs.txt
$ python setup.py build_sphinx
$ open docs/_build/html/index.html

Release Checklist¶

Before a new release, please go through the following checklist:

Bump version in pagerduty_api/version.py
Add a release note in docs/release_notes.rst
Git tag the version

Upload to pypi:

pip install wheel
python setup.py sdist bdist_wheel upload

Vulnerability Reporting¶

For any security issues, please do NOT file an issue or pull request on github! Please contact security@ambition.com with the GPG key provided on Ambition’s website.

Release Notes¶

v0.3¶

PAGERDUTY_API_KEY is no longer required for the Alert() object

v0.2¶

This version fixes interaction with PagerDuty’s Events API.

v0.1¶

This is the initial release of pagerduty-api.

Includes the Alert interface
Includes sphinx docs
python 2.7, 3.3, 3.4 compatibility