Documentation Plugins PagerDuty

PagerDuty data source

The PagerDuty data source plugin allows you to query incident data from PagerDuty and visualize it in Grafana dashboards. You can list and filter incidents, retrieve individual incident details, and overlay incidents as annotations on other data.

Supported features

The following table lists the features supported by the PagerDuty data source.

Before you begin

Before configuring the PagerDuty data source, ensure you have:

• A Grafana Cloud Pro or Advanced plan or an activated on-prem Grafana Enterprise license. Self-hosted installations require Grafana version 11.6.7 or later.
• A PagerDuty account with a REST API key. Refer to the PagerDuty REST API Keys documentation for instructions on generating an API key. Because this plugin only reads data from PagerDuty, prefer generating a read-only API key.
• Grafana permissions: Organization administrator role to add and configure data sources.

Configure the data source

To start querying PagerDuty data, add and configure the data source in Grafana.

Add the data source

To add the PagerDuty data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type PagerDuty in the search bar.
4. Select PagerDuty.
5. Click Add new data source.

Authentication

The PagerDuty data source authenticates using an API key.

Optional settings

The following optional settings are available under Optional Settings in the configuration editor.

Verify the connection

Click Save & test to verify that the data source is configured correctly. A successful connection displays the message PagerDuty API datasource connected successfully.

Provision the data source

You can define the PagerDuty data source in YAML files as part of Grafana’s provisioning system. For more information, refer to Provisioning Grafana data sources.

YAML Copy

apiVersion: 1

datasources:
  - name: PagerDuty
    type: grafana-pagerduty-datasource
    jsonData:
      auth:
        id: api_key
    secureJsonData:
      auth.api_key.apiKey: <API_KEY>

You can also provision the data source using the Grafana Terraform provider:

hcl Copy

resource "grafana_data_source" "pagerduty" {
  type = "grafana-pagerduty-datasource"
  name = "PagerDuty"

  json_data_encoded = jsonencode({
    auth = {
      id = "api_key"
    }
  })

  secure_json_data_encoded = jsonencode({
    "auth.api_key.apiKey" = var.pagerduty_api_key
  })
}

Query the data source

The query editor has the following controls:

1. Category – Select the query category. PagerDuty has a single category: Incidents.
2. Action – Select the operation to perform from the drop-down.
3. Additional parameters (optional) – Expand this collapsible section to configure filters and options. For List incidents, this section starts collapsed.
4. Transformation options – Expand this collapsible section to select which fields to return.

List incidents

The List incidents action retrieves a paginated list of incidents. By default, the Since and Until parameters use the dashboard time range variables ${__from:date} and ${__to:date}, returning only incidents created within the selected time frame. Clear these fields to query all incidents.

Expand the Additional parameters (optional) section to configure the following filters.

Example: Monitor unresolved incidents by service

To build a table showing all currently open incidents for a specific service:

1. Select List incidents from the Action drop-down.
2. Set Statuses to triggered and acknowledged.
3. Enter your PagerDuty service ID in the Service IDs field.
4. Set Sort by to created_at:desc to show the most recent incidents first.
5. Expand Transformation options and select the following fields under Select fields: title, status, urgency, created_at, and html_url.
6. Choose the Table visualization to display the results.

Example: Track incident volume over time

To visualize how many incidents your team handles over time:

1. Select List incidents from the Action drop-down.
2. Set the dashboard time range to the period you want to analyze (for example, Last 30 days).
3. Enter your team ID in the Team IDs field.
4. Expand Transformation options and select created_at and status under Select fields.
5. Choose the Bar chart or Time series visualization.
6. Use a Group by transformation to aggregate incident counts by day or week.

Example: View high-urgency incidents across all services

To create an overview of high-urgency incidents that need immediate attention:

1. Select List incidents from the Action drop-down.
2. Set Urgencies to high.
3. Set Statuses to triggered.
4. Clear the Since and Until fields to return incidents regardless of when they were created.
5. Expand Transformation options and select: title, service, created_at, escalation_policy, and html_url under Select fields.
6. Choose the Table visualization and use the html_url field to link directly to each incident in PagerDuty.

Get an incident

The Get an incident action retrieves detailed information about a single incident. The required Id field appears under the Parameters section.

Select fields

Expand the Transformation options section and use the Select fields drop-down to choose which fields to include in the query results. If no fields are selected, all available fields are returned.

