|
| 1 | +--- |
| 2 | +title: "pgDash alert integration" |
| 3 | +description: "Send pgDash PostgreSQL monitoring alerts to Flashduty On-call through webhooks." |
| 4 | +keywords: ["alert integration", "pgDash", "PostgreSQL", "database monitoring", "webhook"] |
| 5 | +--- |
| 6 | + |
| 7 | +Use pgDash webhook notifications to send PostgreSQL monitoring alerts to Flashduty On-call. Each pgDash server maps to one Flashduty alert: it triggers or updates when alert rules fire on the server, and recovers automatically when all of its alerts clear. |
| 8 | + |
| 9 | +<div className="hide"> |
| 10 | + |
| 11 | +## In Flashduty On-call |
| 12 | +--- |
| 13 | + |
| 14 | +You can get the integration push URL in either of the following ways. |
| 15 | + |
| 16 | +### Use a dedicated integration |
| 17 | + |
| 18 | +1. In the Flashduty console, select **Channel** and open a channel |
| 19 | +2. Select **Configuration** → **Integrations** → **Private integration**, then click **Add an integration** |
| 20 | +3. Select **pgDash** and click **Save** |
| 21 | +4. Open the new integration card and copy the **Push URL** |
| 22 | + |
| 23 | +### Use a shared integration |
| 24 | + |
| 25 | +1. In the Flashduty console, select **Integration Center → Alert Events** |
| 26 | +2. Select **pgDash** and enter an integration name |
| 27 | +3. Configure the default route and select a channel. You can add more rules under **Routes** after creation |
| 28 | +4. Click **Save** and copy the generated **Push URL** |
| 29 | + |
| 30 | +</div> |
| 31 | + |
| 32 | +## Configure pgDash |
| 33 | +--- |
| 34 | + |
| 35 | +The setup is the same for pgDash SaaS and self-hosted pgDash. Webhooks require pgDash 2.4.11 or later. |
| 36 | + |
| 37 | +<Steps> |
| 38 | +<Step title="Set alert rules"> |
| 39 | + |
| 40 | +1. Sign in to pgDash and select the server to connect from the server list |
| 41 | +2. Select **Alerts** in the left menu and add server, database, table, or tablespace level rules as needed. Each rule can be a warning or a critical alert |
| 42 | + |
| 43 | +Alert rules are evaluated each time pgDash receives a pgmetrics report for the server. |
| 44 | + |
| 45 | +</Step> |
| 46 | + |
| 47 | +<Step title="Enter the webhook URL"> |
| 48 | + |
| 49 | +1. On the server's **Alerts** page, find the webhook URL field under **Notification Settings** |
| 50 | +2. Enter the full Flashduty push URL (including `integration_key`). An `https` URL must have a valid certificate |
| 51 | +3. Click **Update** to save |
| 52 | + |
| 53 | +Webhooks are set per server. To connect more servers, repeat this step for each server. They can share the same push URL. |
| 54 | + |
| 55 | +</Step> |
| 56 | +</Steps> |
| 57 | + |
| 58 | +<Warning> |
| 59 | +Enter this push URL only on the **Alerts** page. Notifications from the **Change Alerts** page carry no alert state; when they reach this integration, Flashduty returns success and creates no alert. |
| 60 | +</Warning> |
| 61 | + |
| 62 | +## Alert lifecycle |
| 63 | +--- |
| 64 | + |
| 65 | +pgDash webhooks are edge-triggered: a notification is sent only when the alert status of a server changes, and each notification carries every current alert item of that server (the `alerts` array). When all alerts clear, pgDash sends one notification with an empty `alerts` array. |
| 66 | + |
| 67 | +Flashduty therefore computes the Alert Key from the server name `server`, so every notification for the same server lands on the same alert: |
| 68 | + |
| 69 | +- A notification with alert items triggers or updates the alert. The title and description are replaced with the latest alert items |
| 70 | +- A notification with an empty `alerts` array recovers the alert |
| 71 | + |
| 72 | +When a single alert item clears while the server still has other alerts, pgDash sends no separate recovery for that item. The Flashduty alert stays triggered and its description lists only the items still firing. Flashduty rejects requests that lack the `server` or `alerts` field. |
| 73 | + |
| 74 | +<Tip> |
| 75 | +Renaming a server in pgDash produces a new Alert Key. Close alerts under the old name manually. |
| 76 | +</Tip> |
| 77 | + |
| 78 | +## Severity |
| 79 | +--- |
| 80 | + |
| 81 | +| pgDash alert items | Flashduty severity | |
| 82 | +| :--- | :--- | |
| 83 | +| Any item has `type` `crit` | Critical | |
| 84 | +| Otherwise (`warn`) | Warning | |
| 85 | +| `alerts` is empty | Recovered | |
| 86 | + |
| 87 | +## Alert content |
| 88 | +--- |
| 89 | + |
| 90 | +- **Title**: `server name: rule description`, taken from the first `crit` item (or the first item if none is critical). `(+N more)` is appended when there are several items |
| 91 | +- **Description**: the pgmetrics report time (UTC) and, for each alert item, its type, rule description, current value, object name, and link. Query-level alerts include the SQL text (truncated to 500 characters). Up to 50 items are listed |
| 92 | +- **Labels**: `server`, `check` (rule description of the item used in the title), `resource` (that item's object name), `link` (that item's pgDash link), `alert_count` (number of current alert items), `source` (always `pgdash`) |
| 93 | + |
| 94 | +## Troubleshooting |
| 95 | +--- |
| 96 | + |
| 97 | +- **pgDash sends nothing**: pgDash notifies only when the alert status changes and does not repeat an unchanged state. Check that an alert rule has fired and that the webhook is set on the **Alerts** page, not the **Change Alerts** page |
| 98 | +- **Delivery times out**: pgDash expects a response within 3 seconds and retries at most 3 times on timeout. For self-hosted pgDash, make sure the pgDash server can reach the push URL |
| 99 | +- **The alert does not recover**: it recovers only when all alerts of the server clear. While any other item is still firing, the alert stays open |
| 100 | + |
| 101 | +For field details, see [pgDash Webhooks](https://docs.pgdash.io/webhooks/). |
0 commit comments