diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ea91a8718..fa67c0e772 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +### Changed + +- Update direct paging docs by @vadimkerr ([#2600](https://github.com/grafana/oncall/pull/2600)) + ### Fixed - Fix Slack direct paging issue when there are more than 100 schedules by @vadimkerr ([#2594](https://github.com/grafana/oncall/pull/2594)) diff --git a/docs/sources/integrations/manual/index.md b/docs/sources/integrations/manual/index.md index a52e73afb1..07fa46ba82 100644 --- a/docs/sources/integrations/manual/index.md +++ b/docs/sources/integrations/manual/index.md @@ -9,27 +9,84 @@ keywords: - on-call - Alertmanager - Prometheus -title: Raising alerts manually + - Direct paging +title: Page people manually weight: 300 --- -# Raising alerts manually +# Page people manually -Sometimes you need to page a specific person (following their preferred notification policy), or need help from people -in some particular team. In that case you can trigger an alert group providing some context information as well as -defining who to notify about it, a user or the person on-call in a given team's schedule. +Grafana OnCall relies on automated and pre-configured workflows, such as [integrations][integrations], +[routes, and escalation chains][escalation-chains-and-routes] to handle most of the incident response process. +However, sometimes you might need to page a [team][manage-teams] or request assistance from specific people that +are not part of these pre-defined rules. -You can create a manual alert group using the "+ Manual alert group" button (in the Alert Groups page), and set -its escalation options to page a specific person or group of people. +For such ad-hoc scenarios, Grafana OnCall allows you to create an alert group, input necessary information, and decide +who will be alerted – a team, a user, or an on-call user from a specific schedule. -> The same feature is also available as **/escalate** slack command. +## Page a team -- You need to define a title for your alert, an optional description, and select the responders which could be a -specific user in your team, a particular schedule, or multiple instances of those. -- When selecting a user, a few checks will be performed before adding them to the list of responders: user should have -a notification policy set, and ideally be on-call. -- If the user is not on-call at the time, you will get alternative users to choose instead from the OnCall schedules -that user is part of. You can still page the original user if you confirm that is what you want. -- When selecting a schedule, the user(s) on-call when the alert is triggered will be notified. +Click on "+ New alert group" on the "Alert groups" page to start creating a new alert group. +From there, you can configure the alert group to notify a particular team and optionally include additional users or +schedules. Here are the inputs you need to fill in: -> **NOTE:** for each responder (user or schedule) you can choose the notification policy to use: default or important. +- **Title**: Write a brief and clear title for your alert group. +- **Message**: Optionally, add a message to provide more details or instructions. +- **Team**: Select the team you want to page. The team's +[direct paging integration](#learn-the-flow-and-handle-warnings) will be used for notification. +- **Additional Responders**: Optionally, include more responders for the alert group. +These could be any combination of users and schedules. +For each additional responder (user or schedule), you can select a notification policy: [default or important][notify]. + +> The same feature is also available as [**/escalate**][slack-escalate] Slack command. + +## Add responders for an existing alert group + +If you want to page more people for an existing alert group, you can do so using the "Notify additional responders" +button on the specific alert group's page. Here you can select more users, or choose users who are on-call for specific +schedules. The same functionality is available in Slack using the "Responders" button in the alert group's message. + +Notifying additional responders doesn't disrupt or interfere with the escalation chain configured for the alert group; +it simply adds more responders and notifies them immediately. + +> It's not possible to page a team for an existing alert group. To page a specific team, you need to +[create a new alert group](#page-a-team). + +## Learn the flow and handle warnings + +When you pick a team to page, Grafana OnCall will automatically use the right direct paging integration for the team. +"Direct paging" is a special kind of integration in Grafana OnCall that is unique per team and is used to send alerts +to the team's ChatOps channels and start an appropriate escalation chain. + +If a team hasn't set up a direct paging integration, or if the integration doesn't have any escalation chains connected, +Grafana OnCall will issue a warning. If this happens, consider +[setting up a direct paging integration](#set-up-direct-paging-for-a-team) for the team +(or reach out to the relevant team and suggest doing so). + +## Set up direct paging for a team + +To create a direct paging integration for a team, click "+ New alert group" on the "Alert groups" page, choose the team, +and create an alert group, **regardless of any warnings**. This action automatically triggers Grafana OnCall to generate +a [direct paging integration](#learn-the-flow-and-handle-warnings) for the chosen team. + +After setting up the integration, you can customize its settings, link it to an escalation chain, +and configure associated ChatOps channels. +To confirm that the integration is functioning as intended, [create a new alert group](#page-a-team) +and select the same team for a test run. + +{{% docs/reference %}} +[integrations]: "/docs/oncall/ -> /docs/oncall//integrations" +[integrations]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations" + +[escalation-chains-and-routes]: "/docs/oncall/ -> /docs/oncall//escalation-chains-and-routes" +[escalation-chains-and-routes]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/escalation-chains-and-routes" + +[notify]: "/docs/oncall/ -> /docs/oncall//notify#configure-user-notification-policies" +[notify]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/notify#configure-user-notification-policies" + +[slack-escalate]: "/docs/oncall/ -> /docs/oncall//notify/slack#slack-escalate-command" +[slack-escalate]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/notify/slack#slack-escalate-command" + +[manage-teams]: "/docs/oncall/ -> /docs/oncall//user-and-team-management#manage-teams-in-grafana-oncall" +[manage-teams]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management#manage-teams-in-grafana-oncall" +{{% /docs/reference %}} diff --git a/docs/sources/notify/slack/index.md b/docs/sources/notify/slack/index.md index 8d85eb1348..95e3f3e6b8 100644 --- a/docs/sources/notify/slack/index.md +++ b/docs/sources/notify/slack/index.md @@ -92,19 +92,25 @@ teams of their on-call shifts. Admins can configure shift notification behavior The Grafana OnCall Slack app includes helpful message shortcuts and slash commands. -### Slack commands +### Slack `/escalate` command -Use the `/oncall` Slack command to create a new alert group directly from Slack targetting a team and/or route. +Use `/escalate` to page a team (and additional responders) directly from Slack. -1. Type `/oncall` in the message box of the desired Slack channel then click **Send**. -1. Fill out the **Start New Escalation** creation form then click **Submit**. +1. Type `/escalate` in the message box of any Slack channel then click **Send**. +1. Fill out the **Create Alert Group** form then click **Submit**. 1. Once the Grafana OnCall app sends a Slack message with the newly created alert, the alert group is open and firing. -Use the `/escalate` Slack command to create a new alert group directly from Slack and specifically paging a user or -a schedule. +It's also possible to page additional responders for an existing alert group. To do so, use the "Responders" button +in the alert group message. [Learn more about paging people manually.][integrations-manual] -1. Type `/escalate` in the message box of any Slack channel then click **Send**. -1. Fill out the **Create alert group** form then click **Submit**. +### Slack `/oncall` command + +> **DEPRECATED: `/oncall` is deprecated and WILL BE REMOVED in a future release. Use `/escalate` instead.** + +Use the `/oncall` Slack command to create a new alert group directly from Slack targetting a team and/or route. + +1. Type `/oncall` in the message box of the desired Slack channel then click **Send**. +1. Fill out the **Start New Escalation** creation form then click **Submit**. 1. Once the Grafana OnCall app sends a Slack message with the newly created alert, the alert group is open and firing. ### Message shortcuts @@ -121,4 +127,7 @@ Use message shortcuts to add resolution notes directly from Slack. Message short {{% docs/reference %}} [open-source]: "/docs/oncall/ -> /docs/oncall//open-source" [open-source]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/open-source" + +[integrations-manual]: "/docs/oncall/ -> /docs/oncall//integrations/manual" +[integrations-manual]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations/manual" {{% /docs/reference %}} diff --git a/engine/apps/slack/scenarios/paging.py b/engine/apps/slack/scenarios/paging.py index 41a12bf49a..8cb437fb60 100644 --- a/engine/apps/slack/scenarios/paging.py +++ b/engine/apps/slack/scenarios/paging.py @@ -557,14 +557,14 @@ def _get_team_select_context(organization, team): ":warning: *Direct paging integration missing*\n" "The selected team doesn't have a direct paging integration configured and will not be notified. " "If you proceed with the alert group, an empty direct paging integration will be created automatically for the team. " - "" + "" ) elif not escalation_chains_exist: context_text = ( ":warning: *Direct paging integration not configured*\n" "The direct paging integration for the selected team has no escalation chains configured. " "If you proceed with the alert group, the team likely will not be notified. " - "" + "" ) else: context_text = f"Integration <{alert_receive_channel.web_link}|{alert_receive_channel.verbal_name} ({team_name})> will be used for notification." diff --git a/grafana-plugin/src/components/ManualAlertGroup/ManualAlertGroup.tsx b/grafana-plugin/src/components/ManualAlertGroup/ManualAlertGroup.tsx index 2c8ef9bbdd..5c20486e76 100644 --- a/grafana-plugin/src/components/ManualAlertGroup/ManualAlertGroup.tsx +++ b/grafana-plugin/src/components/ManualAlertGroup/ManualAlertGroup.tsx @@ -168,7 +168,9 @@ const ManualAlertGroup: FC = (props) => {
If you proceed with the alert group, the team likely will not be notified.
= (props) => { If you proceed with the alert group, an empty direct paging integration will be created automatically for the team.