Apache Airflow Providers PagerDuty

A provider package that enables Apache Airflow to integrate with PagerDuty's incident management and monitoring platform. This package provides hooks for interacting with PagerDuty's REST and Events APIs, as well as notification capabilities for workflow alerting and incident response automation.

Package Information

• Package Name: apache-airflow-providers-pagerduty
• Language: Python
• Installation: pip install apache-airflow-providers-pagerduty
• Minimum Airflow Version: 2.10.0

Core Imports

from airflow.providers.pagerduty.hooks.pagerduty import PagerdutyHook
from airflow.providers.pagerduty.hooks.pagerduty_events import PagerdutyEventsHook
from airflow.providers.pagerduty.notifications.pagerduty import PagerdutyNotifier

Basic Usage

Quick Start with PagerDuty Events API

from airflow.providers.pagerduty.hooks.pagerduty_events import PagerdutyEventsHook

# Using connection ID
hook = PagerdutyEventsHook(pagerduty_events_conn_id="my_pagerduty_events")

# Send a trigger event
response = hook.send_event(
    summary="Critical disk space alert",
    severity="critical",
    source="web-server-01",
    custom_details={"disk_usage": "95%", "mount_point": "/var"}
)

# Send a resolve event
hook.send_event(
    summary="Critical disk space resolved",
    severity="info", 
    source="web-server-01",
    action="resolve",
    dedup_key="disk-alert-web-server-01"
)

Using Notifications in DAGs

from airflow import DAG
from airflow.operators.dummy import DummyOperator
from airflow.providers.pagerduty.notifications.pagerduty import PagerdutyNotifier

# Define a notification
notifier = PagerdutyNotifier(
    summary="DAG {{ dag.dag_id }} failed",
    severity="error",
    source="airflow",
    pagerduty_events_conn_id="pagerduty_events_default"
)

# Use in DAG on_failure_callback
dag = DAG(
    'example_dag',
    on_failure_callback=notifier,
    # ... other DAG parameters
)

Architecture

The package provides three main components:

• PagerdutyHook: Interfaces with PagerDuty's REST API v2 for general API operations like service management, incident queries, and user management
• PagerdutyEventsHook: Interfaces with PagerDuty's Events API v2 for incident/alert lifecycle management (trigger, acknowledge, resolve)
• PagerdutyNotifier: Airflow notification system integration for automated alerting on workflow events

Both hooks support connection management through Airflow's connection system, allowing secure credential storage and multiple environment configurations.

Capabilities

REST API Integration

Provides access to PagerDuty's full REST API v2 for comprehensive platform interaction including services, incidents, users, teams, escalation policies, and schedules management.

class PagerdutyHook:
    def __init__(self, token: str = "", pagerduty_conn_id: str | None = None): ...
    def client(self) -> pagerduty.RestApiV2Client: ...
    def test_connection(self): ...

REST API Integration

Events API Integration

Handles incident and alert lifecycle management through PagerDuty's Events API v2, supporting trigger, acknowledge, and resolve actions with full event metadata.

class PagerdutyEventsHook:
    def __init__(self, integration_key: str | None = None, pagerduty_events_conn_id: str | None = None): ...
    def send_event(self, summary: str, severity: str, **kwargs) -> str: ...
    def create_change_event(self, summary: str, **kwargs) -> str: ...
    def test_connection(self): ...

Events API Integration

Notification System

Integrates with Airflow's notification framework to automatically send alerts to PagerDuty based on workflow events, with support for templating and context-aware messaging.

class PagerdutyNotifier:
    def __init__(self, *, summary: str, severity: str, **kwargs): ...
    def notify(self, context): ...
    @property
    def hook(self) -> PagerdutyEventsHook: ...

Notification System

Connection Configuration

The package supports two connection types:

• pagerduty: For REST API operations (requires API token)
• pagerduty_events: For Events API operations (requires integration key)

Both connection types can be configured through Airflow's web interface with appropriate credential fields and validation.