If there is not an out-of-the-box integration for your tool, you can create an Events API integration for as long as your system can make outbound HTTP calls.
To add a generic integration:
- Go to Configuration → Services.
- If you are creating a new service for your integration, click Add New Service. If you are adding your integration to an existing service, click the name of the service you want to add the integration to, go to the Integrations tab, then click New Integration.
- Select Use our API Directly from the Integration Type menu, select whether you would like to use Events API v1 or v2, and and enter an Integration Name. If you are creating a new service for your integration, under General Settings, enter a Name for your new service. Under Incident Settings, select an Escalation Policy, Notification Urgency, and Incident Behavior.
- Click Add Service/Integration and an integration key will be generated. You'll find this key on the Integrations tab. Use this key in your monitoring tool to send events to PagerDuty, which create incidents on your service.
Events APIs allows monitoring tools to directly send events in the PD-CEF format. If you are using custom monitoring you can also leverage this format to take advantage of PD-CEF's display and workflow features.
You'll be prompted to choose Events API v1 or v2 when you select Use our API directly from the Integration Type menu.
You must have Create alerts and incidents enabled to use Events API v2. This setting is under Incident Behavior at the bottom of your service configuration screen. When an Events API v2 integration type is selected the Create incidents option will be grayed out.
Events API v2 is designed to handle machine-generated monitoring and event data, such as infrastructure monitoring (Nagios, SignalFX, Datadog), application performance monitoring (New Relic, AppDynamics), and external site checks (Pingdom, Wormly). PD-CEF events generate alerts in PagerDuty, which can then be grouped together under PagerDuty incidents.
For human-generated events, tickets, or incidents, such as those from ServiceNow or JIRA, we suggest using the Events API v2, which enables direct, streamlined creation of PagerDuty incidents.
If you are using a custom monitoring tool, library, or script that has not yet been updated to v2, you should use Events API v1.
A service may represent an application, component, or team you wish to open incidents against.
If a tool cannot integrate via the API, you can use an email integration to integrate with any monitoring tool that can send emails (even in-house solutions).
You can access all services by going to Configurations → Services. If you are creating a new service, click Add New Service. Otherwise, you can skip to adding integrations to an existing service.
Give your service a name. Then select your app from the Integration Type menu and enter an integration name.
There are 4 integration types:
- Select a Tool. Check to see if we have an existing integration for your service. Search for your service by clicking on the dropdown menu next to Integration Type.
- Integrate via Email. If your service can send email, you can create an integration email address.
- Use our API directly. If your service is able to make HTTP calls, you can trigger, acknowledge, and resolve incidents via our API. Our developer documentation provides several examples.
- Don't use an integration. Choose this option if you only wish to manually created incidents.
You can add more than one integration on a service. This enables you to represent the actual entities you are monitoring, managing, and operating as services in PagerDuty. Entities can be applications, micro-services in an application’s architecture, or cross-cutting shared infrastructure (such as networks, security, etc.).
This allows you to consolidate integrations under one service. With integrations consolidated under one service, you get proper service-level reporting in our Analytics module.
- Go to Configurations → Services and select a service to add an integration to. Open the Integrations tab and click New Integration.
- Select your integration type as described above and name your integration.
- Click Save.
You can also move an integration to another service. For more information on this, please check out our article on moving integrations to another service.
For additional tips on how to use multiple integrations to represent your systems, please check out our best practices article here.
If an integration is no longer needed, it can be deleted. A deleted integration cannot be recovered. You will need to create a new integration of the same type on the service should you wish to use that integration again.
If you'd like to instead temporarily deactivate an integration, you can either place the service in maintenance mode, or temporarily move the integration to an inactive service.
- Find the integration to delete by going to Configurations → Services → Integrations.
- Click the gear icon for the integration and select Delete.
When an integration is deleted, we do not remove the incidents. There are no changes to the open or resolved incidents.
Disabling a service is a good choice in the following cases:
- A service is no longer in use and you want to preserve its settings for future use.
- Prevent incidents from triggering.
Disabling a service is very similar to putting a service in maintenance mode. New incidents will not trigger while a service is in either of these states.
The main difference is that a maintenance window will eventually end and bring a service back online. A disabled service must be manually re-enabled.
- Go to the Configuration menu and select Services.
- Click on the name of the service you would like to disable.
- Click Disable Service on the right-hand sight of the page and then click OK on the confirmation dialog.
- Go to the Configuration menu and select Services.
- Click on the name of the service you would like to enable.
- Click on the Enable this service button, and your service will be enabled.
If an email that triggered an incident is not displayed in its entirety in PagerDuty it may have been truncated due to its size.
If the email (including headers, attachments, etc.) is under 96 KB the message can pass through without truncation. If the message is over 96 KB the following can happen:
- Any parts of the email body where the Content-Type are not matched by this regular expression will be discarded:
This means PDF files and similar attachments will be stripped.
- Text parts (Content-Type of
text/html) will be truncated to 32 KB.
- If the resulting total email size (including headers, attachments, etc.) still exceeds 192 KB then we will reject the message.
You can tell if a message has been truncated or had attachments removed by checking for the headers
X-PagerDuty-Removed-Attachments when viewing the raw message. You can view the raw message on the incident's individual page by clicking View Message on an incident log entry, then View Raw Message.
If an email is over 10 MB, our server will reject it.
If the incident key of the email that triggered an incident is more than 255 characters it will be truncated to 255 characters.
When you receive a PagerDuty email notification, the "Details" section of each incident will be truncated to 500 characters. That said, the entire email body is accessible in the PagerDuty web UI via the incident logs and details, or via the mobile app.
You have the ability to move an integration from one service to another if need be. You can move integrations between as many services as needed, as many times as needed and all incidents tied to that integration will follow.
Your integration key will not change after moving the integration from one service to another.
- Go to Configuration → Services.
- Click on the service which contains the integration you would like to move.
- Go to the Integrations tab on the service's page. Then use the settings gear next to the integration to select Move to Another Service. You have the option rename the integration before or after moving it.
If the settings on the service you are moving an integration to differ from the current service, you'll receive a warning message with the option to proceed or cancel.
- Select the Destination Service where you would like the Integration to move to, and click Move Integration.
The easiest way to create a service and integration is in the PagerDuty web UI, however, you can create a service with a vendor-specific integration via the API.
You’ll need to know the vendor_id. Although we haven’t documented the vendor API, it follows the same pattern as our other APIs. Here's an example using PDJS to look up vendor_id: http://jsfiddle.net/8fxudqbj/6/.
Note: You will need a v1 API key to use this JSFiddle.
Here is a list of common vendor_ids:
After finding the right
vendor_id, you'll need to POST the new service to the services endpoint with