How to use the Web API tile with PagerDuty
This article covers how to use the Web API tile to display live API data from PagerDuty on a dashboard or perspective.
Dashboard Server uses the PagerDuty account that you configure, and queries will be updated as the page updates, by default every minute.
If you need more information about using the Web API tile in general see
This article covers several areas:
Walkthrough: Adding a Web API tile to a dashboard to show PagerDuty alerts
Walkthrough: Adding a Web API Scalar tile to a dashboard to show PagerDuty incident counts
Prerequisites
- The SquaredUp server must have access to your PagerDuty instance, since it is the server that connects to PagerDuty, and not your users' browser.
- If you use a proxy server you may need to configure the proxy to allow the SquaredUp server to communicate with PagerDuty (How to configure Dashboard Server to use a proxy).
- A PagerDuty account. You may need some help from a PagerDuty admin to get an account with the correct privileges.
Adding a PagerDuty provider in Dashboard Server
Before you configure the Web AP tile for use with PagerDuty you need to create a PagerDuty provider in Dashboard Server.
Adding a provider is a one-time configuration task, and once the provider has been configured it can be used each time you configure a tile.
For PagerDuty the provider must be created as a simple provider:
In Dashboard Server navigate to the right-hand menu ☰ > system > Integrations
Under Integrations click Web API.
Click the authentication type Simple
In the service name box type in a suitable name, e.g. PagerDuty
The base URL should be the current PagerDuty API URL, for example:
https://api.PagerDuty.com/
Under default headers click add
Add the following information to the boxes as shown below:
First box (name):
authorization
Second box (value):Token token=API token from PagerDuty
You can create an API access key (token) by logging in to PagerDuty > Integrations > API Access Keys > Create New API Key, and ticking Read-only API Key. See Generating API Keys
Copy the API access key from PagerDuty before closing the window:Paste into the authorization value box in Dashboard Server, prepended by
Token token=
as shown above.Click Save.
Walkthrough: Adding a Web API tile to a dashboard to show PagerDuty alerts
It is important to use http GET
mode and to set the key path in the response data section to alerts
. This is described in the steps below.
On the top navigation bar in Dashboard Server click the + to create a new dashboard, and give your dashboard a title.
Click on the Web API tile.
Select Web API (Grid).
Leave the scope section blank for this walkthrough.
In the provider section select the PagerDuty provider that you created earlier.
In the http mode section leave the http method set to GET.
Type
alerts
in the box after the URL. The URL shown here is the URL you specified when you created the PagerDuty Web API provider.Leave the headers & data section as it is for this walkthrough.
In the response data section you should see some data in the response data box. If there isn't any data check the configuration of your provider.
Type
alerts
into the key path box.At this point you should see some data returned.
Click next to move to the grid columns section.
Click hide next to some of the columns you might not wish to show, e.g. id, type, summary, self, html_url, resolved_at, alert_key, suppressed, service, incident, first_trigger_log_entry, body, integration, privilege.
You may like to rename the columns to make them more readable, e.g. created_at to Created, status to Status and severity to Severity
To make the created date and time more readable you can use mustache syntax with timeago (How to use Custom Labels) in the custom template. Click edit next to Created and paste the following in to the custom template box:
{{timeago(value)}}
This shows how long ago the alert occurred.
You may like to add further columns for additional data. For help customizing the columns of data see How to use the Grid Designer.You can also add columns.
Click Add, give the column a name, such as
Service
, and in the custom template box click the mustache helper button and select the value you require, for example{{value.service.summary}}
then click done. Leave data key path empty.Other columns you might like to add include:
name:
Message
with custom template:{{value.body.cef_details.message}}
name:
Website
with custom template:{{value.body.cef_details.details.hostname}}
name:
Related Incident
with custom template:{{value.incident.summary}}
You may wish to change the order the columns by dragging them into position.
The Grid Options Row Link property allows you to automatically link each row to a parameterised hyperlink. Click on the mustache helper button and then select
{{incident.html_url}}
from the drop down list.Click done.
Walkthrough: Adding a Web API Scalar tile to a dashboard to show PagerDuty incident counts
It is important to use http GET
mode and to set the key path in the response data section to incidents
.
Click on the Web API tile.
Select Web API (Scalar).
Leave the scope section blank for this walkthrough.
In the provider section select the PagerDuty provider that you created earlier.
In the http mode section leave the http method set to get.
In the box following the URL you need to type
incidents
The headers & data section is where you can pass key variables through to PagerDuty. Click the add button under data to add the following data name and value settings:
name:statuses%5B%5D
value:resolved
Click apply changes.
In the response data section you should see some sample data shown. Type
incidents
into the key path field.Click next to move to the scalar section where you can change the font size if you wish.
Click done.
Repeat the above steps to create two new tiles, one for Triggered and another for Acknowledged substituting the following data name and value settings in lower case in the headers & data section:
name:statuses%5B%5D
value:triggered
name:statuses%5B%5D
value:acknowledged
Hints and Tips
- Look at the PagerDuty API documentation or speak to your PagerDuty expert.
- Use custom labels to improve data formatting see How to use Custom Labels