From 16ea8f07097e5e117b9504168438273297bebb8c Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Mon, 4 May 2026 17:14:10 +0200 Subject: [PATCH] docs(app): clarify notifiers and alerts --- redirections.yml | 3 + .../about/2000-01-01-backup-policies.md | 2 +- .../about/2000-01-01-maintenance-windows.md | 2 +- src/_posts/platform/app/2000-01-01-alerts.md | 105 ++++++++---- src/_posts/platform/app/2000-01-01-crash.md | 6 +- src/_posts/platform/app/2000-01-01-metrics.md | 5 +- .../platform/app/2000-01-01-notification.md | 68 -------- .../platform/app/2000-01-01-notifiers.md | 161 ++++++++++++++++++ .../app/scaling/2000-01-01-scaling.md | 4 +- .../scaling/2000-01-01-scalingo-autoscaler.md | 4 +- .../platform/billing/2000-01-01-process.md | 6 +- .../teamwork/2000-01-01-managing.md | 6 +- .../api/_posts/2025-12-01-backup_events.md | 2 +- 13 files changed, 256 insertions(+), 118 deletions(-) delete mode 100644 src/_posts/platform/app/2000-01-01-notification.md create mode 100644 src/_posts/platform/app/2000-01-01-notifiers.md diff --git a/redirections.yml b/redirections.yml index 9fe4e176d..eba8ebb03 100644 --- a/redirections.yml +++ b/redirections.yml @@ -861,6 +861,9 @@ - old: "/databases/postgresql/guides/upgrading" new: "/databases/postgresql/shared-resources/guides/upgrading" + - old: "/platform/app/notification" + new: "/platform/app/notifiers" + obsolete: - "/how-to-migrate-from-cloudcontrol/" - "/how-to-migrate-from-shelly-cloud/" diff --git a/src/_posts/databases/about/2000-01-01-backup-policies.md b/src/_posts/databases/about/2000-01-01-backup-policies.md index 1bcc1ed4c..ec223e756 100644 --- a/src/_posts/databases/about/2000-01-01-backup-policies.md +++ b/src/_posts/databases/about/2000-01-01-backup-policies.md @@ -151,7 +151,7 @@ The following events are available to monitor the backups: | `database_backup_succeeded` | A database backup has been successfully completed | | `database_backup_failed` | A database backup has failed | -To learn more about events and notifications, please visit the page dedicated to [app notifications]({% post_url platform/app/2000-01-01-notification %}). +To learn more about events and notifiers, please visit the page dedicated to [app notifiers]({% post_url platform/app/2000-01-01-notifiers %}). ## Restoring a backup diff --git a/src/_posts/databases/about/2000-01-01-maintenance-windows.md b/src/_posts/databases/about/2000-01-01-maintenance-windows.md index 6ccd97f12..b38d6cede 100644 --- a/src/_posts/databases/about/2000-01-01-maintenance-windows.md +++ b/src/_posts/databases/about/2000-01-01-maintenance-windows.md @@ -213,7 +213,7 @@ later time. By default, owner and collaborators receive email notifications one day before a scheduled maintenance execution. This notification system operates via the -[App notifications]({% post_url /platform/app/2000-01-01-notification %}) +[App notifiers]({% post_url platform/app/2000-01-01-notifiers %}) feature and the "default notifier" which is configured for each app. Please check if it is still active or configure another notifier for this purpose. It can easily be configured to suit your preferences. For instance, if you diff --git a/src/_posts/platform/app/2000-01-01-alerts.md b/src/_posts/platform/app/2000-01-01-alerts.md index 5acc1f279..0ef77380f 100644 --- a/src/_posts/platform/app/2000-01-01-alerts.md +++ b/src/_posts/platform/app/2000-01-01-alerts.md @@ -1,41 +1,80 @@ --- title: Alerts About Application Metrics nav: Alerts -modified_at: 2018-03-27 00:00:00 +modified_at: 2026-05-05 00:00:00 tags: app alert metrics +index: 37 --- -Scalingo lets you create alerts based on an application metric. When the metric's value goes above -or below a user-defined limit, Scalingo sends a notification on some specified notifiers. See [this -page]({% post_url platform/app/2000-01-01-notification %}) for more information about the notifiers. - -An alert can be added to an application by going to the Settings tab and Alerts sub-menu. - -## Alert Parameters - -In order to create a new alert, a few parameters must be provided: - -- Container type: can be any container type of an application (e.g. web, - clock...). -- Metric: - 1. CPU: percentage of CPU consumption - 1. RAM: percentage of memory consumption - 1. Swap: percentage of swap consumption - 1. Response time: 95th percentile of the requests response time - 1. 5xx errors: amount of HTTP errors (status code ranges from 500 to 599) - 1. RPM: requests per minute (RPM) received by your application. - 1. RPM per container: If your application is scaled on multiple containers, - the RPM per container divides the RPM of the application by the amount of - containers. -- Limit: any float value. -- Send when below: send the alert when metric value is _below_ the limit. -- Notifiers: list of [notifiers]({% post_url - platform/app/2000-01-01-notification %}) the alert send a notification to. -- Duration before trigger: send the alert when metric value is above the limit - for the specified duration. For example, specifying 4 minutes means that the - alert will be triggered if the limit is reached for 4 consecutive minutes. - -## Monitoring alert events +Scalingo lets you create alerts based on an [application metric][metrics]. +When the metric's value matches a configured condition for a selected duration, +Scalingo sends a notification to selected [app notifiers][notifiers]. + +## Creating Alerts + +### From the Dashboard + +- From your web browser, open your Scalingo dashboard. +- Select the app for which you want to create an alert. +- Click the **Settings** tab. +- In the settings menu, select **Alerts**. +- Click **Add**. +- Configure the trigger conditions, including the container type, metric, limit, + comparison, and duration before trigger. +- Select the notifier(s) to use when the alert is triggered. +- Click **Finish**. + +### Alert Requirements + +An alert requires at least one notifier and a trigger condition: + +Container type +: Can be any container type of an application (e.g. `web`, `clock`...). + +Metric +: - CPU: percentage of CPU consumption + - RAM: percentage of memory consumption + - Swap: percentage of swap consumption + - Response time: 95th percentile of the requests response time + - 5xx errors: amount of HTTP errors (status code ranges from 500 to 599) + - RPM: requests per minute (RPM) received by your application. + - RPM per container: If your application is scaled on multiple containers, + the RPM per container divides the RPM of the application by the amount of + containers. + +Limit +: Any float value. + +Comparison +: Send the alert when the metric value is above or below the limit. + +Notifiers +: List of [app notifiers][notifiers] the alert sends a notification to. + +Duration before trigger +: Send the alert when the metric value matches the configured condition for the + specified duration. For example, specifying 4 minutes means that the alert + is triggered if the condition is matched for 4 consecutive minutes. + +## Sending alert notifications + +Alerts use the same [notifiers] as application events. An alert must use at least +one notifier. Each app has a default notifier. + +For more information, please visit the page dedicated to [app notifiers][notifiers]. + +## Alert Events Every time an alert is triggered, an event is created. This event appears on the application's -Activity. The user responsible for the operation is labeled `scalingo-platform`. An event is also generated when an alert is created or deleted. +Activity. The user responsible for the operation is labeled `scalingo-platform`. + +The alert-related event types are: + +| Event Type | Display Name | Description | +| --------------------- | --------------- | ---------------------------- | +| `alert_added` | Alert Added | An alert has been configured | +| `alert_deleted` | Alert Deleted | An alert has been deleted | +| `app_alert_triggered` | Alert triggered | An alert was triggered | + +[notifiers]: {% post_url platform/app/2000-01-01-notifiers %} +[metrics]: {% post_url platform/app/2000-01-01-metrics %} diff --git a/src/_posts/platform/app/2000-01-01-crash.md b/src/_posts/platform/app/2000-01-01-crash.md index 6ce1fe4fd..bbb13273e 100644 --- a/src/_posts/platform/app/2000-01-01-crash.md +++ b/src/_posts/platform/app/2000-01-01-crash.md @@ -213,6 +213,6 @@ a recurrent crash occurs (i.e. when an early Runtime Error keeps occuring, or when a Timeout Error occurs). You can modify this behavior by tweaking your -[Notifier's configuration]({% post_url platform/app/2000-01-01-notification %}). -The `app_crashed`, `app_crashed_repeated` and the `app_deploy` events can be -particularily worth considering. +[app notifier configuration]({% post_url platform/app/2000-01-01-notifiers %}). +The `app_crashed`, `app_crashed_repeated` and the `app_deployed` events can be +particularly worth considering. diff --git a/src/_posts/platform/app/2000-01-01-metrics.md b/src/_posts/platform/app/2000-01-01-metrics.md index 6560c971c..882b91079 100644 --- a/src/_posts/platform/app/2000-01-01-metrics.md +++ b/src/_posts/platform/app/2000-01-01-metrics.md @@ -3,6 +3,7 @@ title: Application Metrics nav: Metrics modified_at: 2026-01-02 12:00:00 tags: app metrics +index: 35 --- Performance metrics of applications hosted on Scalingo are gathered and @@ -38,7 +39,8 @@ A lot of events are available on the application timeline but only a few relevan - Deploy event - Scale event -A complete list of events is available in our [developers' documentation](https://developers.scalingo.com/events). +A complete list of events is available in the [App Notifiers][notifiers] +documentation. The **Response time** represents the duration between the time a request arrives at our front servers and the time our front servers receives a response from @@ -130,4 +132,5 @@ type). It can greatly help to spot a bugged container and therefore simplify the debugging process. +[notifiers]: {% post_url platform/app/2000-01-01-notifiers %} [routing-errors]: {% post_url platform/networking/public/2000-01-01-routing %}#http-errors diff --git a/src/_posts/platform/app/2000-01-01-notification.md b/src/_posts/platform/app/2000-01-01-notification.md deleted file mode 100644 index f611b4e39..000000000 --- a/src/_posts/platform/app/2000-01-01-notification.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: App Notifications -nav: Notifications -modified_at: 2024-05-06 00:00:00 -tags: app notification ---- - -A notifier is a way for an application to notify about different events occurring during an -application lifetime. Notifier are defined per application. You can find the settings into the -"Notifications" tab of your app. - -A notifier has: -* a name: help you identify a notifier, -* a communication channel: Slack, webhook, Rocket.Chat, email, -* a list of events to react to. You can find a list of events below. - -Whenever an event occurs in your application, a notification is sent through the user-defined -communication channel. - -You can refer to [Slack -documentation](https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack#set-up-incoming-webhooks) -about "Incoming Webhooks" to help you set this channel up on Scalingo. - -Note that notifiers are also used to send [alerts]({% post_url platform/app/2000-01-01-alerts %}) -generated by an application. - -Note that Mattermost notifications require using the Slack notifier. - -## Events list - -* addon_db_upgraded: Addon database upgraded, A database addon was upgraded -* addon_deleted: Addon deleted, An addon was deleted -* addon_plan_changed: Addon plan changed, An addon plan was changed -* addon_provisioned: Addon provisioned, An addon was provisioned -* addon_resumed: Addon resumed, An addon was provisioned -* addon_suspended: Addon suspended, An addon was suspended -* app_alert_triggered: App alert triggered, An app alert was triggered -* app_command_ran: App command ran, A command was ran in an app -* app_crashed: App crashed, An app was crashed -* app_crashed_repeated: App crashed repeated, An app was crashed. This event is sent on each crash. -* app_deleted: App deleted, A command was ran in an app -* app_deployed: App deployed, An app was deployed -* app_renamed: App renamed, An app was renamed -* app_restarted: App restarted, An app was restarted -* app_scaled: App scaled, An app was scaled -* app_stopped: App stopped, An app was stopped -* app_transferred: App transferred, An app was transferred -* collaborator_accepted: Collaborator accepted, A collaborator invitation was accepted -* collaborator_invited: Collaborator invited, A collaborator was invited -* collaborator_removed: Collaborator removed, A collaborator was removed -* collaborator_role_changed: Collaborator's role changed, The role of a collaborator was changed -* database_backup_succeeded: Database backup succeded, a database backup has been successfully completed -* database_backup_failed: Database backup failed, a database backup has failed -* database_maintenance_planned: Database maintenance planned, A database maintenance has been planned -* database_maintenance_started: Database maintenance started, A database maintenance has started -* database_maintenance_completed: Database maintenance completed, A database maintenance has completed -* domain_added: Domain added, A domain was added -* domain_edited: Domain edited, A domain was edited -* domain_removed: Domain removed, A domain was removed -* github_link: GitHub link, A GitHub repository was linked to an app -* github_unlink: GitHub unlink, A GitHub repository was unlinked from an app -* notifier_added: Notifier added, A notifier was added -* notifier_edited: Notifier edited, A notifier was edited -* notifier_removed: Notifier removed, A notifier was removed -* variable_added: Variable added, A variable was added -* variable_bulk_edited: Variables bulk edited, Some variables were bulk edited -* variable_edited: Variable edited, A variable was edited -* variable_removed: Variable removed, A variable was removed diff --git a/src/_posts/platform/app/2000-01-01-notifiers.md b/src/_posts/platform/app/2000-01-01-notifiers.md new file mode 100644 index 000000000..21dea91f2 --- /dev/null +++ b/src/_posts/platform/app/2000-01-01-notifiers.md @@ -0,0 +1,161 @@ +--- +title: App Notifiers +nav: Notifiers +modified_at: 2026-05-05 00:00:00 +tags: app notifier notification event +index: 36 +--- + +App notifiers let you choose where Scalingo sends messages about your +application activity. A notifier is defined for one application and contains: + +- a name, to identify it in the dashboard; +- a notification channel, such as email, Slack, webhook, or Rocket.Chat; +- the event types that should trigger a notification. + +When an event matching the notifier configuration occurs, Scalingo sends a +notification through the selected channel. + + +## Vocabulary + +Event +: An occurrence of an event type generated by the platform for an app. + +Event type +: An event identifier that can be selected in a notifier, for example + `app_deployed`. + +Notifier +: A per-app configuration that defines where selected events are sent. + +Notification +: The message sent by a notifier. + +Alert +: A metric threshold rule that can trigger notifications through selected + notifiers. + + +## Default Notifier + +Each app has a default notifier. This notifier is configured to send critical +alerts by email to the application owner. + +Scalingo regularly updates the default notifier to include new critical alerts. + +We recommend keeping the default notifier active, keeping critical alert event +types selected, and adding the application's collaborators to this notifier. + + +## Creating Custom Notifiers + +Create additional notifiers when you need specific channels, recipients, or +event types. + +For example, you can create a notifier dedicated to deployment events, another +one for alerts, or another one for a webhook-based integration. + +### From the Dashboard + +- From your web browser, open your Scalingo dashboard. +- Select the app for which you want to configure notifiers. +- Click the **Settings** tab. +- In the settings menu, select **Notifiers**. +- Click **Add**. +- Select the notification platform. +- Configure the notifier name and recipients. +- Select the event types for which the notifier reacts. +- Click **Finish**. + +### Notification Platform Settings + +Depending on the selected notification platform, the notifier asks for +different delivery settings: + +- Email: target app collaborators or additional email addresses. +- Webhook-based platforms: provide a webhook URL. +- Slack: use an Incoming Webhook URL. You can refer to [Slack + documentation](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) + to set it up. +- Rocket.Chat: configure the webhook URL. +- Mattermost: use the Slack integration. + + +## Using Notifiers With Alerts + +Notifiers are also used by [application metric alerts][alerts]. When an alert +is triggered, Scalingo creates an event and sends a notification to the +notifiers selected in the alert configuration. + + +## Event Types + +A notifier can react to all events, to deployment events only, or to a custom +selection of event types. + +The available event types are: + +{::comment} +To update this list, fetch the event types from the public API endpoint: +https://api.osc-fr1.scalingo.com/v1/event_types + +Use: +- name as Event Type; +- display_name as Display Name; +- description as Description. + +Keep the rows sorted alphabetically by name. +{:/comment} + +| Event Type | Display Name | Description | +| -------------------------------- | ------------------------------ | ---------------------------------------------------------------------- | +| `addon_db_upgraded` | Addon database upgraded | A database addon was upgraded | +| `addon_deleted` | Addon deleted | An addon was deleted | +| `addon_plan_changed` | Addon plan changed | An addon plan was changed | +| `addon_provisioned` | Addon provisioned | An addon was provisioned | +| `addon_resumed` | Addon resumed | An addon was provisioned | +| `addon_suspended` | Addon suspended | An addon was suspended | +| `addon_updated` | Addon Updated | An addon has been updated | +| `alert_added` | Alert Added | An alert has been configured | +| `alert_deleted` | Alert Deleted | An alert has been deleted | +| `app_alert_triggered` | Alert triggered | An alert was triggered | +| `app_command_ran` | App command ran | A command was ran in an app | +| `app_crashed` | App crashed | An app was crashed. This event is only sent on 2nd, 5th and 12th crash. | +| `app_crashed_repeated` | App crashed repeated | An app was crashed. This event is sent on each crash. | +| `app_deleted` | App deleted | A command was ran in an app | +| `app_deployed` | App deployed | An app was deployed | +| `app_edited` | App Edited | Application settings have been edited | +| `app_project_updated` | App project updated | An app was moved to another project | +| `app_region_migration_started` | Region Migration Started | An app is being migrated to another region | +| `app_renamed` | App renamed | An app was renamed | +| `app_restarted` | App restarted | An app was restarted | +| `app_scaled` | App scaled | An app was scaled | +| `app_stopped` | App stopped | An app was stopped | +| `app_transferred` | App transferred | An app was transferred | +| `collaborator_accepted` | Collaborator accepted | A collaborator invitation was accepted | +| `collaborator_invited` | Collaborator invited | A collaborator was invited | +| `collaborator_removed` | Collaborator removed | A collaborator was removed | +| `collaborator_role_changed` | Collaborator role changed | A collaborator role was changed | +| `database_backup_failed` | Database backup failed | A database backup has failed | +| `database_backup_succeeded` | Database backup succeeded | A database backup has succeeded | +| `database_maintenance_completed` | Addon maintenance completed | A maintenance has been completed successfully on your addon | +| `database_maintenance_planned` | Addon maintenance planned | A maintenance is planned on your addon | +| `database_maintenance_started` | Addon maintenance started | A maintenance has started on your addon | +| `domain_added` | Domain added | A domain was added | +| `domain_edited` | Domain edited | A domain was edited | +| `domain_removed` | Domain removed | A domain was removed | +| `github_link` | Github link | A GitHub repo was linked to an app | +| `github_unlink` | Github unlink | A GitHub repo was unlinked to an app | +| `notifier_added` | Notifier added | A notifier was added | +| `notifier_edited` | Notifier edited | A notifier was edited | +| `notifier_removed` | Notifier removed | A notifier was removed | +| `project_created` | Project created | A project has been created | +| `project_deleted` | Project deleted | A project has been deleted | +| `project_edited` | Project edited | Project was edited | +| `variable_added` | Variable added | A variable was added | +| `variable_bulk_edited` | Variables bulk edited | Some variables was bulk edited | +| `variable_edited` | Variable edited | A variable was edited | +| `variable_removed` | Variable removed | A variable was removed | + +[alerts]: {% post_url platform/app/2000-01-01-alerts %} diff --git a/src/_posts/platform/app/scaling/2000-01-01-scaling.md b/src/_posts/platform/app/scaling/2000-01-01-scaling.md index 782094a40..da50929f0 100644 --- a/src/_posts/platform/app/scaling/2000-01-01-scaling.md +++ b/src/_posts/platform/app/scaling/2000-01-01-scaling.md @@ -227,8 +227,8 @@ The following event is available to monitor the scaling operations: | ------------ | --------------------------------------------------------------- | | `app_scaled` | A scaling operation (scale in and scale out) has been triggered | -To learn more about events and notifications, please visit the page dedicated -to [app notifications]({% post_url platform/app/2000-01-01-notification %}). +To learn more about events and notifiers, please visit the page dedicated to +[app notifiers]({% post_url platform/app/2000-01-01-notifiers %}). [routing-requests]: {% post_url platform/networking/public/2000-01-01-routing %}#requests-distribution diff --git a/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md b/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md index 5c9d26e15..5460348c6 100644 --- a/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md +++ b/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md @@ -435,7 +435,7 @@ The following event is available to monitor the Autoscaler executions: | ------------ | -------------------------------------------------------------------- | | `app_scaled` | An autoscaling operation (scale-in and scale-out) has been triggered | -To learn more about events and notifications, please visit the page dedicated -to [app notifications]({% post_url platform/app/2000-01-01-notification %}). +To learn more about events and notifiers, please visit the page dedicated to +[app notifiers]({% post_url platform/app/2000-01-01-notifiers %}). [scaling-v]: {% post_url platform/app/scaling/2000-01-01-scaling %}#vertical-scaling diff --git a/src/_posts/platform/billing/2000-01-01-process.md b/src/_posts/platform/billing/2000-01-01-process.md index e8dd44c91..09c8ae6b2 100644 --- a/src/_posts/platform/billing/2000-01-01-process.md +++ b/src/_posts/platform/billing/2000-01-01-process.md @@ -88,11 +88,11 @@ The following events are available to monitor account suspensions: | `addon_resumed` | An addon has been resumed | | `addon_suspended` | An addon has been suspended | -To learn more about events and notifications, please visit the page dedicated -to [app notifications][notifications]. +To learn more about events and notifiers, please visit the page dedicated to +[app notifiers][notifications]. [dashboard]: https://dashboard.scalingo.com -[notifications]: {% post_url platform/app/2000-01-01-notification %} +[notifications]: {% post_url platform/app/2000-01-01-notifiers %} [scale-h]: {% post_url /platform/app/scaling/2000-01-01-scaling %}#using-the-dashboard-1 diff --git a/src/_posts/platform/user-management/teamwork/2000-01-01-managing.md b/src/_posts/platform/user-management/teamwork/2000-01-01-managing.md index 18a55e94a..b639a82e1 100644 --- a/src/_posts/platform/user-management/teamwork/2000-01-01-managing.md +++ b/src/_posts/platform/user-management/teamwork/2000-01-01-managing.md @@ -252,12 +252,12 @@ The following events are available to monitor the collaborators: | `collaborator_removed` | A collaborator has been removed | | `collaborator_role_changed` | A collaborator's role has been changed | -To learn more about events and notifications, please visit the page dedicated -to [app notifications][notifications]. +To learn more about events and notifiers, please visit the page dedicated to +[app notifiers][notifications]. [dashboard]: https://dashboard.scalingo.com/ [cli]: {% post_url tools/cli/2000-01-01-start %} -[notifications]: {% post_url platform/app/2000-01-01-notification %} +[notifications]: {% post_url platform/app/2000-01-01-notifiers %} [roles]: {% post_url platform/user-management/teamwork/2000-01-01-roles %} diff --git a/src/changelog/api/_posts/2025-12-01-backup_events.md b/src/changelog/api/_posts/2025-12-01-backup_events.md index e3c1fb89b..c62bf1a6c 100644 --- a/src/changelog/api/_posts/2025-12-01-backup_events.md +++ b/src/changelog/api/_posts/2025-12-01-backup_events.md @@ -11,4 +11,4 @@ Two new event types have been added to monitor database backup operations: These events can be used to create notifiers that alert you when backup operations succeed or fail. -More information about events and notifications in the [documentation]({% post_url platform/app/2000-01-01-notification %}). +More information about events and notifiers in the [documentation]({% post_url platform/app/2000-01-01-notifiers %}).