diff --git a/docs/cloud/integrations/alerts/rootly.mdx b/docs/cloud/integrations/alerts/rootly.mdx new file mode 100644 index 000000000..f5b629460 --- /dev/null +++ b/docs/cloud/integrations/alerts/rootly.mdx @@ -0,0 +1,252 @@ +--- +title: "Rootly" +--- + +Elementary's Rootly integration enables sending alerts to [Rootly](https://rootly.com) when data issues are detected. + +Alerts are sent to a Rootly [Generic Webhook Alert Source](https://docs.rootly.com/integrations/generic-webhook-alert-source/generic-webhook-alert-source). Rootly then creates or updates alerts, and can trigger incidents, paging, and other alert workflows based on your configuration. + +To send alerts to Rootly, you need to create [alert rules](/cloud/features/alerts-and-incidents/alert-rules) and select Rootly as the destination. + +## Prerequisites + +You need a Rootly account with access to create Alert Sources. + +## Create a Generic Webhook Alert Source in Rootly + +Before connecting Elementary, you need to create a Generic Webhook Alert Source in Rootly: + +1. In Rootly, go to **Alert Sources** and click **New alert source**. Search for **Generic Webhook** and select it. + + +
+ {/* TODO: screenshot — locating Generic Webhook Alert Source in Rootly */} + Locate Generic Webhook Alert Source in Rootly +
+ + +2. Give the alert source a name (e.g. "Elementary Cloud"). + + +
+ {/* TODO: screenshot — naming the alert source */} + Name the Rootly generic webhook alert source +
+ + +3. On the source setup page, you will see the **webhook URL** and a **Bearer Token**. You will need both when connecting in Elementary. Keep this page open — you will come back to it after sending a test alert. + + +
+ {/* TODO: screenshot — webhook URL and Bearer Token on the source setup page */} + Rootly generic webhook alert source connection details +
+ + + +The Bearer Token is a secret. Keep it secure and do not share it publicly. + + + +If you want every alert from this source to always route to the same service, team, or escalation policy, use the fixed-target webhook URL variant Rootly offers (`.../notify//`) instead of the base URL. See [Routing alerts to a target](#routing-alerts-to-a-target) below. + + +## Connect Rootly in Elementary + +1. Go to the **Environments** page on the sidebar. + +2. Select an environment and click connect on the **Connect incident management tool** card, and select **Rootly**. + + +
+ {/* TODO: screenshot — selecting Rootly as incident management tool */} + Select Rootly as incident management tool +
+ + +3. Fill in the connection details from your Rootly alert source: + - **Source name** — a display name for this alert source (e.g. "Elementary Cloud") + - **Webhook endpoint URL** — the webhook URL from the Rootly alert source + - **Webhook secret** — the Bearer Token from the Rootly alert source + + +
+ {/* TODO: screenshot — Connect Rootly form with source name/webhook endpoint/secret */} + Enter Rootly connection details +
+ + +4. Expand **Test connection** to send a test incident and verify the integration is working. + + +
+ {/* TODO: screenshot — Test incident section */} + Test the Rootly connection +
+ + + +The test connection sends a real alert event to Rootly. You may need to manually resolve or close it after testing. + + +5. Click **Save**. **Rootly** will now be available as a destination on the [alert rules](/cloud/features/alerts-and-incidents/alert-rules) page. + + +You can add multiple alert sources by clicking **+ Add source** — for example, to route different alert rules to different Rootly alert sources. + + +## Configure Alert Fields in Rootly + +After sending a test alert from Elementary, go back to the Rootly alert source setup page. You should see the test alert appear in the recent activity / payload preview. Use it as a reference while mapping fields. + + +
+ {/* TODO: screenshot — alert source showing received test alert payload */} + Rootly alert source showing received test alert +
+ + +Rootly doesn't require a specific payload shape — you map the JSON fields Elementary sends to Rootly's alert fields yourself, using Liquid expressions (or by clicking the field directly in the payload preview). + + +
+ {/* TODO: screenshot — Alert Fields mapping UI */} + Map alert fields in Rootly +
+ + +At minimum, map these fields: + +| Rootly field | Map to | Purpose | +|---|---|---| +| **Title** | `title` | Headline shown on the alert | +| **External Identifier** | `external_id` | Stable key Rootly uses to match follow-up events to the same alert | +| **State** | `state` | Lifecycle state (`triggered` / `resolved`) — drives auto-resolution | +| **External URL** | `external_url` | Link back to the relevant page in Elementary Cloud | +| **Description** | `description` | Present only on grouped-alert notifications | + +### Configure auto-resolution + +Elementary sends a `resolved` state event with the same `external_id` when a previously failing test or model passes again. To have Rootly automatically resolve the alert: + +1. In the alert source settings, open **Auto-Resolution**. +2. Map the **external identifier** field to `external_id`. +3. Map the **state** field to `state`. +4. Set the resolved-state value to `resolved`. +5. Turn on auto-resolution for the source. + + +
+ {/* TODO: screenshot — Auto-Resolution configuration */} + Configure auto-resolution in Rootly +
+ + +### Available fields + +Elementary sends the following fields depending on the alert type. All fields are optional — they are included only when the data is available. + +| Field | Type | Description | +|-------|------|-------------| +| `severity` | String | Alert severity (e.g. `warn`, `fail`, `error`) | +| `owners` | Array of strings | Asset and test owners (email addresses) | +| `tags` | Array of strings | Asset and test tags | +| `environment` | String | Elementary environment name | +| `test_description` | String | Test description (test alerts only) | +| `source` | String | Pipeline tool name (pipeline alerts only) | +| `connector` | String | Connector name (pipeline alerts only) | +| `failure_reason` | String | Failure reason (pipeline alerts only) | + +Pipeline alerts also include additional fields such as `connector_type`, `connector_id`, `sync_id`, `destination`, `task_type`, and `rescheduled_at`. + + +When configuring fields, use the test alert payload as a reference — it includes sample values for the common fields, making it easy to set up mappings. + + +### Recommended field mappings + +We recommend mapping these fields in Rootly, in addition to the required ones above: + +- **`severity`** — enables routing alerts by severity +- **`owners`** — enables filtering and routing by data owner +- **`tags`** — enables filtering by tag + + +For array fields like `owners` and `tags`, map them to a field type in Rootly that supports multiple values. + + +If you need additional fields for your routing that are not currently included, [reach out to us](https://www.elementary-data.com/contact-us) and we'll work with you to add them. + +## Routing alerts to a target + +Rootly supports two ways to route an alert to a service, team, or escalation policy: + +- **URL-based** — use the fixed-target webhook URL variant (`.../notify//`) as the webhook endpoint URL when connecting in Elementary. Every alert from that source routes to the same target. This is the simplest option and works well since Elementary alerts don't include a routing target in the payload. +- **Payload-based** — map a routing target from the payload itself. Since Elementary doesn't send a routing target field, this option isn't applicable for this integration — use the URL-based approach instead, or add multiple Rootly sources (one per target) in Elementary and route different [alert rules](/cloud/features/alerts-and-incidents/alert-rules) to each. + +## How alerts work + +### Alert creation and deduplication + +Each Elementary alert includes a stable **external identifier** based on the alert's identity (test, model, or pipeline). Rootly uses this identifier to: + +- **Create** a new alert when a new issue is detected +- **Deduplicate** — avoid creating duplicate alerts for the same ongoing issue +- **Auto-resolve** — when a test passes again, Elementary sends a resolved event with the same external identifier, which resolves the alert in Rootly (once auto-resolution is configured, see above) + +### Alert types + +Elementary sends the following alert types to Rootly: + +- **Test alerts** — dbt and Elementary test failures +- **Model alerts** — dbt model and snapshot failures +- **Source freshness alerts** — source freshness check failures +- **Pipeline alerts** — pipeline connector failures (Fivetran, etc.) +- **Resolved alerts** — automatically sent when a previously failing test/model passes + +### Link to Elementary + +Each alert includes an **external URL** linking back to the relevant page in Elementary Cloud, so you can quickly investigate the issue. + +### Alerts in Rootly + +Each alert sent by Elementary appears in Rootly with its mapped fields and a link back to Elementary Cloud. + + +
+ {/* TODO: screenshot — alert detail view in Rootly */} + Elementary alert detail in Rootly +
+ + +When an alert matches your Rootly [alert workflows](https://docs.rootly.com/workflows/alert-workflows), it can automatically create an incident, page an on-call responder, or post to Slack or Microsoft Teams with full context. diff --git a/docs/docs.json b/docs/docs.json index 509b7852a..479ff6ad5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -282,6 +282,7 @@ "cloud/integrations/alerts/pagerduty", "cloud/integrations/alerts/opsgenie", "cloud/integrations/alerts/incident-io", + "cloud/integrations/alerts/rootly", "cloud/integrations/alerts/jira", "cloud/integrations/alerts/linear", "cloud/integrations/alerts/servicenow", diff --git a/docs/pics/cloud/rootly_alert_detail.png b/docs/pics/cloud/rootly_alert_detail.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_alert_detail.png differ diff --git a/docs/pics/cloud/rootly_auto_resolution.png b/docs/pics/cloud/rootly_auto_resolution.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_auto_resolution.png differ diff --git a/docs/pics/cloud/rootly_connect_form.png b/docs/pics/cloud/rootly_connect_form.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_connect_form.png differ diff --git a/docs/pics/cloud/rootly_field_mapping.png b/docs/pics/cloud/rootly_field_mapping.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_field_mapping.png differ diff --git a/docs/pics/cloud/rootly_name_source.png b/docs/pics/cloud/rootly_name_source.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_name_source.png differ diff --git a/docs/pics/cloud/rootly_new_alert_source.png b/docs/pics/cloud/rootly_new_alert_source.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_new_alert_source.png differ diff --git a/docs/pics/cloud/rootly_select_provider.png b/docs/pics/cloud/rootly_select_provider.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_select_provider.png differ diff --git a/docs/pics/cloud/rootly_source_test_alert.png b/docs/pics/cloud/rootly_source_test_alert.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_source_test_alert.png differ diff --git a/docs/pics/cloud/rootly_test_connection.png b/docs/pics/cloud/rootly_test_connection.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_test_connection.png differ diff --git a/docs/pics/cloud/rootly_webhook_details.png b/docs/pics/cloud/rootly_webhook_details.png new file mode 100644 index 000000000..88b257db5 Binary files /dev/null and b/docs/pics/cloud/rootly_webhook_details.png differ diff --git a/docs/snippets/cloud/integrations/cards-groups/alerts-destination-cards.mdx b/docs/snippets/cloud/integrations/cards-groups/alerts-destination-cards.mdx index 55b195b34..5e15804f8 100644 --- a/docs/snippets/cloud/integrations/cards-groups/alerts-destination-cards.mdx +++ b/docs/snippets/cloud/integrations/cards-groups/alerts-destination-cards.mdx @@ -69,6 +69,27 @@ } > + + + + + + + + + + + + + + + } + > +