diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index a76fc6d4a..53f4b9b57 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -30374,13 +30374,14 @@ }, "change_status": { "type": "string", - "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "link": { @@ -30468,13 +30469,14 @@ }, "change_status": { "type": "string", - "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "start_time": { diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 3d49ef29d..6ffe7dad0 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -30374,13 +30374,14 @@ }, "change_status": { "type": "string", - "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "link": { @@ -30468,13 +30469,14 @@ }, "change_status": { "type": "string", - "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "start_time": { diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 36e2edaf6..5c2bdd216 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -1320,6 +1320,10 @@ "description": "Alert description.", "type": "string" }, + "detail_url": { + "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.", + "type": "string" + }, "end_time": { "description": "Unix timestamp (seconds) when the alert recovered. 0 if still active.", "format": "int64", @@ -1541,6 +1545,10 @@ "description": "Alert description.", "type": "string" }, + "detail_url": { + "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.", + "type": "string" + }, "end_time": { "description": "Resolution time, Unix epoch seconds. 0 if still active.", "format": "int64", @@ -4494,13 +4502,14 @@ "type": "string" }, "change_status": { - "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, @@ -4576,13 +4585,14 @@ "type": "string" }, "change_status": { - "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, diff --git a/api-reference/openapi.legacy.zh.json b/api-reference/openapi.legacy.zh.json index 8a655bf64..174469636 100644 --- a/api-reference/openapi.legacy.zh.json +++ b/api-reference/openapi.legacy.zh.json @@ -28938,7 +28938,8 @@ "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "start_time": { @@ -29007,7 +29008,8 @@ "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "description": "变更状态" }, diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 25cbdfae4..afedef7f7 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -1320,6 +1320,10 @@ "description": "告警描述。", "type": "string" }, + "detail_url": { + "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。", + "type": "string" + }, "end_time": { "description": "告警恢复的 Unix 时间戳（秒），仍活跃时为 0。", "format": "int64", @@ -1541,6 +1545,10 @@ "description": "告警描述。", "type": "string" }, + "detail_url": { + "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。", + "type": "string" + }, "end_time": { "description": "恢复时间，Unix 时间戳（秒）。活跃时为 0。", "format": "int64", @@ -4494,13 +4502,14 @@ "type": "string" }, "change_status": { - "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, @@ -4576,13 +4585,14 @@ "type": "string" }, "change_status": { - "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, diff --git a/docs.json b/docs.json index 37c7bc9ee..d31ff1d21 100644 --- a/docs.json +++ b/docs.json @@ -1848,7 +1848,17 @@ { "group": "变更集成", "pages": [ - "zh/on-call/integration/change-integration/custom-event" + "zh/on-call/integration/change-integration/custom-event", + "zh/on-call/integration/change-integration/github", + "zh/on-call/integration/change-integration/gitlab", + "zh/on-call/integration/change-integration/hcp-terraform", + "zh/on-call/integration/change-integration/argocd", + "zh/on-call/integration/change-integration/netlify", + "zh/on-call/integration/change-integration/vercel", + "zh/on-call/integration/change-integration/jfrog-artifactory", + "zh/on-call/integration/change-integration/buildkite", + "zh/on-call/integration/change-integration/launchdarkly", + "zh/on-call/integration/change-integration/jenkins" ] }, { @@ -3320,7 +3330,17 @@ { "group": "Change Integration", "pages": [ - "en/on-call/integration/change-integration/custom-event" + "en/on-call/integration/change-integration/custom-event", + "en/on-call/integration/change-integration/github", + "en/on-call/integration/change-integration/gitlab", + "en/on-call/integration/change-integration/hcp-terraform", + "en/on-call/integration/change-integration/argocd", + "en/on-call/integration/change-integration/netlify", + "en/on-call/integration/change-integration/vercel", + "en/on-call/integration/change-integration/jfrog-artifactory", + "en/on-call/integration/change-integration/buildkite", + "en/on-call/integration/change-integration/launchdarkly", + "en/on-call/integration/change-integration/jenkins" ] }, { diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index bc1353663..c59d6c161 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -842,8 +842,8 @@ The following commands support `--fields` with `json` or `toon` output. Supply c | Command | Structured output when `--fields` is omitted | Limit | | --- | --- | --- | -| `flashduty incident list` | `incident_id`, `title`, `incident_severity`, `progress`, `start_time`, `channel_id` | 16 KiB | -| `flashduty incident similar ` | `incident_id`, `title`, `incident_severity`, `progress`, `start_time`, `close_time`, `ack_time`, `alert_cnt`, `root_cause`, `score` | 16 KiB | +| `flashduty incident list` | `incident_id`, `num`, `title`, `incident_severity`, `progress`, `start_time`, `channel_id`, `detail_url` | 16 KiB | +| `flashduty incident similar ` | `incident_id`, `num`, `title`, `incident_severity`, `progress`, `start_time`, `close_time`, `ack_time`, `alert_cnt`, `root_cause`, `score`, `detail_url` | 16 KiB | | `flashduty incident detail ` | Returns full detail when `--fields` is omitted; otherwise returns only the selected fields | 8 KiB for projections only | | `flashduty alert-event list` | `event_id`, `alert_id`, `event_severity`, `event_status`, `event_time`, `title` | 16 KiB | | `flashduty channel escalate-rule-list ` | `rule_id`, `rule_name`, `status`, `priority`, `filters` | 16 KiB | diff --git a/en/on-call/incident/search-view-incident.mdx b/en/on-call/incident/search-view-incident.mdx index 177078103..8d4be9e38 100644 --- a/en/on-call/incident/search-view-incident.mdx +++ b/en/on-call/incident/search-view-incident.mdx @@ -277,7 +277,7 @@ The change event list displays the following information: | Column | Description | | :--- | :--- | -| **Status** | Current status of the change event, including Planned, Ready, Processing, Canceled, Done | +| **Status** | Current status of the change event, including Planned, Ready, Processing, Canceled, Done, Failed | | **Change Key** | Unique identifier of the change event | | **Title** | Brief description of the change event | | **Description** | Detailed information about the change event | diff --git a/en/on-call/integration/alert-integration/alert-sources/argocd.mdx b/en/on-call/integration/alert-integration/alert-sources/argocd.mdx index 9ba29d4e5..8412f2268 100644 --- a/en/on-call/integration/alert-integration/alert-sources/argocd.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/argocd.mdx @@ -148,7 +148,7 @@ kubectl exec -n argocd deploy/argocd-notifications-controller -- \ /usr/local/bin/argocd admin notifications template notify flashduty-health --recipient flashduty ``` -No error output means Flashduty accepted the request. When the application is `Healthy`, this is a recovery message and creates no alert; in an intermediate state such as `Progressing`, Flashduty ignores it. +The command prints debug logs of the request and response, including the full push URL with its `integration_key`, so do not paste the output anywhere public. A `200 OK` status on the `Received response:` line means Flashduty accepted the request. When the application is `Healthy`, this is a recovery message and creates no alert; in an intermediate state such as `Progressing`, Flashduty ignores it. diff --git a/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx b/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx index 2e1eccd64..145f090e7 100644 --- a/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx @@ -60,16 +60,16 @@ The script does not parse the parameter file. It sends every `KEY='VALUE'` line 1. Log in to Mission Portal, click **Settings** in the top right, and open **Custom notification scripts** -2. Click **Add script**, upload `flashduty_custom_action.sh`, and enter a name (for example `Flashduty`) and a description +2. Click **Add a script**, upload `flashduty_custom_action.sh`, and enter a name (for example `Flashduty`) and a description 3. Click **Save** -On the **Dashboard**, create an alert or edit an existing one, select the `Flashduty` script uploaded in the previous step in the notification settings, and save. One script can be associated with many alerts; associate it with every alert that should reach Flashduty. +On the **Dashboard**, create an alert or edit an existing one, tick **Custom action** in the notification settings, tick the `Flashduty` script uploaded in the previous step, and save. One script can be associated with many alerts; associate it with every alert that should reach Flashduty. -To keep notifying while an alert stays triggered, choose a reminder interval in the alert's **Remind me** setting. Reminders also run the script, and Flashduty merges them into the existing alert. +To keep notifying while an alert stays triggered, choose a reminder interval after ticking **Set reminders** in the alert. Reminders also run the script, and Flashduty merges them into the existing alert. diff --git a/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx b/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx index d07fc15c7..0b3cf6ab5 100644 --- a/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx @@ -38,9 +38,10 @@ Ghost Inspector's notification settings have three levels — organization, suit 1. Open the test, its suite, or the organization settings page, whichever level you want to configure -2. Click **Settings → Notifications** -3. Under **Webhooks**, add a new one and paste the full Flashduty push URL (it must include `integration_key`) -4. Save +2. Click **Settings**, then select **Notifications** in the left sidebar +3. Under **Webhooks**, set **Enabled** to **Yes** (the default, **Use suite setting**, sends nothing unless the suite or organization has webhooks on), then click **Add webhook** +4. Paste the full Flashduty push URL (it must include `integration_key`) and keep the delivery option at **Always send**. Flashduty needs both failing and passing results; the other options, **Passing result only** and **Failing result only**, would stop the alert from opening or recovering +5. Click **Save changes** diff --git a/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx b/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx index 586e7afe0..fd6704ae6 100644 --- a/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx @@ -37,9 +37,9 @@ You need permission to manage integrations in the GitGuardian workspace. -1. In the GitGuardian dashboard, go to **Settings → Workspace → Integrations → Destinations → Custom webhook** -2. Personal workspace: create a webhook, enter a name, and paste the complete Flashduty integration Push URL as the target URL. The URL must include `integration_key` -3. Business workspace: create the webhook at team level. To receive every incident in the workspace, create it under the **All-incidents team**; to receive only one team's incidents, create it under that team +1. In the GitGuardian dashboard, go to **Settings → Integrations → Destinations → Custom webhook** +2. A webhook belongs to a team. To receive every incident in the workspace, click **Add integration** on the **All-incidents team** row; to receive only one team's incidents, use that team's row +3. On the **Configuration** tab, paste the complete Flashduty integration Push URL into **Webhook URL** (it must include `integration_key`) and click **Next** GitGuardian generates a signature token for the webhook. Flashduty authenticates by the `integration_key` in the Push URL and does not verify the signature, so you do not need to enter the token in Flashduty. @@ -47,22 +47,22 @@ GitGuardian generates a signature token for the webhook. Flashduty authenticates -Select these events: +On the **Events** tab, enter an **Events name**, turn on **Internal monitoring**, and under **Notify when** select these events (or click **Select all**): -| GitGuardian event | `action` | Effect in Flashduty | +| Option in GitGuardian | `action` | Effect in Flashduty | | :--- | :--- | :--- | | New incident detected | `incident_triggered` | Triggers an alert | -| New occurrence detected | `new_occurrence` | Triggers or updates the alert | -| Incident Validity changed | `incident_validity_changed` | Triggers or updates the alert | -| Incident Severity changed | `incident_severity_changed` | Triggers or updates the alert; the severity follows | +| Incident has new occurrence | `new_occurrence` | Triggers or updates the alert | +| Secret validity change | `incident_validity_changed` | Triggers or updates the alert | +| Incident status change → Severity change | `incident_severity_changed` | Triggers or updates the alert; the severity follows | | Risk score updated (Business plan) | `incident_risk_score_updated` | Triggers or updates the alert | | Incident regression | `incident_regression` | Triggers or updates the alert | -| Incident reopened | `incident_reopened` | Triggers or updates the alert | -| Incident resolved | `incident_resolved` | Recovers the alert | -| Incident ignored | `incident_ignored` | Recovers the alert | +| Incident status change → Reopened | `incident_reopened` | Triggers or updates the alert | +| Incident status change → Resolved | `incident_resolved` | Recovers the alert | +| Incident status change → Ignored | `incident_ignored` | Recovers the alert | -You must select **Incident resolved** and **Incident ignored**, or the Flashduty alert does not recover when the incident is handled. +You must select **Resolved** and **Ignored** under **Incident status change**, or the Flashduty alert does not recover when the incident is handled. Assignment, comment, feedback, access, public sharing, and Honeytoken events do not change alert state. Flashduty returns success for them and creates no alert, so you do not need to select them. @@ -75,7 +75,7 @@ To page only for high-risk leaks, add filtering rules to the webhook by severity Trigger a new incident in the workspace and confirm that Flashduty receives an active alert. Then mark the incident **Resolved** in GitGuardian and confirm that the alert recovers. -The test message sent from GitGuardian only verifies that the URL is reachable: Flashduty returns success but creates no alert. +**Send test message** in the webhook's menu (the three dots on its row) only verifies that the URL is reachable: Flashduty returns success but creates no alert. @@ -90,15 +90,15 @@ Changes to severity, validity, occurrence count, or detector name do not change ## Status and severity --- -The alert status follows `action`: `incident_resolved` and `incident_ignored` recover the alert, and every other event in the table above triggers it. A reopened incident triggers a new alert with the same Alert Key. +The alert status follows `action`: `incident_resolved` and `incident_ignored` recover the alert, and every other event in the table above triggers it. A validity, severity, or risk score change on an incident that is already resolved or ignored is ignored and does not re-open the alert. A reopened incident triggers a new alert with the same Alert Key. The severity follows `incident.severity`: | GitGuardian severity | Flashduty severity | | :--- | :--- | -| `high` | Critical | +| `critical`, `high` | Critical | | `medium` | Warning | -| `low` | Info | +| `low`, `info` | Info | | `unknown`, empty, or any other value | Warning | `unknown` means GitGuardian has not rated the incident yet, so Flashduty treats it as Warning. @@ -124,7 +124,7 @@ The severity follows `incident.severity`: --- - **No alert was created**: confirm the matching event is selected and that the webhook's filtering rules do not exclude the incident. GitGuardian states that webhook delivery is best effort and not guaranteed -- **The alert did not recover**: confirm **Incident resolved** and **Incident ignored** are selected +- **The alert did not recover**: confirm **Resolved** and **Ignored** are selected under **Incident status change** - **Flashduty returns an invalid-parameter error**: confirm the target URL is complete and includes `integration_key` - **An ignored incident is reopened**: a new alert is created with the same Alert Key diff --git a/en/on-call/integration/alert-integration/alert-sources/instatus.mdx b/en/on-call/integration/alert-integration/alert-sources/instatus.mdx index 04679217e..85a5ac4f7 100644 --- a/en/on-call/integration/alert-integration/alert-sources/instatus.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/instatus.mdx @@ -54,7 +54,9 @@ One integration can follow several status pages. Alerts from different pages are -Instatus has no button that sends a test notification. To verify: +Saving the subscriber sends a validation delivery right away (the **RUN** button next to the Webhook URL field sends another). Flashduty recognizes it and answers with success, no alert. + +To verify with a real incident instead: 1. In Instatus, go to **Incidents** and click **Add incident**. Set the status to **Investigating**, select an affected component, set it to **Major outage**, then save and notify subscribers. Flashduty shows an incident alert and a component alert, both Critical 2. Add an update to that incident with the status **Resolved**, set the component back to **Operational**, and notify subscribers. Both alerts recover @@ -79,7 +81,8 @@ Instatus sends one JSON payload each time an incident is added or updated, a com | `incident.id` | Incident ID | Alert Key, label `incident_id` | | `incident.name` | Incident name | Alert title | | `incident.status` | Incident status | Alert status, label `incident_status` | -| `incident.impact` | Incident impact | Alert severity, label `impact` | +| `incident.impact` | Incident impact | Label `impact`, informational only: on an incident created through the Instatus dashboard this carries the same word as `status` (e.g. `Investigating`), not an outage severity | +| `incident.affected_components[].status` | Status of each affected component | Alert severity — the worst one across all affected components; used as a fallback only when there are none | | `incident.url` | Incident link | Label `incident_url` | | `incident.incident_updates` | Incident updates | The body of the latest update is the alert description, truncated above 8 KB | @@ -122,15 +125,17 @@ Renaming an incident or component, or changing the impact, does not change the A **Instatus incidents** -The alert severity comes from the impact (`impact`, which takes the same values as component status), and the alert status from the incident status (`status`): +The alert severity is the worst status across the incident's `affected_components` (same values as component status, only differently cased and spaced, e.g. `Major outage`), and the alert status comes from the incident status (`status`): -| Instatus `impact` | Flashduty severity | +| Instatus `affected_components[].status` | Flashduty severity | | :--- | :--- | -| `MAJOROUTAGE` | Critical | -| `PARTIALOUTAGE` | Warning | -| `DEGRADEDPERFORMANCE`, `OPERATIONAL` | Info | +| `Major outage` | Critical | +| `Partial outage` | Warning | +| `Degraded performance`, `Operational` | Info | | Empty or any other value | Warning | +An incident with no affected component falls back to the same mapping applied to `impact` instead — but on a dashboard-created incident, `impact` is usually just the `status` wording (e.g. `Investigating`), which matches none of these values and lands on Warning. + | Instatus `status` | Flashduty status | | :--- | :--- | | `INVESTIGATING`, `IDENTIFIED`, `MONITORING` | Trigger or update the alert | diff --git a/en/on-call/integration/alert-integration/alert-sources/kentik.mdx b/en/on-call/integration/alert-integration/alert-sources/kentik.mdx index d307760f9..c6651faa7 100644 --- a/en/on-call/integration/alert-integration/alert-sources/kentik.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/kentik.mdx @@ -37,8 +37,8 @@ Creating a notification channel requires the Administrator role in Kentik; Membe -1. Log in to the Kentik Portal and go to **Settings** → **Notifications** -2. Click **Add Notification Channel** and set **Type** to **Custom Webhook**. Do not choose the **JSON** type: Flashduty parses the output of the template below +1. Log in to the Kentik Portal and go to **Settings** → **Notification Channels** +2. Click **Add Notification Channel** and set **Type** to **Webhook** (listed as Custom Webhook). Do not choose the **JSON** type: Flashduty parses the output of the template below 3. Fill in the fields as follows: | Field | Value | @@ -47,7 +47,7 @@ Creating a notification channel requires the Administrator role in Kentik; Membe | **Status** | On | | **URL** | The full Flashduty integration push URL, including `integration_key` | | **Custom Headers** | Leave empty | -| **Custom Template** | Paste the template below without renaming any field | +| **Custom Template** | Click **Go to Notification Template Setup** and paste the template below into **TEMPLATE** on the **Template & Preview** tab, without renaming any field | | **Uglify JSON** | Keep the default | ```go-template @@ -75,7 +75,7 @@ Creating a notification channel requires the Administrator role in Kentik; Membe } ``` -4. Click **Add Notification Channel** to save +4. Click **Save** @@ -102,6 +102,7 @@ Do not use this channel for mitigation methods or Insights notifications: these Flashduty uses the Kentik alert ID (`AlarmID`, shown as **Alert ID** in Kentik) as the Alert Key. Every state-change notification of one Kentik alert, from Active to Cleared, carries the same alert ID, so they merge into one alert, and the clear notification closes it. - **Alerts per key**: an alert policy raises a separate alert for each key (one set of values of the policy dimensions) that matches the conditions. Each alert has its own ID, so each is a separate Flashduty alert that recovers on its own +- **Synthetics alerts per agent**: a Synthetics test raises a separate alert, with its own ID, for each test agent. A new failure after an alert clears gets a new alert ID and becomes a new Flashduty alert - Changes to the description, severity, metric values, or times do not change the Alert Key. Events without `AlarmID` are rejected - When one notification carries several events, each event maps to its own alert. A notification with no events is accepted but creates no alert @@ -150,6 +151,6 @@ The alert title is the Kentik event description (`Description`), such as `Alarm - **`AlarmID is required`**: the channel is used for mitigation or Insights notifications, or the template was changed. Use the channel only for alert policies and Synthetics tests - **The alert does not recover**: confirm that the alert is Cleared in Kentik. For policies with **Acknowledgement Required** on, the alert must be acknowledged in Kentik before it can clear (see [Kentik threshold policy settings](https://kb.kentik.com/v1/docs/threshold-policy-settings)) - **One policy creates several alerts**: the policy alerts on each set of dimension values separately; this is expected -- **Test notifications**: the content of the Kentik **Test** / **Test Notification Channels** buttons is defined by Kentik. If it carries an alert ID, Flashduty handles it as a regular alert; close that alert manually in Flashduty +- **Test notifications**: **Send Test Notification** on the **Template & Preview** tab sends mock data whose event description starts with `[TEST]`; Flashduty accepts it and creates no alert. If you first load a real alert with **Enter Alert ID**, the test carries that alert's real state, and Flashduty handles it as a real notification For field details, see [Kentik notification channels](https://kb.kentik.com/docs/notification-channel) and the [Kentik Custom Webhook templating reference](https://github.com/kentik/custom-notification-templates/blob/main/docs/TEMPLATING_REFERENCE.md). diff --git a/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx b/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx index 7ab897581..edef70dd5 100644 --- a/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx @@ -37,18 +37,18 @@ You can get the integration push URL in either of two ways. -1. Sign in to LangSmith, open the tracing project to monitor, go to the **Alerts** page, and create an alert rule: pick the metric (error count, feedback score, latency or cost), the threshold and the aggregation window (5 or 15 minutes) +1. Sign in to LangSmith, open the tracing project to monitor, go to **Monitoring** → **Alerts** (or the project's monitoring dashboard), click **Alert**, and create an alert rule: pick the metric (**Run Count**, **Cost**, **Errors**, **Feedback Score** or **Latency**), the threshold and the time window (1 to 60 minutes) 2. Under **Notification Settings**, choose **Webhook** and fill in: - **URL**: the full push URL of the Flashduty integration - **Headers**: leave empty - - **Request Body Template**: leave empty. LangSmith merges the fields listed under "Payload" below into the request body as top-level keys; it does no template substitution + - **Body**: leave empty. LangSmith merges the fields listed under "Payload" below into the request body as top-level keys; it does no template substitution 3. Save the alert rule -Click **Send Test Alert**. LangSmith does not validate the receiver's response, so the UI reports success even if Flashduty returns an error; check the Flashduty console for the alert instead. If the test payload has no `alert_rule_id`, Flashduty returns success and creates no alert. If it does carry one, an alert is created; close it manually. +Edit the Webhook action in the alert rule's notification settings and click **Send Test Notification**. LangSmith does not validate the receiver's response, so the UI reports success even if Flashduty returns an error; check the Flashduty console instead. The test payload carries the all-zero UUID `00000000-0000-0000-0000-000000000000` as `alert_rule_id`, and Flashduty returns success without creating an alert. @@ -86,7 +86,7 @@ The alert title is the rule name; if it is empty, `LangSmith alert - + -LangSmith does not validate the receiver's response. Flashduty drops a test payload that has no `alert_rule_id`, which is expected; real alerts are sent only when the metric actually crosses the threshold. +LangSmith does not validate the receiver's response. Flashduty drops a test payload (`alert_rule_id` missing or the all-zero UUID), which is expected; real alerts are sent only when the metric actually crosses the threshold. diff --git a/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx b/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx index 690b11d67..7728f7d33 100644 --- a/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx @@ -35,10 +35,10 @@ You can obtain an integration push URL in either of the following ways. -1. In LogRocket, open the dashboard you want to alert on and create or edit a **Timeseries** chart (alerts are supported only on this chart type) -2. In the chart's alert settings, add an alert and choose the **Webhook** type -3. Paste the full Flashduty push URL, including `integration_key`, as the target URL -4. Set the trigger rule: the comparison (greater than or less than), the threshold, and the time interval to evaluate, then save the chart +1. In LogRocket, open **Analytics → Timeseries**, build the chart you want to alert on, and click **Save** (alerts are supported only on saved Timeseries charts) +2. Click **Alerts → Create Alert** at the top right of the chart, and enter an **Alert name** +3. Under **Trigger alert when**, set the comparison (**greater than** or **less than**), the threshold, and the time window, for example "Session count is less than 1 sessions within 5 minutes" +4. Under **Send alert via**, select **Webhook**, paste the full Flashduty push URL, including `integration_key`, into the **Webhook** field, and click **Save Alert** An account can have up to 100 alerts, all managed on the **Alerts** page in Settings. @@ -83,7 +83,7 @@ The LogRocket webhook carries no severity, and a metric crossing a threshold is | `threshold` / `threshold_unit` | Threshold and its unit | | `interval` / `interval_unit` | Evaluation interval and its unit (`MINUTES` or `HOURS`) | -The alert title and description come from `reason`, the text LogRocket generates from the alert settings. Without `reason` the title is `LogRocket alert `. +The alert title and description come from `reason`, which LogRocket fills with the alert name you entered. Without `reason` the title is `LogRocket alert `. ## Troubleshooting --- diff --git a/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx b/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx index e404c830f..01fe3f7d9 100644 --- a/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx @@ -76,7 +76,7 @@ Statuspal pushes JSON. The `event` field is the event type, and `data.object` is | Field | Description | Use in Flashduty | | :--- | :--- | :--- | | `data.object.id` | Incident ID | Alert Key, label `incident_id` | -| `data.object.l_title` | Incident title in each language | Alert title (English first, otherwise the first title) | +| `data.object.l_title` | Incident title in each language | Alert title (English first, otherwise the first title; falls back to `data.object.title` when neither is present) | | `data.object.ends_at` | Incident end time | Recovers the alert when set, label `ends_at` | | `data.object.starts_at` | Incident start time | Label `starts_at` | | `data.object.service_ids` | IDs of the affected services | Label `service_ids` (comma-separated) | diff --git a/en/on-call/integration/alert-integration/alert-sources/stripe.mdx b/en/on-call/integration/alert-integration/alert-sources/stripe.mdx index f727fabc1..99141628a 100644 --- a/en/on-call/integration/alert-integration/alert-sources/stripe.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/stripe.mdx @@ -43,7 +43,7 @@ You can get the integration push URL in either of the following ways. You need a Stripe role that can manage webhooks, such as Administrator or Developer. -1. Sign in to the Stripe Dashboard, open the [Webhooks](https://dashboard.stripe.com/webhooks) tab in Workbench, and click **Create an event destination** +1. Sign in to the Stripe Dashboard, open the [Webhooks](https://dashboard.stripe.com/webhooks) tab in Workbench, and click **Add destination** 2. For **Events from**, select **Your account**. If you run a Connect platform and want events from connected accounts, select **Connected accounts** (create one destination for each scope if you need both) 3. Keep the default **API version**. If you are asked to choose an event payload style, choose **Snapshot**: thin events do not contain the object, so Flashduty cannot parse them @@ -71,7 +71,7 @@ If the destination subscribes to other event types (for example `charge.succeede 1. Click **Continue** and select **Webhook endpoint** as the destination type 2. For **Endpoint URL**, enter the full Flashduty push URL -3. Finish creating the destination. Flashduty does not use the signing secret (starting with `whsec_`) shown on the endpoint page, so you do not need to copy it +3. Optionally enter a **Destination name**, then click **Create destination**. Flashduty does not use the signing secret (starting with `whsec_`) shown on the endpoint page, so you do not need to copy it Webhook endpoints in test environments (sandbox or test mode) and in live mode are separate. To connect both, create an endpoint in each environment; they can use the same push URL. @@ -79,11 +79,12 @@ Webhook endpoints in test environments (sandbox or test mode) and in live mode a -Stripe has no "send test notification" button. Create real test events in a test environment in any of these ways: +The **Send test events** button on the destination page only shows Stripe CLI instructions and sends nothing. Create real test events in a test environment in any of these ways: - Run `stripe trigger charge.dispute.created` with the [Stripe CLI](https://docs.stripe.com/cli) - Pay with test card `4000000000000259`: the payment succeeds and is then disputed as fraudulent. Pay with `4000000000005423` to receive an early fraud warning -- Submit `winning_evidence` as the dispute evidence: the dispute closes as won and Flashduty recovers the alert +- Submit `winning_evidence` (or `losing_evidence`) as the dispute evidence: the dispute closes as won (or lost) and Flashduty recovers the alert. Fully refund the early-fraud-warning payment: Stripe sends `radar.early_fraud_warning.updated` with `actionable` set to `false` and Flashduty recovers the alert +- `payout.failed` needs a failed payout. A sandbox does not accept test bank accounts in its own payout settings; on a Connect platform, pay out from a test connected account whose bank account uses account number `000111111116`, with a destination that receives **Connected accounts** events Test events have `livemode` set to `false`. Flashduty creates alerts for them as usual and adds the label `livemode=false`. diff --git a/en/on-call/integration/alert-integration/alert-sources/tideways.mdx b/en/on-call/integration/alert-integration/alert-sources/tideways.mdx index e967315e3..c7b30e738 100644 --- a/en/on-call/integration/alert-integration/alert-sources/tideways.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/tideways.mdx @@ -4,7 +4,7 @@ description: "Send Tideways response time, error rate, missing data, exception, keywords: ["alert integration", "Tideways", "PHP", "APM", "webhook"] --- -Use the organization-level Webhook integration in Tideways to send performance and error notifications from your PHP applications to Flashduty On-call. Response time and error rate incidents have a full lifecycle: an alert triggers when the incident opens, updates while it continues, and recovers when it closes. Transaction failure rate and missing data notifications are sent once when they occur and never recover. An exception or slow SQL alert recovers when its error group is resolved or ignored in Tideways. +Use the organization-level Webhook integration in Tideways to send performance and error notifications from your PHP applications to Flashduty On-call. Response time and error rate incidents have a full lifecycle: an alert triggers when the incident opens, updates while it continues, and recovers when it closes. Transaction failure rate and missing data notifications are sent once when they occur and never recover. Exception and slow SQL notifications are sent when an error group is new, reopened, or reappears; Tideways sends nothing when the group is resolved, so those alerts do not recover automatically.
@@ -39,32 +39,33 @@ You need admin permission on the organization. The Tideways webhook only accepts 1. Open the organization's **Integrations** settings, click **Add New Integration**, and select **Webhook** 2. Enter a name and paste the full Flashduty push URL, including `integration_key`, as the URL -3. Save +3. Under the trigger options, tick **and when the alert is fixed**. It is off by default; without it Tideways sends no `closed` notification and incident alerts never recover in Flashduty +4. Save -Open the application's **Project Settings → Configure Notifications** and select the new webhook integration for each notification type that should page someone. The table shows how Flashduty handles each type. +Open the application's **Project Settings → Notifications**. For each notification rule that should page someone, click **Edit**, tick the new webhook integration, and save (use **Create Notification Rule** to add a rule type that is not listed yet). The table shows how Flashduty handles each type. -| Tideways notification | `type` | Effect in Flashduty | +| Tideways notification rule | `type` | Effect in Flashduty | | :--- | :--- | :--- | -| Response Time | `response_time` | Trigger, update, recover | -| Failure Rate | `error_rate` | Trigger, update, recover | -| Transaction response time | `transaction-response-time` | Trigger, update, recover | -| Transaction failure rate | `transaction-failure-rate` | Trigger (no recovery) | -| Missing Data | `missing-data` | Trigger (no recovery) | -| New exception | `exception` | Trigger (no recovery) | -| New slow SQL | `slow-sql` | Trigger (no recovery) | -| Weekly report, release, release comparison | `weekly_report`, `release`, `compare_release` | Acknowledged only, no alert | +| Service Response Time | `response_time` | Trigger, update, recover | +| Service Failure Rate | `error_rate` | Trigger, update, recover | +| Transaction Response Times | `transaction-response-time` | Trigger, update, recover | +| Transaction Failure Rates | `transaction-failure-rate` | Trigger (no recovery) | +| Heartbeat Monitoring | `missing-data` | Trigger (no recovery) | +| New Error/Exception | `exception` | Trigger (no recovery) | +| New Slow SQL Query | `slow-sql` | Trigger (no recovery) | +| Weekly Performance Report, New Release, release comparison | `weekly_report`, `release`, `compare_release` | Acknowledged only, no alert | -Push the application's response time above its threshold and confirm Flashduty receives an active alert. After the metric falls back and Tideways closes the incident, confirm the same alert recovers. +Push the application's response time above its threshold and confirm Flashduty receives an active alert. An incident opens once the value has exceeded the threshold over the rule's check period (5 to 60 minutes). After the metric falls back and Tideways closes the incident, confirm the same alert recovers. -The Tideways documentation does not say what the **Preview** button on the integration page sends. Its sample notification has the same shape as a real one, so Flashduty creates an alert for it as listed above. Close it manually after testing. +The **Preview** button on the integration page sends one `response_time` notification with status `opened` and a placeholder incident ID. Flashduty creates a Warning alert for it, and no `closed` notification follows, so close it manually after testing. @@ -79,7 +80,7 @@ Other types use their own object: - New exceptions and slow SQL: the error group ID (`notification.error_group.id`). A group that appears again merges into the same alert - Transaction failure rate and missing data: the organization, application, environment (`environment`), service (`service`), and transaction (`transaction`). The same check firing again merges into the same alert -Changes to the value, time, threshold, or occurrence count never change the Alert Key. A notification whose error group status is `resolved`, `not_error`, or `ignored` recovers the alert of that group. +Changes to the value, time, threshold, or occurrence count never change the Alert Key. An error group notification with status `resolved`, `not_error`, or `ignored` recovers the alert of that group. The exception rule only notifies for new, reappeared, reopened, and unacknowledged errors, so in practice a resolved group produces no notification; a reopened group merges into its existing alert. ## Status and severity --- @@ -98,7 +99,7 @@ When `status` is `closed`, or an error group is `resolved`, `not_error`, or `ign ## When alerts do not recover --- -Transaction failure rate and missing data notifications are sent once, and Tideways sends no matching recovery, so these alerts do not recover automatically. Exception and slow SQL alerts recover when the error group is resolved or ignored, if Tideways sends that notification. +Transaction failure rate and missing data notifications are sent once, and Tideways sends no matching recovery, so these alerts do not recover automatically. Exception and slow SQL alerts also stay active after the error group is resolved or ignored in Tideways, because Tideways sends no notification for that. Turn on [auto-close](/en/on-call/channel/create-edit) for the channel, with the timer starting from **Incident triggered** and a suggested duration of 24 hours. Missing data and new exceptions are normally handled within a working day. If the channel only receives response time and failure rate notifications, you can leave it off. @@ -120,7 +121,7 @@ Turn on [auto-close](/en/on-call/channel/create-edit) for the channel, with the - **Tideways shows a delivery failure**: confirm the URL uses HTTPS and includes `integration_key`. Tideways does not retry, and a response with status 400 or higher is only recorded in the integration's error log - **Flashduty returns an invalid-parameter error**: the message names the missing field (for example `notification.incident_id`) or the unsupported `type` -- **An alert did not recover**: response time, failure rate, and transaction response time incidents recover on `closed`, and exceptions and slow SQL recover when their error group is resolved or ignored in Tideways; turn on auto-close for transaction failure rate and missing data +- **An alert did not recover**: response time, failure rate, and transaction response time incidents recover on `closed`, and turn on auto-close for exceptions, slow SQL, transaction failure rate, and missing data. If incident alerts stay active after Tideways closes the incident, check that **and when the alert is fixed** is ticked on the webhook integration - **A weekly report or release notification created no alert**: these are not incidents, so Flashduty only acknowledges them For field details, see the [Tideways webhook documentation](https://support.tideways.com/documentation/reference/integrations/webhook.html). diff --git a/en/on-call/integration/alert-integration/alert-sources/wormly.mdx b/en/on-call/integration/alert-integration/alert-sources/wormly.mdx index 886cb5fee..d5a6a3a33 100644 --- a/en/on-call/integration/alert-integration/alert-sources/wormly.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/wormly.mdx @@ -35,7 +35,7 @@ You can get the integration push URL in either of the following ways. -1. Sign in to Wormly, go to **Contacts**, and click **Create a new contact** +1. Sign in to Wormly, go to **Contacts**, and click **Create New Contact** 2. Choose the **Webhook** channel 3. Paste the full Flashduty push URL into the URL field 4. Choose a JSON webhook type (`JSON` or `JSON - multipart/form encoding`; Flashduty parses both). Do not choose XML or Serialized PHP @@ -108,7 +108,7 @@ No. While a host stays down, each notification sent at an escalation level carri -Wormly's documentation does not describe the test notification. Flashduty acknowledges an empty JSON object, which has none of the known fields, and creates no alert. If the test notification carries a sample `hostid`, it creates an alert keyed on that `hostid`, which you can close manually in Flashduty. +The contact form's **Send Test** button always posts a trigger notification with a sample `hostid` (`5112`), so it opens an alert keyed on `5112`. No recovery notification follows a test, so close that alert manually in Flashduty. An empty JSON object with none of the known fields is acknowledged without creating an alert. diff --git a/en/on-call/integration/change-integration/argocd.mdx b/en/on-call/integration/change-integration/argocd.mdx new file mode 100644 index 000000000..4fd9bf6d8 --- /dev/null +++ b/en/on-call/integration/change-integration/argocd.mdx @@ -0,0 +1,220 @@ +--- +title: "Argo CD change integration" +description: "Sync Argo CD application sync operations to Flashduty On-call through an Argo CD Notifications webhook service, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Argo CD", "ArgoCD", "GitOps", "Sync", "Notifications", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Argo CD pushes changes through its built-in **Notifications** (`argocd-notifications-controller`). This integration provides an `argocd-notifications-cm` configuration with one webhook service, one request body template, and one trigger. Each sync operation of an Argo CD Application becomes one Flashduty change: it is recorded as Processing when the sync starts and updated to Done, Failed, or Canceled when it ends. + +Automated syncs, manual syncs from the UI or CLI, and rollbacks are all sync operations and are all recorded. For sync-failed and health-degraded alerts, use the Argo CD alert integration; both integrations can be configured side by side. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Argo CD** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `application`, `project`, or `destination_namespace` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Argo CD +--- + +The steps below need Kubernetes permission to edit ConfigMaps in the Argo CD namespace (`argocd` by default) and to edit annotations on Applications or AppProjects. The Argo CD cluster must be able to reach the domain of the push URL. + + + + +Save the following as `flashduty-change.yaml` and replace `url` with the push URL copied above (including `?integration_key=...`): + +```yaml +data: + service.webhook.flashduty-change: | + url: + headers: + - name: Content-Type + value: application/json + + template.flashduty-change: | + webhook: + flashduty-change: + method: POST + body: | + { + "app_uid": {{ .app.metadata.uid | toJson }}, + "app_name": {{ .app.metadata.name | toJson }}, + "app_namespace": {{ .app.metadata.namespace | toJson }}, + "project": {{ .app.spec.project | toJson }}, + "destination": {{ dig "spec" "destination" "name" (dig "spec" "destination" "server" "" .app) .app | toJson }}, + "destination_namespace": {{ dig "spec" "destination" "namespace" "" .app | toJson }}, + "argocd_url": {{ .context.argocdUrl | toJson }}, + "phase": {{ dig "status" "operationState" "phase" "" .app | toJson }}, + "message": {{ dig "status" "operationState" "message" "" .app | toJson }}, + "started_at": {{ dig "status" "operationState" "startedAt" "" .app | toJson }}, + "finished_at": {{ dig "status" "operationState" "finishedAt" "" .app | toJson }}, + "revision": {{ dig "status" "operationState" "syncResult" "revision" (dig "status" "operationState" "operation" "sync" "revision" "" .app) .app | toJson }}, + "initiated_by": {{ dig "status" "operationState" "operation" "initiatedBy" "username" "" .app | toJson }}, + "automated": {{ dig "status" "operationState" "operation" "initiatedBy" "automated" false .app | toJson }}, + "dry_run": {{ dig "status" "operationState" "operation" "sync" "dryRun" false .app | toJson }} + } + + trigger.on-flashduty-change: | + - when: app.status.operationState != nil and app.status.operationState.phase in ['Running'] + oncePer: app.status.operationState?.startedAt + send: [flashduty-change] + - when: app.status.operationState != nil and app.status.operationState.phase in ['Succeeded', 'Failed', 'Error'] + oncePer: app.status.operationState?.startedAt + send: [flashduty-change] +``` + +Merge it into the existing `argocd-notifications-cm` (`--type merge` only adds or updates the keys above and leaves the rest of the configuration alone): + +```bash +kubectl patch configmap argocd-notifications-cm -n argocd --type merge --patch-file flashduty-change.yaml +``` + +If Argo CD is installed with the Helm chart, put `service.webhook.flashduty-change` under `notifications.notifiers`, the template under `notifications.templates`, and the trigger under `notifications.triggers`; otherwise the next upgrade overwrites manual edits. + +Notes: + +- Every value in the template is escaped with `toJson`, so quotes and line breaks in sync messages cannot break the JSON. Do not remove it. Do not rename fields; `app_uid`, `phase`, and `started_at` are required +- Optional fields are read with `dig`, so the template renders even when the application has never synced or the sync has no result yet +- The two trigger conditions cover the start and the end of a sync. `oncePer` is the sync operation's start time, so the start and the end of every sync operation are each sent once, even when Argo CD does not observe the state between two consecutive syncs. Do not remove it +- The service name `flashduty-change` differs from `flashduty` used by the alert integration, so the two integrations' push URLs do not interfere +- `argocd_url` comes from `context.argocdUrl` in `argocd-notifications-cm` and is used to build the change link. Without it, changes have no link but are still recorded + + + + + +A trigger sends only after it is subscribed. Choose one scope: + +- **One application**: add an annotation to the Application + + ```bash + kubectl patch application -n argocd --type merge \ + -p '{"metadata":{"annotations":{"notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change":""}}}' + ``` + +- **All applications in a project**: add the same annotation `notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change: ""` to the AppProject's `metadata.annotations` +- **All applications**: add an entry to `subscriptions` in `argocd-notifications-cm`. If `subscriptions` already exists (for example the entry added by the alert integration), append to the existing list instead of overwriting it with the merge command above + + ```yaml + subscriptions: | + - recipients: + - flashduty-change + triggers: + - on-flashduty-change + ``` + +When the subscription takes effect, each application that has synced before immediately sends the result of its latest sync, and Flashduty records it as one change with that sync's original start and end times. + + + + + +Argo CD has no button for sending a test message. From the `argocd-notifications-controller` Pod, use `argocd admin notifications template notify` to send one notification based on the application's current state: + +```bash +kubectl exec -n argocd deploy/argocd-notifications-controller -- \ + /usr/local/bin/argocd admin notifications template notify flashduty-change --recipient flashduty-change +``` + +The command prints debug logs of the request and response, including the full push URL with its `integration_key`, so do not paste the output anywhere public. A `200 OK` status on the `Received response:` line means Flashduty accepted the request. For an application that has synced before, this notification is the result of its latest sync and merges into that sync's existing record without adding a change; for an application that has never synced, Flashduty ignores it. + + + + + +Sync a subscribed application (click **Sync** in the UI, or run `argocd app sync `). Confirm that a Processing change appears in the Flashduty change list and is updated to Done or Failed when the sync ends. + + + + +## What one change is +--- + +One change is one sync operation of one application. Its change key (change_key) is `/`: + +- `app_uid` is the application's `metadata.uid`. Kubernetes assigns every object a UID that is unique over the whole lifetime of the cluster, so same-named applications in different Argo CD instances, and an application deleted and recreated, are different applications +- `started_at` is the sync operation's start time (`status.operationState.startedAt`, recorded in UTC). Argo CD writes it when the sync starts and keeps it through retries, and an application runs only one sync operation at a time + +So the start, the failed retries, and the final result of one sync update the same change, and two syncs of the same application are two changes, even when they sync the same revision. Changes to the application name, project, revision, or sync message do not change the change key. + +Flashduty rejects a request that lacks `app_uid` or `started_at`, or whose times are not in RFC 3339 format. + +## Status mapping +--- + +| Argo CD sync phase (`phase`) | Flashduty change status | +|---|---| +| `Running`, `Terminating` | Processing | +| `Succeeded` | Done | +| `Failed`, `Error` | Failed | +| `Failed` with the message `Operation terminated` (**Terminate** in the UI, or `argocd app terminate-op`) | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time. An operation that Argo CD terminates because of the sync timeout (the message contains `triggered by controller sync timeout`) is recorded as Failed. + +Sync phases are case-sensitive, and other values are rejected. The following deliveries return success without creating a change: an application with no sync operation yet (empty `phase`), and dry-run syncs. + +The recorded time is `started_at` when a sync starts and `finished_at` when it ends. While Argo CD retries a failed sync automatically, the phase stays `Running`, so the change is not marked Failed early. + +## Change content +--- + +- **Title**: `: sync to `. A Git commit shows its first 7 characters; other values, such as a Helm chart version, are shown as is. The revision or destination namespace part is omitted when empty +- **Link**: `/applications/`, only when `context.argocdUrl` is configured + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `application` | Application name | +| `app_uid` | The application's `metadata.uid` | +| `app_namespace` | Namespace of the Application object | +| `project` | Argo CD project of the application | +| `destination` | Destination cluster name, or the cluster address when no name is set | +| `destination_namespace` | Destination namespace | +| `revision` | Synced revision (Git commit or chart version) | +| `actor` | User who started the sync; `automated` for automated syncs | +| `phase` | Latest sync phase | +| `message` | Latest sync message, such as the failure reason, truncated beyond 1024 bytes | + +Empty fields are not written as labels. + +## FAQ +--- + + + + +- Check the `argocd-notifications-controller` logs (`kubectl logs -n argocd deploy/argocd-notifications-controller`) and confirm that the application has the `notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change` annotation, or that `subscriptions` includes `on-flashduty-change` +- If the logs show `template 'flashduty-change' is not supported` or `trigger 'on-flashduty-change' is not configured`, confirm the configuration is in `argocd-notifications-cm`; for Helm installs, check the corresponding values + + + + + +When a sync finishes within a few seconds, Argo CD may not observe the `Running` phase and sends only the end notification. Flashduty records the change directly in its end state. + + + + + +No. An event with the same phase and the same time is recorded only once. + + + + + +Confirm the template matches this page and every value goes through `toJson`. The response names the missing or unsupported field, such as `app_uid is missing`, `started_at is missing`, or `unsupported phase`. + + + + +For related configuration, see the Argo CD documentation on [Webhook](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/webhook/), [Triggers](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/triggers/), [Templates](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/templates/), and [Subscriptions](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/subscriptions/). diff --git a/en/on-call/integration/change-integration/buildkite.mdx b/en/on-call/integration/change-integration/buildkite.mdx new file mode 100644 index 000000000..a44fd0b5e --- /dev/null +++ b/en/on-call/integration/change-integration/buildkite.mdx @@ -0,0 +1,123 @@ +--- +title: "Buildkite change integration" +description: "Sync Buildkite pipeline builds to Flashduty On-call through a Buildkite webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Buildkite", "build", "deployment", "Webhook", "CI/CD"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Buildkite organization's webhook notification service to sync pipeline builds to Flashduty On-call. Each build becomes one Flashduty change; every state of the build, from scheduled and running through failing to passed, failed, or canceled, updates that same change. + +We recommend sending only deployment pipelines: select those pipelines in the webhook, or use branch filtering to send builds of release branches only. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Buildkite** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `pipeline` or `ref` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Buildkite +--- + + + + +In your Buildkite organization, go to **Settings → Notification Services** and click **Add** next to **Webhook**. You need organization admin permission. + + + + + +1. **Description**: a name you can recognize, such as `Flashduty` +2. **Webhook URL**: paste the complete Flashduty integration Push URL +3. **Token**: keep the default; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Events**, select `build.scheduled`, `build.running`, `build.failing`, `build.finished`, and `build.skipped` +2. Under **Pipelines**, choose the pipelines to send (all, specific pipelines, or the pipelines of specific teams or clusters) +3. To send only some branches, enter branch patterns under **Branch filtering**; leave it empty for all branches +4. Click **Add Webhook Notification** to save + + + + +## What one change is +--- + +One build is one change. Its change identifier (change_key) is the build's `build.id`, a UUID unique across Buildkite. Every `build.*` event of the same build updates the same change; two builds of the same pipeline and branch are two changes, and a rebuild creates a new build and a new change. + +## Status mapping +--- + +Flashduty takes the status from `build.state` in the delivery: + +| Buildkite build state | Flashduty change status | +|---|---| +| blocked (waiting on a block step) | Planned | +| creating, scheduled, waiting | Ready | +| running, failing, waiting_failed, canceling | Processing | +| passed | Done | +| failed | Failed | +| canceled, skipped, not_run | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. A build waiting on a block step is delivered as `build.finished` with state `passed` and `blocked` set to `true`; Flashduty records it as Planned and updates it to the final status when the build continues and finishes. + +These deliveries return success but create no change: `ping` and other non-build events such as `job.*`, `agent.*`, and `cluster_token.*`. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: build # on ` | +| Description | The build message, usually the commit message | +| Link | The build's page in Buildkite | + +Use labels for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `pipeline` | Pipeline slug | +| `repo` | The pipeline's repository URL | +| `ref` | The build's branch | +| `sha` | The build's commit SHA (absent until Buildkite resolves the commit) | +| `actor` | Name of the user who triggered the build | +| `source` | How the build was triggered: `webhook`, `api`, `ui`, `trigger_job`, or `schedule` | +| `build_id` | Build UUID | +| `build_number` | Build number within the pipeline | +| `state` | The latest Buildkite build state; `blocked` while waiting on a block step | + +## FAQ +--- + + + + +- Make sure the webhook has the `build.*` events selected; `job.*` or `agent.*` events alone create no changes +- Make sure the build's pipeline and branch are within the webhook's **Pipelines** and **Branch filtering** settings +- At the bottom of the webhook settings page, click **Load recent requests** to see the last 20 deliveries and Flashduty's responses + + + + + +No. An event with the same state and time is recorded only once. + + + + + +- `unsupported build.state`: Flashduty received a build state it does not support yet; contact us +- `build.id is missing`: the delivery is incomplete; make sure it comes from Buildkite's webhook notification service + + + diff --git a/en/on-call/integration/change-integration/custom-event.mdx b/en/on-call/integration/change-integration/custom-event.mdx index 2c57529f7..0896d868e 100644 --- a/en/on-call/integration/change-integration/custom-event.mdx +++ b/en/on-call/integration/change-integration/custom-event.mdx @@ -61,14 +61,14 @@ Use the **push URL** shown on the integration details page. The URL format is: | :--- | :---: | :--- | :--- | | title | Yes | string | Change title, such as a release title, ticket title, or deployment task name. | | change_key | Yes | string | Change identifier. Events with the same `change_key` are treated as the same change. Subsequent events update the change status, labels, and link. | -| change_status | Yes | string | Change status. Enum values are case-sensitive: `Planned`, `Ready`, `Processing`, `Canceled`, and `Done`. | +| change_status | Yes | string | Change status. Enum values are case-sensitive: `Planned`, `Ready`, `Processing`, `Canceled`, `Done`, and `Failed`. | | event_time | No | integer | Event occurrence time as a Unix timestamp. Seconds and milliseconds are both supported. If omitted, Flashduty uses the time when the event is received. | | description | No | string | Change description, such as change content, impact scope, execution steps, or rollback plan. | | link | No | string | Change details link, such as a release, ticket, or CI/CD task URL. | | labels | No | map | Change labels. Both keys and values must be strings. We recommend following the Prometheus label naming convention for keys. Flashduty replaces special characters such as spaces, dots, and slashes in label keys with underscores. | -When `change_status` is `Done` or `Canceled`, Flashduty records the event time as the change end time. If you report a non-terminal status again, the end time is cleared. +When `change_status` is `Done`, `Canceled`, or `Failed`, Flashduty records the event time as the change end time. If you report a non-terminal status again, the end time is cleared. ### Response @@ -151,7 +151,7 @@ Labels describe events and should be as rich as possible: - **Change scope**: such as host, cluster, etc. - **Change ownership**: such as team, owner, etc. -- **Change lifecycle**: use the same `change_key` to report different `change_status` values as the change moves through planned, processing, completed, or canceled states. This helps restore the change process on the incident timeline. +- **Change lifecycle**: use the same `change_key` to report different `change_status` values as the change moves through planned, processing, completed, canceled, or failed states. This helps restore the change process on the incident timeline. ## FAQ diff --git a/en/on-call/integration/change-integration/github.mdx b/en/on-call/integration/change-integration/github.mdx new file mode 100644 index 000000000..07d479f62 --- /dev/null +++ b/en/on-call/integration/change-integration/github.mdx @@ -0,0 +1,132 @@ +--- +title: "GitHub change integration" +description: "Sync GitHub deployments and releases to Flashduty On-call through a GitHub webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "GitHub", "Deployment", "Release", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a GitHub repository or organization webhook to sync deployments and releases to Flashduty On-call. Each deployment and each release becomes one Flashduty change; every state of a deployment, from created and queued through running to success or failure, updates that same change. + +GitHub Actions jobs that declare an `environment` create deployments automatically, so repositories that release with Actions can connect without changing their workflows. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **GitHub** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `repo` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure GitHub +--- + + + + +- Repository: go to the repository's **Settings → Webhooks** and click **Add webhook** +- Organization: go to the organization's **Settings → Webhooks** and click **Add webhook**; events from every repository in the organization are sent + +You need admin permission on the repository or organization. + + + + + +1. **Payload URL**: paste the complete Flashduty integration Push URL +2. **Content type**: select `application/json` (`application/x-www-form-urlencoded` is also accepted) +3. **Secret**: leave it empty; Flashduty authenticates the request by the `integration_key` in the Push URL + + + + + +1. Select **Let me select individual events** +2. Check **Deployments**, **Deployment statuses**, and **Releases**, and uncheck **Pushes**, which is selected by default +3. Keep **Active** checked and click **Add webhook** + +After you save, GitHub sends a `ping`. Flashduty accepts it without creating a change. + + + + +## What one change is +--- + +| GitHub object | Change key (change_key) | Notes | +|---|---|---| +| Deployment | `deployment:` | The `deployment` event and every `deployment_status` event of one deployment update the same change; two deployments of the same repository to the same environment are two changes | +| Release | `release:` | Publishing, unpublishing, and deleting one release update the same change | + +## Status mapping +--- + +| GitHub event | GitHub state | Flashduty change status | +|---|---|---| +| deployment | created | Ready | +| deployment_status | waiting (waiting for environment approval) | Planned | +| deployment_status | pending, queued | Ready | +| deployment_status | in_progress | Processing | +| deployment_status | success | Done | +| deployment_status | failure, error | Failed | +| deployment_status | error from a GitHub Actions job canceled on the run page (`workflow_run.conclusion` is `cancelled`) | Canceled | +| release | published | Done | +| release | unpublished, deleted | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. + +These deliveries are accepted without creating a change: `ping`, any other event type, the release actions `created`, `edited`, `released`, and `prereleased` (GitHub also sends `published` when a release is published, and that is the one recorded), and the deployment state `inactive` (an older deployment replaced by a newer one; its earlier result stays as it was). + +## Change content +--- + +| Field | Deployment | Release | +|---|---|---| +| Title | `: deploy () to ` | `: release ` | +| Description | The deployment's description | The release name (empty when it equals the tag) | +| Link | The deployment log (`log_url` or `target_url`), or the repository's Deployments page when there is none | The release page | + +Labels can be used in routes and to filter the change list: + +| Label | Deployment | Release | +|---|---|---| +| `repo` | Full repository name, such as `octo-org/hello-world` | Same | +| `environment` | Deployment environment | — | +| `ref` | The branch, tag, or SHA deployed | The release's target branch or commit | +| `sha` | Full commit SHA deployed | — | +| `version` | — | Release tag | +| `task` | Deployment task, usually `deploy` | — | +| `actor` | The user who created the deployment | The release author | +| `deployment_id` / `release_id` | GitHub object ID | GitHub object ID | +| `state` | The latest GitHub deployment state | — | +| `prerelease` | — | `true` for a pre-release | + +## FAQ +--- + + + + +- Make sure the webhook has **Deployments** and **Deployment statuses** checked. **Pushes** alone creates no changes +- Check the delivery history and Flashduty's responses under **Recent Deliveries** on the GitHub webhook page +- Only releases that use GitHub Deployments send deployment events, for example a GitHub Actions job that declares an `environment`, or a call to the Deployments API + + + + + +No. An event with the same state and time is recorded once. + + + + + +- `unsupported deployment_status.state`: Flashduty received a deployment state it does not support yet. Contact us +- `deployment.id is missing` or `release.id is missing`: the payload is incomplete. Make sure the delivery comes from a native GitHub webhook + + + diff --git a/en/on-call/integration/change-integration/gitlab.mdx b/en/on-call/integration/change-integration/gitlab.mdx new file mode 100644 index 000000000..7c67c1556 --- /dev/null +++ b/en/on-call/integration/change-integration/gitlab.mdx @@ -0,0 +1,133 @@ +--- +title: "GitLab change integration" +description: "Sync GitLab deployments to Flashduty On-call through a GitLab webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "GitLab", "Deployment", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a GitLab project or group webhook to sync deployments to Flashduty On-call. Each deployment becomes one Flashduty change; every state of a deployment, from waiting for approval through running to success, failure or cancellation, updates that same change. + +GitLab CI/CD jobs that declare an `environment` create deployments automatically, so projects that release with GitLab CI/CD can connect without changing their pipelines. This works for both GitLab.com and self-managed GitLab. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **GitLab** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure GitLab +--- + + + + +- Project: go to the project's **Settings → Webhooks** and click **Add new webhook** +- Group (GitLab Premium or higher): go to the group's **Settings → Webhooks** and click **Add new webhook**; deployments from every project in the group are sent + +Project webhooks need the Maintainer or Owner role on the project; group webhooks need the Owner role on the group. + + + + + +1. **URL**: paste the complete Flashduty integration Push URL +2. **Signing token** and **Secret token**: not needed; Flashduty authenticates the request with the `integration_key` in the Push URL + + + + + +1. Under **Trigger**, select only **Deployment events** and clear the default **Push events** +2. Keep **Enable SSL verification** selected and click **Add webhook** + +GitLab's **Test** feature cannot send deployment events. Other events sent with Test (such as Push events) get a success response from Flashduty but create no change. + + + + +## What one change is +--- + +| GitLab object | Change identifier (change_key) | Notes | +|---|---|---| +| Deployment | `deployment:` | Every Deployment event of one deployment updates the same change; two deployments of the same project to the same environment (including a retried deploy job) are two changes | + +`deployment_id` is unique within one GitLab instance. To connect several GitLab instances (for example GitLab.com and a self-managed instance), create one integration per instance. + +## Status mapping +--- + +| GitLab deployment status | Flashduty change status | +|---|---| +| blocked (waiting for approval or a manual action) | Planned | +| created | Ready | +| running | Processing | +| success | Done | +| failed | Failed | +| canceled, skipped | Canceled | + +Done, Failed and Canceled are end states; Flashduty records the change's end time. GitLab only sends events for blocked, running, success, failed and canceled. + +These deliveries get a success response but create no change: event types other than Deployment (Push, Pipeline and so on), and the protected-environment approval events `approved` and `rejected`. An approval event describes the approval record, not the deployment itself: after an approval GitLab sends `running` when the deployment starts, and after a rejection it sends `failed`; the change status follows those deployment events. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: deploy () to ` | +| Description | The title of the deployed commit (`commit_title`) | +| Link | The CI/CD job that ran the deployment; deployments created through the API or by a trigger job have no job, so the link is the project's Environments page | + +Labels can be used for routing and for filtering the change list: + +| Label | Content | +|---|---| +| `project` | Full project path, for example `acme/order-service` | +| `project_id` | GitLab project ID | +| `environment` | Deployment environment | +| `environment_tier` | Environment tier, for example `production` or `staging` | +| `ref` | Deployed branch or tag | +| `sha` | Short SHA of the deployed commit | +| `actor` | Username of the user who triggered the deployment | +| `deployment_id` | GitLab deployment ID | +| `state` | Latest GitLab deployment status | + +## FAQ +--- + + + + +- Make sure the webhook has **Deployment events** selected. With only **Push events** selected, no changes are created +- Check the deliveries and Flashduty's responses under **Recent events** on the GitLab webhook edit page +- Only GitLab deployments produce deployment events, for example a CI/CD job that declares an `environment`, or a call to the Deployments API + + + + + +No. An event with the same status and the same time is recorded only once. + + + + + +After a deployment is rejected, GitLab sends `failed`; Flashduty records the deployment status as Failed, with the `state` label set to `failed`. + + + + + +- `unsupported deployment status`: Flashduty received a deployment status it does not support yet; contact us +- `deployment_id is missing`: the payload is incomplete; make sure it comes from a native GitLab webhook + + + diff --git a/en/on-call/integration/change-integration/hcp-terraform.mdx b/en/on-call/integration/change-integration/hcp-terraform.mdx new file mode 100644 index 000000000..b7d708efa --- /dev/null +++ b/en/on-call/integration/change-integration/hcp-terraform.mdx @@ -0,0 +1,134 @@ +--- +title: "HCP Terraform change integration" +description: "Sync Terraform runs to Flashduty On-call through HCP Terraform workspace notifications, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "HCP Terraform", "Terraform Cloud", "Run", "Webhook", "infrastructure changes"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use HCP Terraform (formerly Terraform Cloud) workspace notifications to sync Terraform runs to Flashduty On-call. Each run becomes one Flashduty change; every state of a run, from created through planning, waiting for confirmation, and applying to completed, errored, or canceled, updates that same change. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **HCP Terraform** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `organization` or `workspace` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure HCP Terraform +--- + +Notifications are configured per workspace, so configure one for each workspace you want to connect. You need admin permission on the workspace. + + + + +In the workspace, go to **Settings → Notifications** and click **Create a notification**. + + + + + +1. **Destination**: select **Webhook** +2. **Name**: enter a recognizable name, such as `Flashduty` +3. **Webhook URL**: paste the complete Flashduty integration Push URL +4. **Token**: leave it empty; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Run Events**, select **All events** +2. Under **Workspace Events** (drift detection, auto destroy, and so on), select **No events**; Flashduty ignores these notifications +3. Click **Create a notification** + +When you save, HCP Terraform sends a verification request. Flashduty accepts it without creating a change. You can verify again later with **Send a test**. + + + + +You can also manage this configuration with the Terraform `tfe` provider: a `tfe_notification_configuration` resource with `destination_type = "generic"`, `url` set to the Push URL, and `triggers` set to `["run:created", "run:planning", "run:needs_attention", "run:applying", "run:completed", "run:errored"]`. + +## What one change is +--- + +| HCP Terraform object | Change key (change_key) | Notes | +|---|---|---| +| Run | `run_id`, for example `run-FwnENkvDnrpyFC7M` | Every notification of one run updates the same change; two runs of the same workspace are two changes | + +## Status mapping +--- + +| Notification trigger | Run status (run_status) | Flashduty change status | +|---|---|---| +| run:created | pending | Ready | +| run:planning | planning | Processing | +| run:needs_attention | for example planned or policy_override (waiting for confirmation) | Planned | +| run:applying | applying | Processing | +| run:completed | applied, planned_and_finished, planned_and_saved | Done | +| run:completed | discarded (the run was discarded at the confirm step) | Canceled | +| run:errored | errored, policy_soft_failed | Failed | +| run:errored | canceled, force_canceled | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time. + +`planned_and_finished` means a run that only planned (no changes, or a plan-only run). It is also recorded as Done; use the `run_status` label to tell it apart. + +The following deliveries are accepted without creating a change: the verification request sent on save or by **Send a test** (trigger `verification`), health assessment notifications (`assessment:drifted`, `assessment:check_failure`, `assessment:failed`), and workspace notifications (`workspace:auto_destroy_reminder`, `workspace:auto_destroy_run_results`, `workspace:deleted`). + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `/: terraform run ` | +| Description | The run message (why the run was queued, such as a VCS commit message or a message entered manually) | +| Link | The run's page in HCP Terraform | + +Use labels for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `organization` | HCP Terraform organization name | +| `workspace` | Workspace name | +| `workspace_id` | Workspace ID, for example `ws-XdeUVMWShTesDMME` | +| `run_id` | Run ID | +| `run_status` | Run status in the latest notification | +| `actor` | User who created the run | + +## FAQ +--- + + + + +- Make sure the notification is enabled and **Run Events** are selected. **Workspace Events** alone create no changes +- Check recent deliveries and Flashduty's responses on the notification configuration page +- Notifications are per workspace; make sure the run's workspace has this notification configured + + + + + +No. An event with the same run, status, and time is recorded only once. + + + + + +No. A health assessment reports resources drifting from their configuration, not a change. Flashduty accepts it and ignores it. + + + + + +- `unsupported notifications[].trigger` or `unsupported notifications[].run_status`: Flashduty received a trigger or run status it does not support yet; contact us +- `run_id is missing`: the payload is incomplete; make sure it comes from an HCP Terraform webhook notification + + + diff --git a/en/on-call/integration/change-integration/jenkins.mdx b/en/on-call/integration/change-integration/jenkins.mdx new file mode 100644 index 000000000..bf2d842be --- /dev/null +++ b/en/on-call/integration/change-integration/jenkins.mdx @@ -0,0 +1,145 @@ +--- +title: "Jenkins change integration" +description: "Sync every build of your Jenkins deployment jobs to Flashduty On-call through the Jenkins Notification plugin, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Jenkins", "Notification plugin", "build", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use the Jenkins [Notification plugin](https://plugins.jenkins.io/notification/) to sync job builds to Flashduty On-call. Each build becomes one Flashduty change; the build's start and finish update that same change. + +Jenkins cannot tell whether a build changed anything, so add the notification only to **jobs that deploy**, not to jobs that only compile or test. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Jenkins** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `job` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Jenkins +--- + + + + +Go to **Manage Jenkins → System** and make sure **Jenkins URL** under **Jenkins Location** is set to the address of your Jenkins. Without it, notifications carry no build link, Flashduty cannot identify the build, and the delivery is rejected. + + + + + +Go to **Manage Jenkins → Plugins → Available plugins**, search for **Notification**, and install it. You need Jenkins administrator permission. + +The plugin also needs the **JUnit** plugin, which Jenkins does not install with it. If **Manage Jenkins → Plugins → Installed plugins** does not list JUnit, install it too. Without JUnit, no notification is sent and the build log shows `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction`. + + + + + +1. Open the deployment job, click **Configure**, find the **Job Notifications** section, and click **Add Endpoint** +2. **Format**: select `JSON` +3. **Protocol**: select `HTTP` +4. **Event**: select `All Events`, so Flashduty sees the build both start and finish +5. **URL Source**: select `Credentials Store`, save the complete Flashduty integration Push URL as a **Secret text** credential, and select that credential in **URL**. With `Plain Text`, the plugin prints the full Push URL, including `integration_key`, in the log of every build +6. Keep **Branch** at the default `.*`, leave the other options at their defaults, and click **Save** + +If the job configuration is managed by a Jenkinsfile (for example, a multibranch pipeline), add the same settings to the Jenkinsfile's `properties`. You can generate the code on the pipeline's **Pipeline Syntax → Snippet Generator** page by selecting `properties: Set job properties`. + + + + + +Run the job once; the change appears in the Flashduty change list. The Notification plugin has no test button. If Jenkins cannot reach Flashduty, the build log shows `Failed to notify endpoint`; the plugin does not check the response, so a delivery that Flashduty rejects is not shown in Jenkins. + + + + +## What one change is +--- + +Each build is one change. Its change key (change_key) is `#`, for example `https://jenkins.example.com/job/deploy/18/#4711`. + +- Every phase of one build updates the same change +- Two builds of the same job are two changes +- When a job is deleted and recreated and its build numbers restart at 1, the queue IDs differ, so new builds are not merged into old ones +- When several Jenkins instances send to the same integration, their build URLs differ, so their builds are kept apart + +## Status mapping +--- + +| Build phase (phase) | Build result (status) | Flashduty change status | +|---|---|---| +| STARTED | — | Processing | +| COMPLETED, FINALIZED | SUCCESS | Done | +| COMPLETED, FINALIZED | UNSTABLE | Done | +| COMPLETED, FINALIZED | FAILURE | Failed | +| COMPLETED, FINALIZED | ABORTED, NOT_BUILT | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. COMPLETED means the build steps have finished; FINALIZED means post-build actions (such as archiving artifacts) have finished too. Both carry the same result. + +UNSTABLE means every build step ran, but tests or quality checks reported problems, so it is recorded as Done; use the `result` label to filter these changes. + +The plugin sends QUEUED only when the build starts, never while the build waits in the queue. Flashduty accepts QUEUED without recording it, so a change appears when its build starts. + +A `notifyEndpoints` step in a pipeline with `phase` set to `NONE` is accepted without creating a change. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | ` #`, such as `platform/order-service/main #18` | +| Description | The endpoint's **Notes** option; empty when not set | +| Link | The build page | + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `job` | Full job name, including folders and the branch of a multibranch pipeline, such as `platform/order-service/main` | +| `build_number` | Build number | +| `branch` | The Git branch the build checked out | +| `commit` | The Git commit the build checked out | +| `phase` | The latest build phase | +| `result` | The build result, present once the build has finished | + +`branch` and `commit` are sent only by freestyle jobs that use Git under **Source Code Management**. A Pipeline job that checks out with the `git` step does not send them. A notification sent when the build starts can carry the values from before this build's checkout, so rely on the values at the end of the build. Route on `job`; otherwise the early and late events of one build can land in different channels. + +## FAQ +--- + + + + +- Make sure **Format** is `JSON` and **Protocol** is `HTTP` +- Make sure **Jenkins URL** is set under **Manage Jenkins → System** +- Look for `Notifying endpoint` or `Failed to notify endpoint` in the build log +- `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction` in the build log means the JUnit plugin is missing. Install it +- When **Branch** is not `.*`, only builds that have a `BRANCH_NAME` environment variable matching it send notifications + + + + + +The plugin sends one notification when the build completes (COMPLETED) and another when post-build actions finish (FINALIZED). Both carry the same result, so the change status does not change. When both arrive within the same second, the second one is not recorded. To receive only one, set **Event** to `Job Finalized`, but then the running phase is not shown. + + + + + +Flashduty rejects a delivery in these cases: + +- `build.full_url is missing`: the Jenkins URL is not configured +- `build.queue_id is missing`: the payload has no queue ID. Make sure the delivery comes from the Notification plugin +- `build.status is missing`: an end phase arrived without a build result, usually from a pipeline calling `notifyEndpoints(phase: 'COMPLETED')` or `'FINALIZED'` before the result is set +- `must use Format JSON`: the endpoint's **Format** is `XML` +- `unsupported build.phase` or `unsupported build.status`: Flashduty received a phase or result it does not support yet. Contact us + + + diff --git a/en/on-call/integration/change-integration/jfrog-artifactory.mdx b/en/on-call/integration/change-integration/jfrog-artifactory.mdx new file mode 100644 index 000000000..4dcee68dd --- /dev/null +++ b/en/on-call/integration/change-integration/jfrog-artifactory.mdx @@ -0,0 +1,137 @@ +--- +title: "JFrog Artifactory change integration" +description: "Sync artifact deploys, deletes, moves, and copies from JFrog Artifactory to Flashduty On-call through a webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "JFrog", "Artifactory", "artifact", "Webhook", "change events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a JFrog Artifactory predefined webhook to sync artifact deploys, deletes, moves, and copies to Flashduty On-call. Each deployed artifact becomes one change, and deleting that same artifact later updates the change to Canceled; each move or copy becomes a change of its own. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **JFrog Artifactory** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `repo` or `path` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure JFrog Artifactory +--- + + + + +1. Sign in to the JFrog Platform and select **All Projects** or a specific project +2. Go to **Platform → Integrations → Webhooks** and click **New Webhook** +3. Keep the **Predefined** toggle selected (do not use Custom) + +You need admin or project admin permission. + + + + + +1. **Name**: for example, `flashduty-changes` +2. **URL**: paste the complete Flashduty integration Push URL +3. **Secret token**: leave empty; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Artifacts**, select **Artifact was deployed**, **Artifact was deleted**, **Artifact was moved**, and **Artifact was copied** +2. Select the repositories to watch: all local repositories, a list of repositories, or include/exclude path patterns +3. Click **Test** to check connectivity, then click **Create** + +**Test** sends JFrog's sample data (checksum `sample_checksum`); Flashduty returns success but records no change. + + + + +## What one change is +--- + +JFrog payloads carry no change ID, so Flashduty identifies an artifact by its location plus its content checksum: + +| Artifactory event | Change key (change_key) | Notes | +|---|---|---| +| deployed, deleted | `artifact:/@` | Deploying and later deleting the same content update the same change; new content at the same path (a different checksum) is a new change | +| moved | `moved:/@ -> ` | One change per move | +| copied | `copied:/@ -> ` | One change per copy | + +For moved and copied, `/` is the artifact's original location and `` is the payload's `target_repo_path`. + +## Status mapping +--- + +| Artifactory event (event_type) | Flashduty change status | +|---|---| +| deployed | Done | +| moved | Done | +| copied | Done | +| deleted | Canceled | + +Artifactory sends artifact events after the operation completes, so each change has already ended when its first event arrives. + +The following deliveries return success but record no change: event domains other than artifacts (Artifact Properties, Docker, Builds, Release Bundles, and so on), `cached` (a remote repository caching a downloaded artifact, which is not a change), and the sample data sent by the **Test** button. + +## Change content +--- + +| Field | deployed, deleted | moved, copied | +|---|---|---| +| Title | `/ ()` | `move / () to `, or `copy ...` for a copy | +| Description | Empty | Empty | +| Link | The artifact's page in the JFrog Platform | The target location's page in the JFrog Platform | + +The link is built from the payload's `jpd_origin`; when the payload has no such field, the change has no link. + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `repo` | Repository key; for moved and copied, the original repository | +| `path` | The artifact's path in the repository | +| `name` | File name | +| `sha256` | SHA-256 checksum of the artifact's content | +| `source_repo_path` | moved and copied only: the original location | +| `target_repo_path` | moved and copied only: the target location | +| `actor` | The user or access token subject that performed the operation | +| `event_type` | Artifactory event: `deployed`, `deleted`, `moved`, or `copied` | + +## FAQ +--- + + + + +- Make sure the webhook is **Predefined** and has events under **Artifacts** selected +- Make sure the repository you deploy to is within the webhook's selected repositories +- Check the delivery records and Flashduty's responses on the webhook's **Troubleshooting** tab (on JFrog Cloud, the instance must have this feature enabled) + + + + + +Deploying a file with identical content to the same path adds an event to the existing change instead of creating a new one. Different content creates a new change. + + + + + +A retry adds an event but does not create a new change. JFrog payloads carry no event time, so Flashduty records each event at the time it is received and cannot recognize a retry. + + + + + +- `unsupported event_type`: Flashduty received an artifact event it does not support yet; contact us +- `data.repo_key is missing`, `data.path is missing`, `data.sha256 is missing`, or `data.target_repo_path is missing`: the payload is incomplete; make sure you use a Predefined webhook, not a Custom webhook with a customized payload + + + diff --git a/en/on-call/integration/change-integration/launchdarkly.mdx b/en/on-call/integration/change-integration/launchdarkly.mdx new file mode 100644 index 000000000..1d9422060 --- /dev/null +++ b/en/on-call/integration/change-integration/launchdarkly.mdx @@ -0,0 +1,144 @@ +--- +title: "LaunchDarkly change integration" +description: "Sync LaunchDarkly feature flag and segment changes to Flashduty On-call through a LaunchDarkly webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "LaunchDarkly", "Feature Flag", "feature flag", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a LaunchDarkly organization webhook to sync feature flag and segment changes to Flashduty On-call. Each flag or segment entry in LaunchDarkly's change history becomes one Flashduty change, for example turning a flag on or off, editing targeting rules, or changing the default rule. + +LaunchDarkly sends changes that have already taken effect, so each change is recorded as **Done** directly. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **LaunchDarkly** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project`, `environment`, or `flag` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure LaunchDarkly +--- + + + + +1. Click the **gear** icon in the left sidebar to open **Organization settings** +2. Click **Integrations**, find **Webhooks**, and click **Add new** + +You need a member role that can manage integrations, such as Admin. + + + + + +1. **Name**: enter a recognizable name, such as `Flashduty` +2. **URL**: paste the full push URL of the Flashduty integration +3. **Sign this webhook**: leave it unchecked. Flashduty authenticates the delivery by the `integration_key` in the push URL + + + + + +Without a policy, LaunchDarkly sends only flag changes in the **production** environment. To send other environments or segment changes, add this policy: + +```json +[ + { + "effect": "allow", + "actions": ["*"], + "resources": ["proj/*:env/*:flag/*"] + }, + { + "effect": "allow", + "actions": ["*"], + "resources": ["proj/*:env/*:segment/*"] + } +] +``` + +Replace `env/*` with a specific environment (such as `env/production`) to send only that environment. Accept the terms and click **Save settings**. + + + + +LaunchDarkly has no test delivery button. After saving, make one change to any flag and the record appears in the Flashduty change list. + +## What one change is +--- + +| LaunchDarkly object | Change key (change_key) | Notes | +|---|---|---| +| Change history entry | The entry's `_id` | Every save of a flag or segment creates one entry, which becomes one Flashduty change; turning the same flag on and then off is two changes | + +## Status mapping +--- + +| LaunchDarkly entry | Flashduty change status | +|---|---| +| A flag or segment change (on/off, targeting rules, default rule, variations, create, delete, archive, applying an approval request, and so on) | Done | + +These deliveries are accepted without creating a change: + +- Entries for other resource kinds, such as projects, environments, members, roles, webhooks, metrics, and experiments +- Entries that contain only the following actions, which do not change how a flag evaluates: + - Creating, updating, reviewing, or deleting an approval request (once an approval request is applied, LaunchDarkly sends the entry for that step) + - Creating, updating, or deleting scheduled changes (the entry for the scheduled change is sent when it runs) + - Name, description, tags, maintainer, temporary flag, deprecation, custom properties, rule descriptions, code references, flag links, followers, and segment exports + +## Change content +--- + +| Field | Content | +|---|---| +| Title | ` in : `, such as `Checkout redesign in production: turned on the flag`; project-wide actions (such as creating a flag) name no environment | +| Description | The change comment and LaunchDarkly's change details | +| Link | The flag or segment page in LaunchDarkly | + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `project` | Project key | +| `environment` | Environment key, such as `production`; absent for project-wide actions | +| `flag` | Flag key (flag changes) | +| `segment` | Segment key (segment changes) | +| `kind` | `flag` or `segment` | +| `action` | LaunchDarkly actions, comma-separated when there are several, such as `updateOn` or `updateRules` | +| `actor` | The name of the member who made the change, or the access token or application name for API changes | +| `audit_log_id` | Change history entry ID | + +## FAQ +--- + + + + +Without a policy, LaunchDarkly sends only flag changes in the production environment. Add a policy as described in **Choose what to send**. + + + + + +No. When a delivery fails, LaunchDarkly retries it once with the same content, and Flashduty records it once. + + + + + +LaunchDarkly does not guarantee chronological delivery. Flashduty uses the entry's own time (`date`) as the change time. + + + + + +- `_id is missing`: the payload is incomplete. Make sure the delivery comes from a native LaunchDarkly webhook +- `invalid date`: the time field in the payload is malformed + + + diff --git a/en/on-call/integration/change-integration/netlify.mdx b/en/on-call/integration/change-integration/netlify.mdx new file mode 100644 index 000000000..7adc35edd --- /dev/null +++ b/en/on-call/integration/change-integration/netlify.mdx @@ -0,0 +1,130 @@ +--- +title: "Netlify change integration" +description: "Sync Netlify deploys to Flashduty On-call through Netlify deploy notifications (HTTP POST request), as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Netlify", "deploy notifications", "Deploy notifications", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Netlify project's deploy notifications to sync deploys to Flashduty On-call. Each deploy becomes one Flashduty change; every notification of that deploy, from waiting for approval and building to success or failure, updates that same change. + +Production deploys, branch deploys, and Deploy Previews are all sent; the `environment` label tells them apart. HTTP POST request deploy notifications are available on every Netlify plan. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Netlify** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Netlify +--- + +Each Netlify notification listens to one event, so add one notification for each event in the table below, all with the same Push URL. + + + + +In your Netlify project, go to **Project configuration → Notifications → Deploy notifications**, click **Add notification**, and select **HTTP POST request**. + + + + + +1. **Event to listen for**: select one event, see the next step +2. **URL to notify**: paste the complete Flashduty integration Push URL +3. **JWS secret token**: leave it empty; Flashduty authenticates the request by the `integration_key` in the Push URL +4. Click **Save** + + + + + +| Event | Needed | +|---|---| +| Deploy started | Required | +| Deploy succeeded | Required | +| Deploy failed | Required | +| Deploy restored | Recommended, records rollbacks | +| Deploy request pending, Deploy request accepted, Deploy request rejected | Add these when the project requires approval for untrusted deploys | + +Deploy locked, Deploy unlocked, and Deploy deleted are not needed: they do not change a deploy's result, and Flashduty accepts them without creating a change. + + + + +## What one change is +--- + +| Netlify object | Change key (change_key) | Notes | +|---|---|---| +| Deploy | The deploy ID (`id`) | Every notification of one deploy updates the same change; two deploys of the same project and branch are two changes | + +A rollback (Deploy restored) publishes an existing deploy again, so it updates that deploy's change with status Done. The rollback notification carries no rollback time, so the event time is when Flashduty receives it. + +## Status mapping +--- + +| Netlify event | Flashduty change status | +|---|---| +| Deploy request pending | Planned | +| Deploy request accepted | Ready | +| Deploy started | Processing | +| Deploy succeeded | Done | +| Deploy restored | Done | +| Deploy failed | Failed; Canceled when the build was canceled | +| Deploy request rejected | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: deploy () to `, such as `example-site: deploy main (f95f852) to production`; a manual deploy without a branch or commit gives `: deploy to ` | +| Description | The deploy's title, usually the commit message or the message entered for a manual deploy | +| Link | The deploy's page in the Netlify console, or the deploy's own URL when the payload has no `admin_url` | + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `project` | Netlify project name | +| `site_id` | Netlify project ID | +| `environment` | Deploy context: `production`, `deploy-preview`, `branch-deploy`, and so on | +| `ref` | The branch deployed | +| `sha` | Full commit SHA deployed | +| `deploy_id` | Netlify deploy ID | +| `review_id` | The pull request number of a Deploy Preview | +| `state` | The Netlify deploy state in the latest notification, such as `building`, `ready`, or `error` | +| `error_message` | Netlify's error message when a deploy fails | + +## FAQ +--- + + + + +Each Netlify notification sends one event. Make sure Deploy started, Deploy succeeded, and Deploy failed each have their own notification. + + + + + +No. When Netlify resends a notification that failed, Flashduty records it at the time of the event itself, and a notification with the same deploy, state, and time is recorded once. Deploy restored is the exception: it is recorded at the time Flashduty receives it, so a resent one is recorded again. + + + + + +- `unsupported X-Netlify-Event`: Flashduty received a Netlify event it does not support yet. Contact us +- `deploy id is missing`: the payload is incomplete. Make sure the delivery comes from a Netlify deploy notification + + + diff --git a/en/on-call/integration/change-integration/vercel.mdx b/en/on-call/integration/change-integration/vercel.mdx new file mode 100644 index 000000000..89a2c07b2 --- /dev/null +++ b/en/on-call/integration/change-integration/vercel.mdx @@ -0,0 +1,139 @@ +--- +title: "Vercel change integration" +description: "Sync deployments, promotions and rollbacks from a Vercel team webhook to Flashduty On-call as change events correlated with alerts and incidents." +keywords: ["change integration", "Vercel", "Deployment", "deployment events", "Instant Rollback", "Webhook"] +--- + +**Plan requirement**: This feature requires the On-call Standard plan or above. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Vercel team webhook to sync deployments and production rollbacks (Instant Rollback) to Flashduty On-call. Each deployment becomes one Flashduty change; every state of the deployment, from created and built to succeeded, promoted, failed or canceled, updates that same change. + +Vercel team webhooks are available to Pro and Enterprise teams only; Hobby accounts cannot configure them. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Vercel** and enter an integration name +3. To assign changes to specific channels, configure rules in the integration's **Routing** based on labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## In Vercel +--- + + + + +In the Vercel dashboard, switch to the target team and go to **Settings → Webhooks**. You need permission to manage the team's webhooks. + + + + + +Under **Deployment Events**, select: + +- **Deployment Created** +- **Deployment Succeeded** +- **Deployment Promoted** +- **Deployment Rollback** +- **Deployment Error** +- **Deployment Cancelled** + +Project, Feature Flag and Firewall events are not deployment changes; if selected, Flashduty returns success without recording a change. + + + + + +1. Choose the projects to send: **All Team Projects** or specific projects +2. **Endpoint URL**: paste the full Flashduty push URL +3. Click **Create Webhook** + +Vercel then shows a secret. Flashduty does not need it; requests are authenticated by the `integration_key` in the push URL. + + + + +## What one change is +--- + +| Vercel object | Change key (change_key) | Notes | +|---|---|---| +| Deployment | `deployment:` | Every event of one deployment (an ID starting with `dpl_`) updates the same change; two deployments of the same project and commit are two changes | +| Rollback | `rollback::` | An Instant Rollback is a separate change and does not modify the records of the replaced or restored deployment | + +## Status mapping +--- + +| Vercel event | Flashduty change status | +|---|---| +| `deployment.created` | Ready | +| `deployment.ready` (built, checks running) | Processing | +| `deployment.succeeded` | Done | +| `deployment.promoted` (now serving production traffic) | Done | +| `deployment.error` | Failed | +| `deployment.canceled` | Canceled | +| `deployment.rollback` | Done | + +Done, Failed and Canceled are end states; Flashduty records the change's end time. + +These deliveries return success without recording a change: event types that do not start with `deployment.` (Project, Feature Flag, Firewall and others); deployment events about checks or integration actions; `deployment.cleanup` (the deployment is permanently deleted after its retention period, which does not change its earlier result). + +## Change content +--- + +| Field | Deployment | Rollback | +|---|---|---| +| Title | `: deploy () to `, or the deployment URL when there is no Git metadata | `: roll back production to ` | +| Description | First line of the Git commit message | Empty | +| Link | The deployment's page in the Vercel dashboard | Empty (Vercel rollback events carry no link) | + +Labels can be used for routing and for filtering the change list: + +| Label | Deployment | Rollback | +|---|---|---| +| `project` | Project name | — | +| `project_id` | Project ID (starts with `prj_`) | Same | +| `environment` | `production`, a custom environment such as `staging`, or `preview` when no target is set | `production` | +| `ref` | Git branch | — | +| `sha` | Full commit SHA | — | +| `actor` | Git username of the commit author | — | +| `deployment_id` | Deployment ID | — | +| `from_deployment_id` / `to_deployment_id` | — | IDs of the replaced / restored deployment | +| `state` | Latest Vercel event, for example `succeeded` | `rollback` | + +`ref`, `sha` and `actor` come from the deployment metadata of a connected GitHub, GitLab or Bitbucket repository; deployments made directly from the CLI do not have them. + +## FAQ +--- + + + + +After a production deployment builds successfully, Vercel sends `deployment.succeeded`, then `deployment.promoted` once production traffic has switched to it. Both map to Done and update the same change. + + + + + +No. Flashduty uses the time carried by the Vercel event, so the same event at the same time is recorded once. When a delivery fails, Vercel retries it for up to 24 hours. + + + + + +Rolling back from the same deployment to the same deployment produces the same change key, so the second rollback updates the first rollback's change (its last time becomes the second rollback's time) instead of creating a new one. Vercel rollback events carry only the two deployment IDs, not a rollback ID of their own. + + + + + +- `unsupported type`: Flashduty received a deployment event it does not support yet (for example `deployment.blocked` subscribed through the API). Select only the six events listed above, or contact us +- `payload.deployment.id is missing`: the payload is incomplete; make sure the request comes from a native Vercel webhook + + + diff --git a/en/on-call/integration/webhooks/alert-webhook.mdx b/en/on-call/integration/webhooks/alert-webhook.mdx index ec60001d3..4e1f7fff2 100644 --- a/en/on-call/integration/webhooks/alert-webhook.mdx +++ b/en/on-call/integration/webhooks/alert-webhook.mdx @@ -103,6 +103,7 @@ alt | string | Yes | Caption; may be an empty string | images | [][Image](#Image) | Yes | Alert image list; null when there are no images | | labels | map[string]string | No | Label KV, both Key and Value are strings | | event_cnt | int64 | No | Associated event count | +| detail_url | string | No | Console page for this alert, in the form `{console}/alert/detail/{alert_id}`; the field is omitted when the deployment has no console base configured | | incident | [Incident](#Incident) | No | Associated incident | diff --git a/en/rum/best-practices/sampling.mdx b/en/rum/best-practices/sampling.mdx index b29468e21..094ad3855 100644 --- a/en/rum/best-practices/sampling.mdx +++ b/en/rum/best-practices/sampling.mdx @@ -309,7 +309,11 @@ The base rule uses `hash(userId) % 100` instead of `Math.random()`, which brings ## Best practice 3: full error capture with proportional sampling for the rest -A common requirement is "cut data volume to 20%, but never miss an error". Setting `sessionSampleRate` to 20 will not do it: sampling works per session, and a session that loses the draw reports nothing at all — errors included (rule 1). You would lose roughly four fifths of your errors along with the volume. The correct shape is to collect every session so no error is lost, then bucket on a stable key inside `beforeSend` so only the winning share keeps full data: + +Starting with Web SDK **0.3.0**, enable `sessionOnError` (and `sessionReplayOnError` if you need error replays) to capture error sessions without writing your own `beforeSend`; see [on-error session capture](/en/rum/sdk/web/advanced-config#on-error-session-capture) for configuration, billing, and limitations. The recipe below remains available for older versions or custom event filtering. Its failed-request filtering differs from the new options: a failed resource event alone does not trigger on-error capture. + + +A common requirement is "cut data volume to 20%, but never miss an error". Setting `sessionSampleRate` to 20 will not do it: sampling works per session, and a session that loses the draw reports nothing at all — errors included (rule 1). You would lose roughly four fifths of your errors along with the volume. The custom filtering recipe below collects every session so no error is lost, then buckets on a stable key inside `beforeSend` so only the winning share keeps full data: - **Error events**: always kept — 100% of errors - **Failed requests**: always kept — 100% of API failures (HTTP 5xx and request failures are resource events, not error events) diff --git a/en/rum/quickstart/app-management.mdx b/en/rum/quickstart/app-management.mdx index ca7a20b6c..b4b0bc691 100644 --- a/en/rum/quickstart/app-management.mdx +++ b/en/rum/quickstart/app-management.mdx @@ -297,7 +297,7 @@ After disabling geo-location or IP address collection, the related filter and an The **Remote Configuration** tab lets you adjust collection and privacy parameters online, without code changes or a new release. When enabled, the configuration on this page overrides SDK initialization settings. When disabled, clients fall back to their SDK initialization settings and data collection continues uninterrupted. -- Remote Configuration is currently available for **Browser**, **iOS**, **Android** and **WeChat Mini Program** applications. Other platform types will be enabled as their SDKs ship support. +- Remote Configuration is currently available for **Browser**, **iOS**, **Android**, **Flutter** and **WeChat Mini Program** applications. Other platform types will be enabled as their SDKs ship support. - On SaaS the feature is rolled out account by account. If the **Remote Configuration** tab is not visible on the application detail page, contact support to enable it. On private deployments it is available by default. @@ -307,11 +307,15 @@ The **Remote Configuration** tab lets you adjust collection and privacy paramete |------|------|------| | **Session sample rate** | Integer 0–100 (%) | Percentage of sessions collected. Leave it empty to skip delivering this field; clients keep the value set at SDK initialization | | **Session replay sample rate** | Integer 0–100 (%) | Percentage of sessions recorded by Session Replay. If empty, the SDK setting applies | +| **On-error session capture** (`sessionOnError`) | On / Off / Use SDK setting | For sessions missed by session sampling, uploads up to the last minute of events on error and continues collection; requires Web SDK 0.3.0 or later | +| **On-error replay capture** (`sessionReplayOnError`) | On / Off / Use SDK setting | For collected sessions missed by replay sampling, uploads buffered replay on error and continues recording; requires Web SDK 0.3.0 or later | | **Trace sample rate** | Integer 0–100 (%) | A second session-level sampling pass within already-collected sessions, deciding which sessions inject trace headers into eligible requests; the outcome is consistent within one session. Overall trace coverage is roughly *session sample rate × trace sample rate*. If empty, the SDK setting applies | | **Replay privacy level** | `mask` / `mask-user-input` / `allow` | Default masking of page content in Session Replay: `mask` obscures text and hides input values; `mask-user-input` keeps page text and hides only what users typed; `allow` records the page as it is. Loosening the level starts collecting content that was not collected before, and replays already uploaded cannot be retroactively masked. The console asks you to confirm again before publishing | | **Custom configuration keys** | Key–value pairs typed as string / number / boolean / JSON | Delivered to clients together with the remote configuration and read by your application code; the platform does not interpret them. Up to 5 keys; each key name is at most 64 bytes (counted in UTF-8, not characters), each value at most 4 KB and nesting at most 3 levels (objects and arrays each count one level), and all custom entries together at most 16 KB | -iOS, Android, and WeChat Mini Program applications also show the **Remote Configuration** tab, but their SDKs read only the **session sample rate** and **custom configuration keys** (none of the three has Session Replay; the other values are neither delivered nor effective). Every SDK has to opt in with `remoteConfigurationEnabled: true` at initialization (off by default; an application that has not opted in never requests the configuration). On iOS this requires SDK 0.6.0 or later, see [iOS SDK Advanced Configuration](/en/rum/sdk/ios/advanced-config#remote-configuration); on Android it requires SDK 0.7.0 or later, see [Android SDK Advanced Configuration](/en/rum/sdk/android/advanced-config#remote-configuration-adjust-the-sample-rate-from-the-console). +The two on-error options are independent: **On** delivers `true`, **Off** delivers `false`, and **Use SDK setting** omits the field so the corresponding `init()` option applies (off if unset). Browser applications require Web SDK 0.3.0 or later with `remoteConfigurationEnabled: true` at initialization. Turning off on-error capture does not affect sessions selected by ordinary sampling. See [Web SDK on-error session capture](/en/rum/sdk/web/advanced-config#on-error-session-capture) for scope, billing, and limitations. + +iOS, Android, Flutter, and WeChat Mini Program applications also show the **Remote Configuration** tab, but their SDKs read only the **session sample rate** and **custom configuration keys** (none of them has Session Replay; the other values are neither delivered nor effective). Every SDK has to opt in with `remoteConfigurationEnabled: true` at initialization (off by default; an application that has not opted in never requests the configuration). On iOS this requires SDK 0.6.0 or later, see [iOS SDK Advanced Configuration](/en/rum/sdk/ios/advanced-config#remote-configuration); on Android it requires SDK 0.7.0 or later, see [Android SDK Advanced Configuration](/en/rum/sdk/android/advanced-config#remote-configuration-adjust-the-sample-rate-from-the-console); on Flutter it requires `flashcat_flutter_plugin` 0.2.0 or later, see [Flutter SDK Advanced Configuration](/en/rum/sdk/flutter/advanced-config#remote-configuration). Custom entries are delivered to clients and may be readable by end users. Never put secrets, access tokens, or personally sensitive information in them. diff --git a/en/rum/quickstart/faq.mdx b/en/rum/quickstart/faq.mdx index 52b1b2784..97eda8032 100644 --- a/en/rum/quickstart/faq.mdx +++ b/en/rum/quickstart/faq.mdx @@ -20,7 +20,7 @@ Confirm that the RUM SDK is correctly imported: ```html CDN Integration