Available fields for List incidents include: id, summary, type, self, html_url, incident_number, title, description, created_at, updated_at, status, incident_key, service, assignments, assigned_via, last_status_change_at, resolved_at, first_trigger_log_entry, alert_counts, is_mergeable, escalation_policy, teams, pending_actions, acknowledgements, alert_grouping, last_status_change_by, priority, resolve_reason, incidents_responders, responder_requests, and urgency.

The Get an incident action supports the same fields except description, and additionally includes conference_bridge.

The fields created_at, updated_at, resolved_at, and last_status_change_at are automatically parsed as timestamps.

Annotations

You can use annotations to overlay PagerDuty incidents on other dashboard panels. This helps you correlate incidents with metrics and logs from other data sources.

To add a PagerDuty annotation:

1. Open your dashboard and click Settings (gear icon).
2. Select Annotations and click Add annotation query.
3. Select the PagerDuty data source.
4. Choose List incidents from the Action drop-down.
5. Configure any filters you need, such as Statuses or Service IDs.
6. Click Save dashboard.

Incidents are mapped to annotations using the timestamp fields (created_at, updated_at, resolved_at, or last_status_change_at). Use the Select fields drop-down under Transformation options to control which fields appear in the annotation tooltip.

Example: Correlate incidents with infrastructure metrics

To overlay PagerDuty incidents on a time series panel that shows CPU or memory usage from another data source:

1. Create a dashboard panel with your infrastructure metrics (for example, from Prometheus or CloudWatch).
2. Open Dashboard settings > Annotations and click Add annotation query.
3. Select the PagerDuty data source.
4. Choose List incidents from the Action drop-down.
5. Set Service IDs to the service that matches the infrastructure being monitored.
6. Set Statuses to triggered and acknowledged to show only active incidents.
7. Expand Transformation options and select title and status under Select fields so the annotation tooltip shows useful context.
8. Click Save dashboard.

Incident markers now appear on the time series panel, making it easy to see whether a spike in resource usage corresponds to a PagerDuty incident.

For more information about annotations, refer to Annotate visualizations.

Template variables

Template variables let you create dynamic, reusable dashboards. You can use the PagerDuty data source as a query variable source.

To create a PagerDuty query variable:

1. Navigate to Dashboard settings > Variables.
2. Click Add variable.
3. Select Query as the variable type.
4. Select the PagerDuty data source.
5. Choose an action from the Action drop-down (for example, List incidents).
6. Use the Select fields drop-down to choose which fields to return.

After creating a variable, reference it in your PagerDuty queries using variable syntax. For more information, refer to Templates and variables.

Example: Filter incidents by variable

To create a dashboard where users can select an incident from a drop-down and view its details:

1. Create a query variable named incident using the PagerDuty data source.
2. Select List incidents from the Action drop-down.
3. Under Select fields, choose summary first (label), then id (value).
4. In your panel query, select Get an incident from the Action drop-down and enter $incident in the Id field.

When users select an incident from the dashboard drop-down, the panel updates to show that incident’s details.

Example: Filter by status using a custom variable

To let users toggle between viewing triggered, acknowledged, or resolved incidents:

1. Navigate to Dashboard settings > Variables and click Add variable.
2. Select Custom as the variable type.
3. Name the variable status.
4. Enter triggered,acknowledged,resolved in the Custom options field.
5. Enable Multi-value to allow users to select more than one status.
6. In your panel query, select List incidents from the Action drop-down and enter $status in the Statuses field.

The dashboard drop-down now lets users control which incident statuses are displayed.

Alerting

You can create Grafana alert rules that query PagerDuty incident data. For example, you can alert when the number of triggered incidents exceeds a threshold or when high-urgency incidents remain unacknowledged.

To create an alert rule using PagerDuty data:

1. Navigate to Alerting > Alert rules.
2. Click New alert rule.
3. Select the PagerDuty data source.
4. Configure a List incidents query with the appropriate filters (for example, Statuses set to triggered and Urgencies set to high).
5. Add a Reduce expression to aggregate the results (for example, count rows).
6. Add a Threshold expression to define the alert condition.
7. Configure notification policies and contact points as needed.

For more information, refer to Grafana Alerting.

Plugin updates

Always ensure that your plugin version is up-to-date so you have access to all current features and improvements. Navigate to Plugins and data > Plugins to check for updates. Grafana recommends upgrading to the latest Grafana version, and this applies to plugins as well.

Related resources

• Troubleshoot PagerDuty data source issues
• PagerDuty REST API documentation
• Explore
• Transformations
• Alerting
• Grafana community forum