From f4cc1a9eb0e58c2275667636b18091fa13948763 Mon Sep 17 00:00:00 2001 From: Matvey Kukuy Date: Mon, 6 Jun 2022 15:25:07 +0300 Subject: [PATCH 1/9] Data source -> Alert Source --- docs/sources/configure-notifications.md | 10 +++++----- docs/sources/integrations/_index.md | 2 +- docs/sources/integrations/add-integration.md | 10 +++++----- docs/sources/integrations/webhooks/_index.md | 6 +++--- .../integrations/webhooks/add-webhook-integration.md | 6 +++--- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/sources/configure-notifications.md b/docs/sources/configure-notifications.md index b66d672f..04a8141b 100644 --- a/docs/sources/configure-notifications.md +++ b/docs/sources/configure-notifications.md @@ -11,7 +11,7 @@ These procedures introduce you to the configuration of user settings, how to set ## Before you begin -You must have a Grafana Cloud account and be connected to a data source with alerts configured. +You must have a Grafana Cloud account. Each supported integration and the associated monitoring system has a slightly different configuration method. These methods will not be explained in this guide, however, you can follow the online instructions provided when adding an integration. @@ -36,9 +36,9 @@ You can configure how each user will receive notifications when they are assigne ## Connect to integration data sources -You use Grafana OnCall to connect to the monitoring services of your data sources listed in the Grafana OnCall **Integrations** section. +You use Grafana OnCall to connect to the monitoring services of your alert sources listed in the Grafana OnCall **Integrations** section. -1. Connect to a data source with configured alerts. +1. Connect to a alert source with configured alerts. In Grafana OnCall, click on the **Integrations** tab and click **+ New integration for receiving alerts**. @@ -48,7 +48,7 @@ You use Grafana OnCall to connect to the monitoring services of your data source 1. Configure your integration. - Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana data source, select Grafana and follow the instructions. + Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana alert source, select Grafana and follow the instructions. ## Configure escalation policies @@ -118,4 +118,4 @@ You can use an override calendar to allow team members to schedule on-call dutie 1. Click **Edit**. -1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. \ No newline at end of file +1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index f0061636..199c8fe9 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -6,6 +6,6 @@ aliases = ["/docs/grafana-cloud/oncall/integrations/"] +++ # Connect to Grafana OnCall -There are many alert sources that Grafana OnCall directly supports. Those that aren't listed in the integrations menu in OnCall can be connected using webhooks and configured with custom templates. To configure integrations that are directly supported, follow the instructions provided after selecting a data source in the **Integrations** tab in Grafana OnCall. To review general instructions, and also specific integration instructions for some popular integration options, see the following topics: +There are many alert sources that Grafana OnCall directly supports. Those that aren't listed in the integrations menu in OnCall can be connected using webhooks and configured with custom templates. To configure integrations that are directly supported, follow the instructions provided after selecting alert source in the **Integrations** tab in Grafana OnCall. To review general instructions, and also specific integration instructions for some popular integration options, see the following topics: {{< section >}} diff --git a/docs/sources/integrations/add-integration.md b/docs/sources/integrations/add-integration.md index cbdbdc98..0a1e5602 100644 --- a/docs/sources/integrations/add-integration.md +++ b/docs/sources/integrations/add-integration.md @@ -1,15 +1,15 @@ +++ -title = "Integrate with data sources" +title = "Integrate with alert sources" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] aliases = ["/docs/grafana-cloud/oncall/integrations/add-integration/"] weight = 100 +++ -# Integrate with data sources +# Integrate with alert sources -Grafana OnCall can connect directly to the monitoring services of your data sources listed in the Grafana OnCall **Integrations** section. +Grafana OnCall can connect directly to the monitoring services of your alert sources listed in the Grafana OnCall **Integrations** section. -1. Connect to a data source with configured alerts. +1. Connect to alert source with configured alerts. In Grafana OnCall, click on the **Integrations** tab and click **+ New integration for receiving alerts**. @@ -19,4 +19,4 @@ Grafana OnCall can connect directly to the monitoring services of your data sour 1. Configure your integration. - Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana data source, select Grafana and follow the instructions. \ No newline at end of file + Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana as an alert source, select Grafana and follow the instructions. diff --git a/docs/sources/integrations/webhooks/_index.md b/docs/sources/integrations/webhooks/_index.md index 026458a8..0a616cd8 100644 --- a/docs/sources/integrations/webhooks/_index.md +++ b/docs/sources/integrations/webhooks/_index.md @@ -4,9 +4,9 @@ keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager weight = 900 +++ -# Use webhooks to send and receive alerts -You can use webhooks to send alert group notifications, and also to receive alerts in the event that the data source for for the alerts is not directly supported by Grafana OnCall. You can also use custom templates to format your alerts. +# Use webhooks to receive alerts +You can use webhooks to send alerts to Grafana OnCall. You can also use custom templates to format your alerts. Follow these links to learn more about using webhooks for OnCall alert notifications: -{{< section >}} \ No newline at end of file +{{< section >}} diff --git a/docs/sources/integrations/webhooks/add-webhook-integration.md b/docs/sources/integrations/webhooks/add-webhook-integration.md index b6de74d4..9741f276 100644 --- a/docs/sources/integrations/webhooks/add-webhook-integration.md +++ b/docs/sources/integrations/webhooks/add-webhook-integration.md @@ -4,9 +4,9 @@ keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager weight = 100 +++ -# Integrate with your data source using webhooks +# Integrate with your alert source using webhooks -Grafana OnCall directly supports integrations from many data sources, but you can connect to any data source that isn't listed in the **Create Integration** page by using webhooks. +Grafana OnCall directly supports integrations from many alert sources, but you can connect to any alert source that isn't listed in the **Create Integration** page by using webhooks. 1. In **Integrations**, click **+ New integration for receiving alerts**. 1. Select a webhook format. @@ -36,4 +36,4 @@ Grafana OnCall directly supports integrations from many data sources, but you ca "link_to_upstream_details": "https://en.wikipedia.org/wiki/Downtime", "message": "Smth happened. Oh no!" }' - ``` \ No newline at end of file + ``` From 52ec19d59363443e39d4bfcdb9df02f17abf9a2e Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Tue, 7 Jun 2022 13:59:13 -0600 Subject: [PATCH 2/9] oncall docs IA refactor --- docs/Makefile | 2 +- docs/sources/calendar-schedules/_index.md | 49 +++++++++++++++++-- .../calendar-schedules/about-calendars.md | 13 ----- .../calendar-schedules/create-calendar.md | 44 ----------------- docs/sources/chat-options/_index.md | 4 +- docs/sources/chat-options/configure-slack.md | 4 +- .../chat-options/configure-telegram.md | 4 +- docs/sources/configure-user-settings.md | 6 +-- docs/sources/escalation-policies/_index.md | 4 +- ...cies.md => configure-escalation-chains.md} | 4 +- ...lation-policies.md => configure-routes.md} | 4 +- ...re-notifications.md => getting-started.md} | 6 +-- docs/sources/integrations/_index.md | 2 +- .../{webhooks => }/add-webhook-integration.md | 6 +-- .../_index.md} | 6 ++- .../add-alertmanager.md | 8 +-- .../add-grafana-alerting.md | 4 +- .../add-zabbix.md | 4 +- .../configure-outgoing-webhooks.md | 4 +- .../{webhooks => }/create-custom-templates.md | 4 +- docs/sources/integrations/webhooks/_index.md | 12 ----- docs/sources/manage-alert-groups.md | 14 ------ 22 files changed, 84 insertions(+), 124 deletions(-) delete mode 100644 docs/sources/calendar-schedules/about-calendars.md delete mode 100644 docs/sources/calendar-schedules/create-calendar.md rename docs/sources/escalation-policies/{about-escalation-policies.md => configure-escalation-chains.md} (94%) rename docs/sources/escalation-policies/{configure-escalation-policies.md => configure-routes.md} (97%) rename docs/sources/{configure-notifications.md => getting-started.md} (98%) rename docs/sources/integrations/{webhooks => }/add-webhook-integration.md (94%) rename docs/sources/integrations/{add-integration.md => available-integrations /_index.md} (89%) rename docs/sources/integrations/{ => available-integrations }/add-alertmanager.md (93%) rename docs/sources/integrations/{ => available-integrations }/add-grafana-alerting.md (97%) rename docs/sources/integrations/{ => available-integrations }/add-zabbix.md (98%) rename docs/sources/integrations/{webhooks => }/configure-outgoing-webhooks.md (93%) rename docs/sources/integrations/{webhooks => }/create-custom-templates.md (98%) delete mode 100644 docs/sources/integrations/webhooks/_index.md delete mode 100644 docs/sources/manage-alert-groups.md diff --git a/docs/Makefile b/docs/Makefile index f66259da..5ddacacf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,4 +8,4 @@ pull: .PHONY: docs docs: pull - docker run -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) + docker run -v '$(shell pwd)/sources:$(CONTENT_PATH):Z' -p $(PORT) --rm -it $(IMAGE) diff --git a/docs/sources/calendar-schedules/_index.md b/docs/sources/calendar-schedules/_index.md index c0c68cea..3b322720 100644 --- a/docs/sources/calendar-schedules/_index.md +++ b/docs/sources/calendar-schedules/_index.md @@ -1,15 +1,56 @@ +++ -title = "On-call calendar scheduling" +title = "Configure and manage on-call schedules" description = "" keywords = ["Grafana", "oncall", "on-call", "calendar"] aliases = [] -weight = 1100 +weight = 900 +++ -# Use calendars to create on-call schedules +# Configure and manage on-call schedules Grafana OnCall allows you to use any calendar service that uses the iCal format to create customized on-call schedules for team members. Using Grafana OnCall, you can create a primary calendar that acts as a read-only schedule, and an override calendar that allows all team members to modify schedules as they change. To learn more about creating on-call calendars, see the following topics: -{{< section >}} \ No newline at end of file +# Configure and manage on-call schedules + +You can use any calendar with an iCal address to schedule on-call times for users. During these times, notifications configured in escalation chains with the **Notify users from an on-call schedule** setting will be sent to the the person scheduled. You can also schedule multiple users for overlapping times, and assign prioritization labels for the user that you would like to notify. + +When you create a schedule, you will be able to select a Slack channel, associated with your OnCall account, that will notify users when there are errors or notifications regarding the assigned on-call shifts. + +## Create an on-call schedule calendar + +Create a primary calendar and an optional override calendar to schedule on-call shifts for team members. + +1. In the **Scheduling** section of Grafana OnCall, click **+ Create schedule**. + +1. Give the schedule a name. + +1. Create a new calendar in your calendar service and locate the secret iCal URL. For example, in a Google calendar, this URL can be found in **Settings > Settings for my calendars > Integrate calendar**. + +1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. + The permissions you set when you create the calendar determine who can modify the calendar. + +1. Click **Create Schedule**. + +1. Schedule on-call times for team members. + + Use the Grafana username of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. + +1. Create overlapping schedules (optional). + + When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including a level 9 prioritization, or `[L9]`. + +# Create an override calendar (optional) + +You can use an override calendar to allow team members to schedule on-call duties that will override the primary schedule. An override option allows flexibility without modifying the primary schedule. Events scheduled on the override calendar will always override overlapping events on the primary calendar. + +1. Create a new calendar using the same calendar service you used to create the primary calendar. + + Be sure to set permissions that allow team members to edit the calendar. + +1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. + +1. Click **Edit**. + +1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. \ No newline at end of file diff --git a/docs/sources/calendar-schedules/about-calendars.md b/docs/sources/calendar-schedules/about-calendars.md deleted file mode 100644 index c01e2df9..00000000 --- a/docs/sources/calendar-schedules/about-calendars.md +++ /dev/null @@ -1,13 +0,0 @@ -+++ -title = "About Grafana OnCall calendar scheduling" -description = "" -keywords = ["Grafana", "oncall", "on-call", "calendar"] -aliases = [] -weight = 100 -+++ - -# About Grafana OnCall scheduling - -You can use any calendar with an iCal address to schedule on-call times for users. During these times, notifications configured in escalation chains with the **Notify users from an on-call schedule** setting will be sent to the the person scheduled. You can also schedule multiple users for overlapping times, and assign prioritization labels for the user that you would like to notify. - -When you create a schedule, you will be able to select a Slack channel, associated with your OnCall account, that will notify users when there are errors or notifications regarding the assigned on-call shifts. \ No newline at end of file diff --git a/docs/sources/calendar-schedules/create-calendar.md b/docs/sources/calendar-schedules/create-calendar.md deleted file mode 100644 index 551d4632..00000000 --- a/docs/sources/calendar-schedules/create-calendar.md +++ /dev/null @@ -1,44 +0,0 @@ -+++ -title = "Create an on-call schedule calendar" -description = "" -keywords = ["Grafana", "oncall", "on-call", "calendar"] -aliases = [] -weight = 300 -+++ - -# Create an on-call schedule calendar - -Create a primary calendar and an optional override calendar to schedule on-call shifts for team members. - -1. In the **Scheduling** section of Grafana OnCall, click **+ Create schedule**. - -1. Give the schedule a name. - -1. Create a new calendar in your calendar service and locate the secret iCal URL. For example, in a Google calendar, this URL can be found in **Settings > Settings for my calendars > Integrate calendar**. - -1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. - The permissions you set when you create the calendar determine who can modify the calendar. - -1. Click **Create Schedule**. - -1. Schedule on-call times for team members. - - Use the Grafana username of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. - -1. Create overlapping schedules (optional). - - When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including a level 9 prioritization, or `[L9]`. - -# Create an override calendar (optional) - -You can use an override calendar to allow team members to schedule on-call duties that will override the primary schedule. An override option allows flexibility without modifying the primary schedule. Events scheduled on the override calendar will always override overlapping events on the primary calendar. - -1. Create a new calendar using the same calendar service you used to create the primary calendar. - - Be sure to set permissions that allow team members to edit the calendar. - -1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. - -1. Click **Edit**. - -1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. \ No newline at end of file diff --git a/docs/sources/chat-options/_index.md b/docs/sources/chat-options/_index.md index fcd147c7..9a4ad687 100644 --- a/docs/sources/chat-options/_index.md +++ b/docs/sources/chat-options/_index.md @@ -1,10 +1,10 @@ +++ -title = "Messaging application configuration" +title = "Connect ChatOps to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "slack"] weight = 700 +++ -# Messaging application configuration +# Connect ChatOps to Grafana OnCall Grafana OnCall directly supports the export of alert notifications to some popular messaging applications like Slack and Telegram. You can use outgoing webhooks to applications that aren't directly supported. For information on configuring outgoing webhooks, see [Send alert group notifications by webhook]({{< relref "../integrations/webhooks/configure-outgoing-webhooks.md" >}}). diff --git a/docs/sources/chat-options/configure-slack.md b/docs/sources/chat-options/configure-slack.md index 447ca25f..0d7e9002 100644 --- a/docs/sources/chat-options/configure-slack.md +++ b/docs/sources/chat-options/configure-slack.md @@ -1,10 +1,10 @@ +++ -title = "Configure Slack for Grafana OnCall" +title = "Connect Slack to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "slack"] weight = 100 +++ -# Configure Slack for Grafana OnCall +# Connect Slack to Grafana OnCall Grafana OnCall integrates closely with your Slack workspace to deliver alert group notifications to individuals, groups, and team members. ## Connect to Slack diff --git a/docs/sources/chat-options/configure-telegram.md b/docs/sources/chat-options/configure-telegram.md index fc30f070..b56104a6 100644 --- a/docs/sources/chat-options/configure-telegram.md +++ b/docs/sources/chat-options/configure-telegram.md @@ -1,10 +1,10 @@ +++ -title = "Configure Telegram for Grafana OnCall" +title = "Connect Telegram to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "telegram"] weight = 300 +++ -# Configure Telegram for Grafana OnCall +# Connect Telegram to Grafana OnCall You can use Telegram to deliver alert group notifications to a dedicated channel, and allow users to perform notification actions. diff --git a/docs/sources/configure-user-settings.md b/docs/sources/configure-user-settings.md index 714c564f..76df57c8 100644 --- a/docs/sources/configure-user-settings.md +++ b/docs/sources/configure-user-settings.md @@ -1,10 +1,10 @@ +++ -title = "Configure user settings" +title = "Manage users and teams for Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 900 +weight = 1100 +++ -# User settings for Grafana OnCall +# Manage users and teams for Grafana OnCall Grafana OnCall is configured based on the teams you've created on the organization level of your Grafana instance, in **Configuration > Teams**. Administrators can create a different configuration for each team, and can navigate between team configurations in the **Select Team** dropdown menu in the **Incidents** section of Grafana OnCall. diff --git a/docs/sources/escalation-policies/_index.md b/docs/sources/escalation-policies/_index.md index 976c9cf3..36e90fe5 100644 --- a/docs/sources/escalation-policies/_index.md +++ b/docs/sources/escalation-policies/_index.md @@ -1,10 +1,10 @@ +++ -title = "Escalation policies" +title = "Escalation Chains and Routes" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] weight = 500 +++ -# Grafana OnCall escalation policies +# Escalation Chains and Routes for Grafana OnCall Administrators can create escalation policies to automatically send alert group notifications to recipients. These policies define how, where, and when to send notifications. diff --git a/docs/sources/escalation-policies/about-escalation-policies.md b/docs/sources/escalation-policies/configure-escalation-chains.md similarity index 94% rename from docs/sources/escalation-policies/about-escalation-policies.md rename to docs/sources/escalation-policies/configure-escalation-chains.md index 509544e5..a0b058f3 100644 --- a/docs/sources/escalation-policies/about-escalation-policies.md +++ b/docs/sources/escalation-policies/configure-escalation-chains.md @@ -1,10 +1,10 @@ +++ -title = "About escalation policies" +title = "Configure and manage Escalation Chains" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] weight = 100 +++ -# About escalation policies +# Configure and manage Escalation Chains Escalation policies dictate how users and groups are notified when an alert notification is created. They can be very simple, or very complex. You can define as many escalation configurations for an integration as you need, and you can send notifications for certain alerts to a designated place when certain conditions are met, or not met. diff --git a/docs/sources/escalation-policies/configure-escalation-policies.md b/docs/sources/escalation-policies/configure-routes.md similarity index 97% rename from docs/sources/escalation-policies/configure-escalation-policies.md rename to docs/sources/escalation-policies/configure-routes.md index aa8cc5e8..855363fb 100644 --- a/docs/sources/escalation-policies/configure-escalation-policies.md +++ b/docs/sources/escalation-policies/configure-routes.md @@ -1,10 +1,10 @@ +++ -title = "Configure escalation policies" +title = "Configure and manage Routes" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] weight = 300 +++ -# Configure escalation policies +# Configure and manage Routes Set up escalation chains and routes to configure escalation behavior for alert group notifications. ## Configure escalation chains diff --git a/docs/sources/configure-notifications.md b/docs/sources/getting-started.md similarity index 98% rename from docs/sources/configure-notifications.md rename to docs/sources/getting-started.md index 04a8141b..97aac06b 100644 --- a/docs/sources/configure-notifications.md +++ b/docs/sources/getting-started.md @@ -1,11 +1,11 @@ +++ title = "Getting started with Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call"] -aliases = ["/docs/grafana-cloud/oncall/configure-notifications"] -draft = true +aliases = ["/docs/grafana-cloud/oncall/getting-started"] +weight = 100 +++ -# Configure users, notifications, and on-call schedules +# Getting started with Grafana OnCall These procedures introduce you to the configuration of user settings, how to set up escalation policies, and how to use your calendar service for on-call scheduling. diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index 199c8fe9..fb14010d 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -1,7 +1,7 @@ +++ title = "Connect to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 100 +weight = 300 aliases = ["/docs/grafana-cloud/oncall/integrations/"] +++ diff --git a/docs/sources/integrations/webhooks/add-webhook-integration.md b/docs/sources/integrations/add-webhook-integration.md similarity index 94% rename from docs/sources/integrations/webhooks/add-webhook-integration.md rename to docs/sources/integrations/add-webhook-integration.md index 9741f276..f3ca39f7 100644 --- a/docs/sources/integrations/webhooks/add-webhook-integration.md +++ b/docs/sources/integrations/add-webhook-integration.md @@ -1,10 +1,10 @@ +++ -title = "Webhook integration" +title = "Webhook integration for Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] -weight = 100 +weight = 700 +++ -# Integrate with your alert source using webhooks +# Webhook integration for Grafana OnCall Grafana OnCall directly supports integrations from many alert sources, but you can connect to any alert source that isn't listed in the **Create Integration** page by using webhooks. diff --git a/docs/sources/integrations/add-integration.md b/docs/sources/integrations/available-integrations /_index.md similarity index 89% rename from docs/sources/integrations/add-integration.md rename to docs/sources/integrations/available-integrations /_index.md index 0a1e5602..99919aae 100644 --- a/docs/sources/integrations/add-integration.md +++ b/docs/sources/integrations/available-integrations /_index.md @@ -1,11 +1,11 @@ +++ -title = "Integrate with alert sources" +title = "Currently available integrations for Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] aliases = ["/docs/grafana-cloud/oncall/integrations/add-integration/"] weight = 100 +++ -# Integrate with alert sources +# Currently available integrations Grafana OnCall can connect directly to the monitoring services of your alert sources listed in the Grafana OnCall **Integrations** section. @@ -20,3 +20,5 @@ Grafana OnCall can connect directly to the monitoring services of your alert sou 1. Configure your integration. Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana as an alert source, select Grafana and follow the instructions. + +{{< section >}} diff --git a/docs/sources/integrations/add-alertmanager.md b/docs/sources/integrations/available-integrations /add-alertmanager.md similarity index 93% rename from docs/sources/integrations/add-alertmanager.md rename to docs/sources/integrations/available-integrations /add-alertmanager.md index bea29cd8..50a094e6 100644 --- a/docs/sources/integrations/add-alertmanager.md +++ b/docs/sources/integrations/available-integrations /add-alertmanager.md @@ -1,11 +1,11 @@ +++ -title = "Configure alert notifications with Alertmanager" +title = "Connect Alert Manager to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] -aliases = ["/docs/grafana-cloud/oncall/integrations/add-alertmanager/"] -weight = 500 +aliases = ["/docs/grafana-cloud/oncall/available-integrations/add-alertmanager/"] +weight = 300 +++ -# Alertmanager (Prometheus) +# Connect Alert manager to Grafana OnCall The Alertmanager integration handles alerts sent by client applications such as the Prometheus server. diff --git a/docs/sources/integrations/add-grafana-alerting.md b/docs/sources/integrations/available-integrations /add-grafana-alerting.md similarity index 97% rename from docs/sources/integrations/add-grafana-alerting.md rename to docs/sources/integrations/available-integrations /add-grafana-alerting.md index 9962786b..fdc0b8bb 100644 --- a/docs/sources/integrations/add-grafana-alerting.md +++ b/docs/sources/integrations/available-integrations /add-grafana-alerting.md @@ -1,8 +1,8 @@ +++ -title = "Configure alert notifications with Grafana Alerting" +title = "Connect Grafana Alerting to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Prometheus"] aliases = ["/docs/grafana-cloud/oncall/integrations/add-grafana-alerting/"] -weight = 300 +weight = 100 +++ # Connect Grafana Alerting to Grafana OnCall diff --git a/docs/sources/integrations/add-zabbix.md b/docs/sources/integrations/available-integrations /add-zabbix.md similarity index 98% rename from docs/sources/integrations/add-zabbix.md rename to docs/sources/integrations/available-integrations /add-zabbix.md index c22c2437..aaaa9913 100644 --- a/docs/sources/integrations/add-zabbix.md +++ b/docs/sources/integrations/available-integrations /add-zabbix.md @@ -1,7 +1,7 @@ +++ -title = "Configure alert notifications with Zabbix" +title = "Connect Zabbix to Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Zabbix"] -weight = 700 +weight = 500 +++ # Connect Zabbix to Grafana OnCall diff --git a/docs/sources/integrations/webhooks/configure-outgoing-webhooks.md b/docs/sources/integrations/configure-outgoing-webhooks.md similarity index 93% rename from docs/sources/integrations/webhooks/configure-outgoing-webhooks.md rename to docs/sources/integrations/configure-outgoing-webhooks.md index 396ca4cd..ef344175 100644 --- a/docs/sources/integrations/webhooks/configure-outgoing-webhooks.md +++ b/docs/sources/integrations/configure-outgoing-webhooks.md @@ -1,10 +1,10 @@ +++ -title = "Send alert notifications by webhook" +title = "Configure outgoing webhooks for Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "webhooks"] weight = 500 +++ -# Send alert group notifications by webhook +# Configure outgoing webhooks for Grafana OnCall You can configure outgoing webhooks to send alerts to destination. Once a webhook is created, you can choose the webhook as a notification method in escalation steps. 1. In Grafana OnCall, navigate to **Outgoing Webhooks** and click **+ Create**. diff --git a/docs/sources/integrations/webhooks/create-custom-templates.md b/docs/sources/integrations/create-custom-templates.md similarity index 98% rename from docs/sources/integrations/webhooks/create-custom-templates.md rename to docs/sources/integrations/create-custom-templates.md index 631119d3..162fd313 100644 --- a/docs/sources/integrations/webhooks/create-custom-templates.md +++ b/docs/sources/integrations/create-custom-templates.md @@ -1,10 +1,10 @@ +++ -title = "Format alerts with templates" +title = "Configure alerts in Grafana OnCall" keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Jinja"] weight = 300 +++ -# Format alerts with templates +# Configure alerts in Grafana OnCall Grafana OnCall works with over one thousand alert monitoring systems. Almost any monitoring system can send alerts using webhooks with JSON payloads. diff --git a/docs/sources/integrations/webhooks/_index.md b/docs/sources/integrations/webhooks/_index.md deleted file mode 100644 index 0a616cd8..00000000 --- a/docs/sources/integrations/webhooks/_index.md +++ /dev/null @@ -1,12 +0,0 @@ -+++ -title = "Use webhooks to send and receive alerts" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] -weight = 900 -+++ - -# Use webhooks to receive alerts -You can use webhooks to send alerts to Grafana OnCall. You can also use custom templates to format your alerts. - -Follow these links to learn more about using webhooks for OnCall alert notifications: - -{{< section >}} diff --git a/docs/sources/manage-alert-groups.md b/docs/sources/manage-alert-groups.md deleted file mode 100644 index 78cb40a7..00000000 --- a/docs/sources/manage-alert-groups.md +++ /dev/null @@ -1,14 +0,0 @@ -+++ -title = "Manage alert groups" -description = "" -keywords = ["Grafana", "oncall", "on-call", "calendar", "incidents", "alert groups"] -weight = 300 -+++ - -# Manage alert groups - -When you create a new alert integration, alerts are sent from the alert monitoring service of that source to Grafana OnCall. When the first alert is sent, the escalation policies you have in place for that integration determine when and where notifications are sent. Alerts will continue to gather until resolved, forming an alert group. For example, if Juan, an administrator, silences a firing alert group, the alerts will continue to collect in that group until the status is **resolved**. Once this occurs, a new alert will begin the next alert group. - -In the **Alert Groups** tab, you can view alert groups by status. Groups are named by the name of the first alert that was fired. When you click on a group, you can view information on all of alerts that have fired, the source of the alerts, and the users assigned in the escalation chain associated with the group. You can also view the timeline of the group, which shows all of the actions associated with the configured escalation policies, and resolution notes. - -Administrators can change the status of individual alert groups, or can select multiple groups to edit at once. Alert group status can be changed in the following ways: `acknowledge`, `resolve`, `unresolve`, `restart`, and `silence`. \ No newline at end of file From 67782050a2ea34eb25f8c7a917788291dd1d31f4 Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Tue, 7 Jun 2022 15:37:27 -0600 Subject: [PATCH 3/9] connect to oncall section in progress --- docs/sources/integrations/_index.md | 79 ++++++++++++++++++- .../integrations/create-custom-templates.md | 56 ++++++------- 2 files changed, 103 insertions(+), 32 deletions(-) diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index fb14010d..07df8c86 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -6,6 +6,83 @@ aliases = ["/docs/grafana-cloud/oncall/integrations/"] +++ # Connect to Grafana OnCall -There are many alert sources that Grafana OnCall directly supports. Those that aren't listed in the integrations menu in OnCall can be connected using webhooks and configured with custom templates. To configure integrations that are directly supported, follow the instructions provided after selecting alert source in the **Integrations** tab in Grafana OnCall. To review general instructions, and also specific integration instructions for some popular integration options, see the following topics: + +Integrations allow you to connect monitoring systems of your choice to send alerts to Grafana OnCall. Regardless of where your alerts originate, you can configure alerts to be sent to Grafana OnCall for alert escalation and notification. Grafana OnCall receives alerts in JSON format via a POST request, OnCall then parses alert data using pre configured alert templates to determine alert grouping, apply routes, and determine correct escalation. + +There are many integrations that are directly supported by Grafana OnCall. Those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. + +## Configure and manage integrations + +You can configure and manage your integrations from the **Integrations** tab in Grafana OnCall. The following sections describe how to configure and customize your integrations to ensure alerts are treated appropriately. + + +### Connect an integration to Grafana OnCall + +To configure an integration for Grafana OnCall: + +1. In Grafana OnCall, navigate to the **Integrations** tab and click **+ New integration for receiving alerts**. +2. Select an integration from the provided options, if the integration you want isn’t listed, then select **Webhook**. +3. Follow the configuration steps on the integration settings page. +4. Complete any necessary configurations in your tool to send alerts to Grafana OnCall. + + +### Manage Grafana OnCall integrations + +To manage existing integrations, navigate to the **Integrations** tab in Grafana OnCall and select the integration you want to manage. + +#### Customize alert templates and grouping + +To customize the alert template for an integration: + +1. Select an integration from your list of enabled integrations in the **Integrations** tab. +2. Click **Change alert template and grouping**. +3. Select a template to edit from the **Edit template for** dropdown menu. +4. Edit alert templates as needed to customize the fields and content rendered for an alert. + +To customize alert grouping for an integration: + +1. Click **Change alert template and grouping**. +2. Select **Alert Behavior** from the dropdown menu next to **Edit template for**. +3. Edit the **grouping id**, **acknowledge condition**, and **resolve condition** templates as needed to customize your alert behavior. + +For more information on alert templates, refer to Configure Alerts in Grafana OnCall (ADD RELREF) + +#### Add Routes + +To add a route to an integration using regular expression: + +1. Select an integration from your list of enabled integrations in the **Integrations** tab. +2. Click **+ Add Route**. +3. Use python style regex to match on your alert content. +4. Click **Create Route**. +5. Select an escalation chain for “**IF** alert payload matches regex” and “**ELSE**” to specify where to route each type of alert. + +To learn more about routes, refer to Configure Routes for Grafana OnCall (ADD RELREF) + + +#### Edit integration name +To edit the name of an integration: + +1. Navigate to the **Integrations** tab, select an integration from the list of enabled integrations. +2. Click the **pencil icon** next to the integration name. +3. Provide a new name and click **Update**. + +#### Delete integration +To delete an integration: + +1. Select an integration from your list of enabled integrations in the **Integrations** tab. +2. Click the **trash can** icon next to the selected integration. +3. Confirm by clicking **Delete**. + + + + + + + + + + + {{< section >}} diff --git a/docs/sources/integrations/create-custom-templates.md b/docs/sources/integrations/create-custom-templates.md index 162fd313..741804e7 100644 --- a/docs/sources/integrations/create-custom-templates.md +++ b/docs/sources/integrations/create-custom-templates.md @@ -6,13 +6,22 @@ weight = 300 # Configure alerts in Grafana OnCall -Grafana OnCall works with over one thousand alert monitoring systems. Almost any monitoring system can send alerts using webhooks with JSON payloads. + Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default preconfigured alert template is applied to modify the alert payload to be more human readable. These alert templates are customizable for any integration. -By default, webhooks will deliver raw JSON. To modify the payload to be more human-readable, you can format your alerts fields that OnCall recognizes. You can use Jinja templates for more advanced customization. +See Format alerts with alert templates in this document to learn more about how to customize alert templates. -## JSON alerting object +## Alert Behavior + +Once Grafana OnCall receives an alert, the following occurs, based on the alert content: + +- Default or customized alert templates are applied to deliver the most useful alert fields with the most valuable information, in a readable format. +- Alerts are grouped based on your alert grouping configurations, combining similar or related alerts to reduce alert noise. +- Alerts automatically resolve if an alert from the monitoring system matches the resolve condition for that alert. + +## Alert payload + +Alerts received by Grafana OnCall contain metadata as keys and values in a JSON object. The following is an example of an alert from Grafana OnCall: -Alerts we receive contain metadata as keys and values in a JSON object. The following is an example of an alert from Grafana: ```json { "dashboardId":1, @@ -38,15 +47,6 @@ Alerts we receive contain metadata as keys and values in a JSON object. The foll } ``` -## The alert payload -Once an alert is received by Grafana OnCall, the following occurs, based on the alert content: - -1. The most useful information is shown in a readable format. - -1. Noise is minimized by grouping alerts, combining similar alerts into a single page. - -1. The alert group is resolved if the monitoring system tells Grafana OnCall to do so. - In Grafana OnCall every alert and alert group has the following fields: - `Title`, `message` and `image url` - `Grouping Id` @@ -62,35 +62,29 @@ The result is that each field of the alert in OnCall is now mapped to the JSON p * `{{ 1 if payload.state == 'OK' else 0 }}` -> Resolve Signal -OnCall has default Jinja templates for the most popular monitoring systems. - -If your monitoring system is not in the Grafana OnCAll integrations list you can create the most generic integration `Webhook`, send an alert, and write your own templates. - -As a best practice, add `_Playbooks_`, `_Useful links_`, or `_Checklists_` to the alert message. +Grafana OnCall provides a pre configured default Jinja template for supported integrations. If your monitoring system is not in the Grafana OnCall integrations list, you can create a generic `webhook` integration, send an alert, and configure your templates. -## How to customize templates +## Customize alerts with alert templates -You can customize the default templates in Grafana OnCall by opening the **Settings** window in either the **Integrations** or **Alert Groups** tab: +Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert templates for all the different ways you receive your alerts such as web, slack, SMS, and email. For more advanced customization, use Jinja templates. -1. From the **Integrations** tab, select the integration, then click the **Settings** (gear) icon. +As a best practice, add _Playbooks_, _Useful links_, or _Checklists_ to the alert message. - +To customize alert templates in Grafana OnCall: -1. From the **Alert Groups** tab, click **Edit rendering, grouping, and other templates** +1. Navigate to the **Integrations** tab, select the integration, then click **Change alert template and grouping**. - - -1. In **Settings**, select the template to edit from **Edit template for**. +2. In Alert Templates, select a template from the **Edit template for** dropdown. -1. Edit the Appearances template as needed: +3. Edit the Appearances template as needed: * `Title`, `Message`, `Image url` for Web * `Title`, `Message`, `Image url` for Slack - * `Title` used in SMS - * `Title` used in Phone - * `Title`, `Message` used in Email + * `Title` used for SMS + * `Title` used for Phone + * `Title`, `Message` used for Email -1. Edit the alert behavior as needed: +4. Edit the alert behavior as needed: * `Grouping Id` - This output groups other alerts into a single alert group. * `Acknowledge Condition` - The output should be `ok`, `true`, or `1` to auto-acknowledge the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. * `Resolve Condition` - The output should be `ok`, `true` or `1` to auto-resolve the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. From 0163ca93653e25910f673b8915244dad03e077b1 Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Wed, 8 Jun 2022 14:10:12 -0600 Subject: [PATCH 4/9] connect to oncall section updates --- docs/sources/integrations/_index.md | 12 +---- .../integrations/add-webhook-integration.md | 41 +++++++++------ .../available-integrations /_index.md | 12 +---- .../add-alertmanager.md | 28 +++++----- .../add-grafana-alerting.md | 52 ++++++++++--------- .../available-integrations /add-zabbix.md | 9 ++-- .../configure-outgoing-webhooks.md | 33 +++++++----- .../integrations/create-custom-templates.md | 2 +- 8 files changed, 97 insertions(+), 92 deletions(-) diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index 07df8c86..a11519ee 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -45,7 +45,8 @@ To customize alert grouping for an integration: 2. Select **Alert Behavior** from the dropdown menu next to **Edit template for**. 3. Edit the **grouping id**, **acknowledge condition**, and **resolve condition** templates as needed to customize your alert behavior. -For more information on alert templates, refer to Configure Alerts in Grafana OnCall (ADD RELREF) +For more information on alert templates, see [Configure alerts in Grafana OnCall]({{< relref " ../create-custom-templates/" >}}) + #### Add Routes @@ -76,13 +77,4 @@ To delete an integration: - - - - - - - - - {{< section >}} diff --git a/docs/sources/integrations/add-webhook-integration.md b/docs/sources/integrations/add-webhook-integration.md index f3ca39f7..ebde152a 100644 --- a/docs/sources/integrations/add-webhook-integration.md +++ b/docs/sources/integrations/add-webhook-integration.md @@ -4,25 +4,33 @@ keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager weight = 700 +++ -# Webhook integration for Grafana OnCall +# Configure Webhook integrations for Grafana OnCall -Grafana OnCall directly supports integrations from many alert sources, but you can connect to any alert source that isn't listed in the **Create Integration** page by using webhooks. +Grafana OnCall directly supports many integrations, those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. -1. In **Integrations**, click **+ New integration for receiving alerts**. -1. Select a webhook format. - There are two available formats. **Webhook** and **Formatted Webhook**. - * **Webhook** will pull all of the raw JSON information and display it in the manner that it is received. - * **Formatted Webhook** can be used if the body of the alerts sent by your monitoring service are formatted in a way that OnCall can read. The following fields are recognized, but none are required: - * `alert_uid`: a unique alert ID for grouping. - * `title`: a title. - * `image_url`: a URL for an image attached to alert. - * `state`: either `ok` or `alerting`. Helpful for auto-resolving. - * `link_to_upstream_details`: link back to your monitoring system. - * `message`: alert details. +With the webhook integration, you can connect to any alert source that isn't listed in the **Create Integration** page. - To learn how to use custom alert templates for formatted webhooks, see [Configure custom alert templates]({{< relref "../create-custom-templates/" >}}). +There are two available formats, **Webhook** and **Formatted Webhook**. -1. Use the unique webhook URL for requests. For example: +* **Webhook** will pull all of the raw JSON payload and display it in the manner that it's received. +* **Formatted Webhook** can be used if the alert payload sent by your monitoring service is formatted in a way that OnCall recognizes. + + The following fields are recognized, but none are required: + * `alert_uid`: a unique alert ID for grouping. + * `title`: a title. + * `image_url`: a URL for an image attached to alert. + * `state`: either `ok` or `alerting`. Helpful for auto-resolving. + * `link_to_upstream_details`: link back to your monitoring system. + * `message`: alert details. + +To configure a webhook integration: + +1. In the **Integrations** tab, click **+ New integration for receiving alerts**. +2. Select either **Webhook** or **Formatted Webhook** integration. +3. Follow the configuration steps in the **How to connect** section of the integration settings. +4. Use the unique webhook URL to complete any configuration in your monitoring service to send POST requests. Use any http client, e.g. curl to send POST requests with any payload. + + For example: ```json curl -X POST \ @@ -37,3 +45,6 @@ Grafana OnCall directly supports integrations from many alert sources, but you c "message": "Smth happened. Oh no!" }' ``` + + +To learn how to use custom alert templates for formatted webhooks, see [Configure alerts in Grafana OnCall]({{< relref "../create-custom-templates/" >}}). \ No newline at end of file diff --git a/docs/sources/integrations/available-integrations /_index.md b/docs/sources/integrations/available-integrations /_index.md index 99919aae..92b5b936 100644 --- a/docs/sources/integrations/available-integrations /_index.md +++ b/docs/sources/integrations/available-integrations /_index.md @@ -7,18 +7,10 @@ weight = 100 # Currently available integrations -Grafana OnCall can connect directly to the monitoring services of your alert sources listed in the Grafana OnCall **Integrations** section. +Grafana OnCall can connect directly to the monitoring services where your alerts originate. All currently available integrations are listed in the Grafana OnCall **Create Integration** section. -1. Connect to alert source with configured alerts. - - In Grafana OnCall, click on the **Integrations** tab and click **+ New integration for receiving alerts**. +The following integrations are currently available for Grafana Cloud OnCall and have documentation: -1. Select an integration from the provided options. - - If you want to use an integration that is not listed, you must use webhooks. To learn more about using webhooks see [Integrate with webhooks]({{< relref "/integrations/webhooks/add-webhook-integration/" >}}). -1. Configure your integration. - - Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana as an alert source, select Grafana and follow the instructions. {{< section >}} diff --git a/docs/sources/integrations/available-integrations /add-alertmanager.md b/docs/sources/integrations/available-integrations /add-alertmanager.md index 50a094e6..2fd195fb 100644 --- a/docs/sources/integrations/available-integrations /add-alertmanager.md +++ b/docs/sources/integrations/available-integrations /add-alertmanager.md @@ -5,25 +5,25 @@ aliases = ["/docs/grafana-cloud/oncall/available-integrations/add-alertmanager/" weight = 300 +++ -# Connect Alert manager to Grafana OnCall +# Connect AlertManager to Grafana OnCall -The Alertmanager integration handles alerts sent by client applications such as the Prometheus server. +The AlertManager integration for Grafana OnCall handles alerts sent by client applications such as the Prometheus server. -Grafana OnCall provides grouping abilities when processing alerts from Alertmanager, including initial deduplicating, grouping, and routing the alerts to Grafana OnCall. +Grafana OnCall provides grouping abilities when processing alerts from Alert Manager, including initial deduplicating, grouping, and routing the alerts to Grafana OnCall. -## Connect Alertmanager to Grafana OnCall +## Configure AlertManager integration for Grafana OnCall -You must have an Admin role to connect to Grafana OnCall. +You must have an Admin role to create integrations in Grafana OnCall. -1. Navigate to the **Integrations** tab in Grafana OnCall. +1. In the **Integrations** tab, click **+ New integration for receiving alerts**. -1. Click on the Alertmanager icon. +2. Select **AlertManager** from the list of available integrations. -1. Follow the instructions that display in the dialog box to find a unique integration URL in the monitoring configuration. +3. Follow the instructions in the **How to connect** window to get your unique integration URL and identify next steps. -## Configure Alertmanager +## Configure AlertManager Update the `receivers` section of your Alertmanager configuration to use a unique integration URL: ``` @@ -38,20 +38,20 @@ receivers: send_resolved: true ``` -## Configure grouping with Alertmanager and Grafana OnCall +## Configure grouping with AlertManager and Grafana OnCall -You can use the grouping mechanics of Alertmanager and Grafana OnCall to configure settings for groups of alert notifications. +You can use the alert grouping mechanics of AlertManager and Grafana OnCall to configure your alert grouping preferences. -Alertmanager offers three grouping settings: +AlertManager offers three alert grouping options: - `group_by` provides two options, `instance` or `job`. - `group_wait` sets the length of time to initially wait before sending a notification for a particular group of alerts. For example, `group_wait` can be set to 45s. - Setting a high value for `group_wait` reduces alert noise and minimizes interruption, but it may introduce longer delays in receiving alert notifications. To set an appropriate wait time, consider whether the group of alerts will be the same as those previously sent. + Setting a high value for `group_wait` reduces alert noise and minimizes interruption, but it may introduce delays in receiving alert notifications. To set an appropriate wait time, consider whether the group of alerts will be the same as those previously sent. - `group_interval` sets the length of time to wait before sending notifications about new alerts that have been added to a group of alerts that have been previously alerted on. This setting is usually set to five minutes or more. - During high alert volume periods, Alertmanager will send alerts at each `group_interval`, which can mean a lot of distraction. Grafana OnCall grouping will help manage this in the following ways: + During high alert volume periods, AlertManager will send alerts at each `group_interval`, which can mean a lot of distraction. Grafana OnCall grouping will help manage this in the following ways: - Grafana OnCall groups alerts based on the first label of each alert. diff --git a/docs/sources/integrations/available-integrations /add-grafana-alerting.md b/docs/sources/integrations/available-integrations /add-grafana-alerting.md index fdc0b8bb..885e9be6 100644 --- a/docs/sources/integrations/available-integrations /add-grafana-alerting.md +++ b/docs/sources/integrations/available-integrations /add-grafana-alerting.md @@ -7,23 +7,24 @@ weight = 100 # Connect Grafana Alerting to Grafana OnCall -You must have the Admin role assigned to connect to Grafana OnCall. - -1. Navigate to the **Integrations** tab in Grafana OnCall. - -1. Click on the Grafana logo. - -1. Follow the instructions that display in the dialog box to find a unique integration URL in the monitoring configuration. - -## Grafana installations - -Grafana OnCall can be set up using two methods: +Grafana Alerting for Grafana OnCall can be set up using two methods: - Grafana Alerting: Grafana OnCall is connected to the same Grafana instance being used to manage Grafana OnCall. -- Grafana (External): Grafana OnCall is connected to one or more Grafana instances separate from the one being used to manage Grafana OnCall. +- Grafana (Other Grafana): Grafana OnCall is connected to one or more Grafana instances separate from the one being used to manage Grafana OnCall. -### Grafana Cloud Alerting +## Configure Grafana Alerting for Grafana OnCall + +You must have an Admin role to create integrations in Grafana OnCall. + +1. In the **Integrations** tab, click **+ New integration for receiving alerts**. + +2. Select **Grafana Alerting** by clicking the **Quick connect** button or select **Grafana (Other Grafana)** from the integrations list. + +3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL and complete any necessary configurations. + + +### Configure Grafana Cloud Alerting Use the following method if you are connecting Grafana OnCall with alerts coming from the same Grafana instance from which Grafana OnCall is being managed. 1. In Grafana OnCall, navigate to the **Integrations** tab and select **New Integration for receiving alerts**. @@ -32,29 +33,30 @@ Use the following method if you are connecting Grafana OnCall with alerts coming >**Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/) -1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new chain. For more information on creating escalation chains, see: [Configure alert notifications with Grafana OnCall]({{< relref "../configure-notifications" >}}).. +1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new escalation chain. -1. In Grafana Cloud Alerting, navigate to **Alerting > Contact Points** and find a contact point with a name matching the integration you created in Grafana OnCall. +2. In Grafana Cloud Alerting, navigate to **Alerting > Contact Points** and find a contact point with a name matching the integration you created in Grafana OnCall. -1. Click the **Edit** (pencil) icon, then click **Test**. This will send an alert to Grafana OnCall. +3. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. -### Grafana (External) +### Configure Grafana (Other Grafana) + +Connect Grafana OnCall with alerts coming from a Grafana instance that is different from the instance that Grafana OnCall is being managed: -Connect Grafana OnCall with alerts coming from an instance of Grafana different from the one on which Grafana OnCall is being managed: 1. In Grafana OnCall, navigate to the **Integrations** tab and select **New Integration for receiving alerts**. -1. Select the **Grafana** tile. +2. Select the **Grafana (Other Grafana)** tile. -1. View and save the URL needed to connect. +3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL and complete any necessary configurations. -1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new chain. For more information on creating escalation chains, see: [Configure alert notifications with Grafana OnCall]({{< relref "../configure-notifications/" >}}). +4. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new escalation chain. -1. Go to the other Grafana instance to connect to Grafana OnCall and navigate to **Alerting > Contact Points**. +5. Go to the other Grafana instance to connect to Grafana OnCall and navigate to **Alerting > Contact Points**. -1. Select **New Contact Point**. +6. Select **New Contact Point**. -1. Choose the contact point type `webhook`, then paste the URL generated in step 3 into the URL field. +7. Choose the contact point type `webhook`, then paste the URL generated in step 3 into the URL field. >**Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/). -1. Click the **Edit** (pencil) icon, then click **Test**. This will send an alert to Grafana OnCall. \ No newline at end of file +8. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. \ No newline at end of file diff --git a/docs/sources/integrations/available-integrations /add-zabbix.md b/docs/sources/integrations/available-integrations /add-zabbix.md index aaaa9913..46645bbd 100644 --- a/docs/sources/integrations/available-integrations /add-zabbix.md +++ b/docs/sources/integrations/available-integrations /add-zabbix.md @@ -8,11 +8,14 @@ weight = 500 Zabbix is an open-source monitoring software tool for diverse IT components, including networks, servers, virtual machines, and cloud services. Zabbix provides monitoring for metrics such as network utilization, CPU load, and disk space consumption. -To connect Grafana OnCall with Zabbix using the following procedure, you must have an Admin role assigned. -1. Navigate to the **Integrations** tab in Grafana OnCall. +## Configure Zabbix integration for Grafana OnCall -1. Follow the instructions that display in the dialog box to use a unique integration URL in the monitoring configuration. +You must have an Admin role to create integrations in Grafana OnCall. + +1. In the **Integrations** tab, click **+ New integration for receiving alerts**. +2. Select **Zabbix** from the list of available integrations +3. Follow the instructions in the **How to connect** window to get your unique integration URL and review next steps. diff --git a/docs/sources/integrations/configure-outgoing-webhooks.md b/docs/sources/integrations/configure-outgoing-webhooks.md index ef344175..4a0b56ab 100644 --- a/docs/sources/integrations/configure-outgoing-webhooks.md +++ b/docs/sources/integrations/configure-outgoing-webhooks.md @@ -5,27 +5,33 @@ weight = 500 +++ # Configure outgoing webhooks for Grafana OnCall -You can configure outgoing webhooks to send alerts to destination. Once a webhook is created, you can choose the webhook as a notification method in escalation steps. +Outgoing webhooks allow you to send alert details to a specified URL from Grafana OnCall. Once an outgoing webhook is configured, you can use it as a notification method in escalation chains. + + +To automatically send alert data to a destination URL via outgoing webhook: 1. In Grafana OnCall, navigate to **Outgoing Webhooks** and click **+ Create**. - This is also the place to edit and delete existing webhooks. + This is also the place to edit and delete existing outgoing webhooks. -1. Name your webhook and enter the destination URL. +2. Provide a name for your outgoing webhook and enter the destination URL. -1. If the destination requires authentication, enter your credentials. +3. If the destination requires authentication, enter your credentials. You can enter a username and password (HTTP) or an authorization header formatted in JSON. -1. Configure the webhook payload in the **Data** field. - You can use four variables to automate the body of your webhook. The format you use to call the variables must match the structure of how the fields are nested in your alert payload. The **Data** field can use the following four variables to auto-populate the webhook payload with information about the first alert in the alert group: - - `{{ alert_title }}` - - `{{ alert_message }}` - - `{{ alert_url }}` - - `{{ alert_payload }}` +4. Configure the webhook payload in the **Data** field. + +5. Click **Create Webhook**. + +The format you use to call the variables must match the structure of how the fields are nested in the alert payload. The **Data** field can use the following four variables to auto-populate the webhook payload with information about the first alert in the alert group: +- `{{ alert_title }}` +- `{{ alert_message }}` +- `{{ alert_url }}` +- `{{ alert_payload }}`
- `alert_payload` is always the first level of any variable you want to call. +`alert_payload` is always the first level of any variable you want to call. - The following is an example of an entry in the **Data** field that might return an alert name and description. +The following is an example of an entry in the **Data** field that might return an alert name and description. ```json { @@ -34,6 +40,5 @@ You can configure outgoing webhooks to send alerts to destination. Once a webhoo } ``` - >**NOTE:** If you get an error message and cannot create a webhook, make sure your JSON is formatted correctly. +>**NOTE:** If you receive an error message and cannot create an outgoing webhook, verify that your JSON is formatted correctly. -1. Click **Create Webhook**. \ No newline at end of file diff --git a/docs/sources/integrations/create-custom-templates.md b/docs/sources/integrations/create-custom-templates.md index 741804e7..9d2add94 100644 --- a/docs/sources/integrations/create-custom-templates.md +++ b/docs/sources/integrations/create-custom-templates.md @@ -6,7 +6,7 @@ weight = 300 # Configure alerts in Grafana OnCall - Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default preconfigured alert template is applied to modify the alert payload to be more human readable. These alert templates are customizable for any integration. + Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default pre configured alert template is applied to modify the alert payload to be more human readable. These alert templates are customizable for any integration. See Format alerts with alert templates in this document to learn more about how to customize alert templates. From a0784346c1de50e4e4219ea96060332c875ea3f8 Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Wed, 8 Jun 2022 15:40:53 -0600 Subject: [PATCH 5/9] relrefs and minor edits --- docs/sources/integrations/_index.md | 4 ++-- docs/sources/integrations/available-integrations /_index.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index a11519ee..ba58b183 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -7,7 +7,7 @@ aliases = ["/docs/grafana-cloud/oncall/integrations/"] # Connect to Grafana OnCall -Integrations allow you to connect monitoring systems of your choice to send alerts to Grafana OnCall. Regardless of where your alerts originate, you can configure alerts to be sent to Grafana OnCall for alert escalation and notification. Grafana OnCall receives alerts in JSON format via a POST request, OnCall then parses alert data using pre configured alert templates to determine alert grouping, apply routes, and determine correct escalation. +Integrations allow you to connect monitoring systems of your choice to send alerts to Grafana OnCall. Regardless of where your alerts originate, you can configure alerts to be sent to Grafana OnCall for alert escalation and notification. Grafana OnCall receives alerts in JSON format via a POST request, OnCall then parses alert data using preconfigured alert templates to determine alert grouping, apply routes, and determine correct escalation. There are many integrations that are directly supported by Grafana OnCall. Those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. @@ -58,7 +58,7 @@ To add a route to an integration using regular expression: 4. Click **Create Route**. 5. Select an escalation chain for “**IF** alert payload matches regex” and “**ELSE**” to specify where to route each type of alert. -To learn more about routes, refer to Configure Routes for Grafana OnCall (ADD RELREF) +To learn more about routes, refer to [Configure and manage Routes]({{< relref " ../configure-routes/" >}}) #### Edit integration name diff --git a/docs/sources/integrations/available-integrations /_index.md b/docs/sources/integrations/available-integrations /_index.md index 92b5b936..ea29806c 100644 --- a/docs/sources/integrations/available-integrations /_index.md +++ b/docs/sources/integrations/available-integrations /_index.md @@ -9,6 +9,8 @@ weight = 100 Grafana OnCall can connect directly to the monitoring services where your alerts originate. All currently available integrations are listed in the Grafana OnCall **Create Integration** section. +If the integration you're looking for isn't currently listed, see [Configure Webhook integrations for Grafana OnCall]({{< relref " ../add-webhook-integration/" >}}) to integration your monitoring system with Grafana OnCall. + The following integrations are currently available for Grafana Cloud OnCall and have documentation: From f8a178d903341ca307b2a758b9e953dd7c8f072a Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Wed, 8 Jun 2022 16:05:30 -0600 Subject: [PATCH 6/9] added notes for cloud only integrations --- docs/sources/integrations/available-integrations /_index.md | 5 ++++- .../integrations/available-integrations /add-zabbix.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/sources/integrations/available-integrations /_index.md b/docs/sources/integrations/available-integrations /_index.md index ea29806c..6898f87a 100644 --- a/docs/sources/integrations/available-integrations /_index.md +++ b/docs/sources/integrations/available-integrations /_index.md @@ -11,7 +11,10 @@ Grafana OnCall can connect directly to the monitoring services where your alerts If the integration you're looking for isn't currently listed, see [Configure Webhook integrations for Grafana OnCall]({{< relref " ../add-webhook-integration/" >}}) to integration your monitoring system with Grafana OnCall. -The following integrations are currently available for Grafana Cloud OnCall and have documentation: +>**Note:** Some integrations are available for Grafana Cloud instances only. See individual integration guides for more information. + + +The following integrations are currently available for Grafana OnCall and have documentation: diff --git a/docs/sources/integrations/available-integrations /add-zabbix.md b/docs/sources/integrations/available-integrations /add-zabbix.md index 46645bbd..26b04f65 100644 --- a/docs/sources/integrations/available-integrations /add-zabbix.md +++ b/docs/sources/integrations/available-integrations /add-zabbix.md @@ -11,7 +11,7 @@ Zabbix is an open-source monitoring software tool for diverse IT components, inc ## Configure Zabbix integration for Grafana OnCall -You must have an Admin role to create integrations in Grafana OnCall. +This integration is available for Grafana Cloud OnCall. You must have an Admin role to create integrations in Grafana OnCall. 1. In the **Integrations** tab, click **+ New integration for receiving alerts**. 2. Select **Zabbix** from the list of available integrations From 95b6ad9f926b3f9114a1d2b3750f89e2e3706316 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Thu, 9 Jun 2022 10:08:07 +0100 Subject: [PATCH 7/9] Convert front matter to YAML and add current aliases to all pages Signed-off-by: Jack Baldry --- docs/sources/_index.md | 23 +- docs/sources/calendar-schedules/_index.md | 41 +- docs/sources/chat-options/_index.md | 23 +- docs/sources/chat-options/configure-slack.md | 33 +- .../chat-options/configure-telegram.md | 39 +- docs/sources/configure-user-settings.md | 47 ++- docs/sources/escalation-policies/_index.md | 21 +- .../configure-escalation-chains.md | 32 +- .../escalation-policies/configure-routes.md | 55 +-- docs/sources/getting-started.md | 106 +++--- docs/sources/integrations/_index.md | 45 ++- .../integrations/add-webhook-integration.md | 52 +-- .../available-integrations /_index.md | 27 +- .../add-alertmanager.md | 31 +- .../add-grafana-alerting.md | 37 +- .../available-integrations /add-zabbix.md | 101 ++--- .../configure-outgoing-webhooks.md | 39 +- .../integrations/create-custom-templates.md | 125 ++++--- docs/sources/oncall-api-reference/_index.md | 41 +- .../oncall-api-reference/alertgroups.md | 60 +-- docs/sources/oncall-api-reference/alerts.md | 180 ++++----- .../oncall-api-reference/escalation_chains.md | 56 +-- .../escalation_policies.md | 106 +++--- .../oncall-api-reference/integrations.md | 351 +++++++++--------- .../oncall-api-reference/on_call_shifts.md | 190 +++++----- .../oncall-api-reference/outgoing_webhooks.md | 34 +- .../personal_notification_rules.md | 128 +++---- .../postmortem_messages.md | 83 +++-- .../oncall-api-reference/postmortems.md | 102 ++--- docs/sources/oncall-api-reference/routes.md | 147 ++++---- .../sources/oncall-api-reference/schedules.md | 181 +++++---- .../oncall-api-reference/slack_channels.md | 36 +- .../oncall-api-reference/user_groups.md | 55 +-- docs/sources/oncall-api-reference/users.md | 86 ++--- 34 files changed, 1438 insertions(+), 1275 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index ec446b6f..e2b19d95 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -1,9 +1,18 @@ -+++ -title = "Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "OnCall", "irm"] -weight = 1000 -aliases = ["/docs/grafana-cloud/oncall/"] -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/ + - /docs/oncall/latest/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - OnCall + - irm +title: Grafana OnCall +weight: 1000 +--- # Grafana OnCall @@ -13,4 +22,4 @@ When you integrate an alert monitoring system with Grafana OnCall, the alerts wi Follow these links to learn more: -{{< section >}} \ No newline at end of file +{{< section >}} diff --git a/docs/sources/calendar-schedules/_index.md b/docs/sources/calendar-schedules/_index.md index 3b322720..7dff67a0 100644 --- a/docs/sources/calendar-schedules/_index.md +++ b/docs/sources/calendar-schedules/_index.md @@ -1,10 +1,15 @@ -+++ -title = "Configure and manage on-call schedules" -description = "" -keywords = ["Grafana", "oncall", "on-call", "calendar"] -aliases = [] -weight = 900 -+++ +--- +aliases: + - /docs/oncall/latest/calendar-schedules/ +description: "" +keywords: + - Grafana + - oncall + - on-call + - calendar +title: Configure and manage on-call schedules +weight: 900 +--- # Configure and manage on-call schedules @@ -20,26 +25,26 @@ When you create a schedule, you will be able to select a Slack channel, associat ## Create an on-call schedule calendar -Create a primary calendar and an optional override calendar to schedule on-call shifts for team members. +Create a primary calendar and an optional override calendar to schedule on-call shifts for team members. 1. In the **Scheduling** section of Grafana OnCall, click **+ Create schedule**. -1. Give the schedule a name. +1. Give the schedule a name. 1. Create a new calendar in your calendar service and locate the secret iCal URL. For example, in a Google calendar, this URL can be found in **Settings > Settings for my calendars > Integrate calendar**. -1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. - The permissions you set when you create the calendar determine who can modify the calendar. +1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. + The permissions you set when you create the calendar determine who can modify the calendar. 1. Click **Create Schedule**. 1. Schedule on-call times for team members. - Use the Grafana username of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. + Use the Grafana username of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. -1. Create overlapping schedules (optional). +1. Create overlapping schedules (optional). - When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including a level 9 prioritization, or `[L9]`. + When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including a level 9 prioritization, or `[L9]`. # Create an override calendar (optional) @@ -47,10 +52,10 @@ You can use an override calendar to allow team members to schedule on-call dutie 1. Create a new calendar using the same calendar service you used to create the primary calendar. - Be sure to set permissions that allow team members to edit the calendar. + Be sure to set permissions that allow team members to edit the calendar. -1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. +1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. -1. Click **Edit**. +1. Click **Edit**. -1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. \ No newline at end of file +1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. diff --git a/docs/sources/chat-options/_index.md b/docs/sources/chat-options/_index.md index 9a4ad687..324356d3 100644 --- a/docs/sources/chat-options/_index.md +++ b/docs/sources/chat-options/_index.md @@ -1,13 +1,22 @@ -+++ -title = "Connect ChatOps to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "slack"] -weight = 700 -+++ +--- +aliases: + - /docs/oncall/latest/chat-options/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - slack +title: Connect ChatOps to Grafana OnCall +weight: 700 +--- -# Connect ChatOps to Grafana OnCall +# Connect ChatOps to Grafana OnCall Grafana OnCall directly supports the export of alert notifications to some popular messaging applications like Slack and Telegram. You can use outgoing webhooks to applications that aren't directly supported. For information on configuring outgoing webhooks, see [Send alert group notifications by webhook]({{< relref "../integrations/webhooks/configure-outgoing-webhooks.md" >}}). To configure supported messaging apps, see the following topics: -{{< section >}} \ No newline at end of file +{{< section >}} diff --git a/docs/sources/chat-options/configure-slack.md b/docs/sources/chat-options/configure-slack.md index 0d7e9002..5b330838 100644 --- a/docs/sources/chat-options/configure-slack.md +++ b/docs/sources/chat-options/configure-slack.md @@ -1,20 +1,30 @@ -+++ -title = "Connect Slack to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "slack"] -weight = 100 -+++ +--- +aliases: + - /docs/oncall/latest/chat-options/configure-slack/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - slack +title: Connect Slack to Grafana OnCall +weight: 100 +--- # Connect Slack to Grafana OnCall -Grafana OnCall integrates closely with your Slack workspace to deliver alert group notifications to individuals, groups, and team members. + +Grafana OnCall integrates closely with your Slack workspace to deliver alert group notifications to individuals, groups, and team members. ## Connect to Slack Connect your organization's Slack workspace to your Grafana OnCall instance. ->**NOTE:** Only Grafana users with the administrator role can configure OnCall settings. +> **NOTE:** Only Grafana users with the administrator role can configure OnCall settings. 1. In OnCall, click on the **ChatOps** tab and select Slack in the side menu. -1. Click **Install Slack integration**. +1. Click **Install Slack integration**. 1. Read the notice and click the button to proceed to the Slack website. 1. Sign in to your organization's workspace. 1. Click **Allow** to allow OnCall to access Slack. @@ -22,12 +32,13 @@ Connect your organization's Slack workspace to your Grafana OnCall instance. ## Configure Slack in OnCall -In the Slack settings for Grafana OnCall, administrators can set a default Slack channel for notifications and opt to set reminders for acknowledged alerts that can timeout and revert an alert group to the unacknowledged state. +In the Slack settings for Grafana OnCall, administrators can set a default Slack channel for notifications and opt to set reminders for acknowledged alerts that can timeout and revert an alert group to the unacknowledged state. 1. In OnCall, click on the **ChatOps** tab and select Slack in the side menu. 1. In the first dropdown menu, select a default Slack channel. - When you set up escalation policies to notify Slack channels of incoming alerts, the default will be the one you set here. You will still have the option to select from all the channels available in your organization. + When you set up escalation policies to notify Slack channels of incoming alerts, the default will be the one you set here. You will still have the option to select from all the channels available in your organization. 1. In **Additional settings** you can choose how to remind users of acknowledged but unresolved alert groups. You can also select whether and or when to automatically revoke the "acknowledged" status from an alert group to an unacknowledged state. ## Slack settings for on-call calendar scheduling notifications -Admins can configure settings in Slack to notify people and groups about on-call schedules. When an on-call shift notification is sent to a person or channel, click the gear button to access **Notification preferences**. Use the options to configure the behavior of future shift notifications. \ No newline at end of file + +Admins can configure settings in Slack to notify people and groups about on-call schedules. When an on-call shift notification is sent to a person or channel, click the gear button to access **Notification preferences**. Use the options to configure the behavior of future shift notifications. diff --git a/docs/sources/chat-options/configure-telegram.md b/docs/sources/chat-options/configure-telegram.md index b56104a6..ec6128eb 100644 --- a/docs/sources/chat-options/configure-telegram.md +++ b/docs/sources/chat-options/configure-telegram.md @@ -1,12 +1,21 @@ -+++ -title = "Connect Telegram to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "telegram"] -weight = 300 -+++ +--- +aliases: + - /docs/oncall/latest/chat-options/configure-telegram/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - telegram +title: Connect Telegram to Grafana OnCall +weight: 300 +--- # Connect Telegram to Grafana OnCall -You can use Telegram to deliver alert group notifications to a dedicated channel, and allow users to perform notification actions. +You can use Telegram to deliver alert group notifications to a dedicated channel, and allow users to perform notification actions. Each alert group notification is assigned a dedicated discussion. Users can perform notification actions (acknowledge, resolve, silence), create reports, and discuss alerts in the comments section of the discussions. @@ -14,19 +23,19 @@ Each alert group notification is assigned a dedicated discussion. Users can perf Connect your organization's Telegram account to your Grafana OnCall instance by following the instructions provided in OnCall. You can use the following steps as a reference. ->**NOTE:** Only Grafana users with the administrator role can configure OnCall settings. +> **NOTE:** Only Grafana users with the administrator role can configure OnCall settings. 1. In OnCall, click on the **ChatOps** tab and select Telegram in the side menu. 1. Click **Connect Telegram channel** and follow the instructions, mirrored here for reference. A unique verification code will be generated that you must use to activate the channel. -1. In your team Telegram account, create a new channel, and set it to **Private**. +1. In your team Telegram account, create a new channel, and set it to **Private**. 1. In **Manage Channel**, make sure **Sign messages** is enabled. 1. Create a new discussion group. - This group handles alert actions and comments. -1. Add the discussion group to the channel. - In **Manage Channel**, click **Discussion** to find and add the new group. -1. In OnCall, click the link to the OnCall bot to add it to your contacts. -1. In Telegram, add the bot to your channel as an Admin. Allow it to **Post Messages**. -1. Add the bot to the discussion group. + This group handles alert actions and comments. +1. Add the discussion group to the channel. + In **Manage Channel**, click **Discussion** to find and add the new group. +1. In OnCall, click the link to the OnCall bot to add it to your contacts. +1. In Telegram, add the bot to your channel as an Admin. Allow it to **Post Messages**. +1. Add the bot to the discussion group. 1. In OnCall, send the provided verification code to the channel. 1. Make sure users connect to Telegram in their OnCall user profile. @@ -36,4 +45,4 @@ Connect your organization's Telegram account to your Grafana OnCall instance by 1. Click **Connect automatically** for the bot to message you and to bring up your telegram account. 1. Click **Start** when the OnCall bot messages you. -If you want to connect manually, you can click the URL provided and then **SEND MESSAGE**. In your Telegram account, click **Start**. \ No newline at end of file +If you want to connect manually, you can click the URL provided and then **SEND MESSAGE**. In your Telegram account, click **Start**. diff --git a/docs/sources/configure-user-settings.md b/docs/sources/configure-user-settings.md index 76df57c8..7654c795 100644 --- a/docs/sources/configure-user-settings.md +++ b/docs/sources/configure-user-settings.md @@ -1,38 +1,47 @@ -+++ -title = "Manage users and teams for Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 1100 -+++ +--- +aliases: + - /docs/oncall/latest/configure-user-settings/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - integrations +title: Manage users and teams for Grafana OnCall +weight: 1100 +--- # Manage users and teams for Grafana OnCall -Grafana OnCall is configured based on the teams you've created on the organization level of your Grafana instance, in **Configuration > Teams**. Administrators can create a different configuration for each team, and can navigate between team configurations in the **Select Team** dropdown menu in the **Incidents** section of Grafana OnCall. +Grafana OnCall is configured based on the teams you've created on the organization level of your Grafana instance, in **Configuration > Teams**. Administrators can create a different configuration for each team, and can navigate between team configurations in the **Select Team** dropdown menu in the **Incidents** section of Grafana OnCall. Users can edit their contact information, but user permissions are assigned at the Cloud portal level. ## Configure user notification policies -Administrators can configure how each user will receive notifications when they are are scheduled to receive them in escalation chains. Users can verify phone numbers and email addresses. +Administrators can configure how each user will receive notifications when they are are scheduled to receive them in escalation chains. Users can verify phone numbers and email addresses. ->**NOTE**: You cannot add users or manage permissions in Grafana OnCall. Most user settings are found on the organizational level of your Grafana instance in **Configuration > Users**. +> **NOTE**: You cannot add users or manage permissions in Grafana OnCall. Most user settings are found on the organizational level of your Grafana instance in **Configuration > Users**. 1. Find users. - - Select the **Users** tab and use the browser to search for a user in the team associated with the OnCall configuration. + + Select the **Users** tab and use the browser to search for a user in the team associated with the OnCall configuration. 1. Configure user settings. - Add and verify a phone number, a Slack username, and a Telegram account if you want to receive notifications using these mediums. + Add and verify a phone number, a Slack username, and a Telegram account if you want to receive notifications using these mediums. - >**NOTE:** To edit a user's profile username, email, or role, you must do so in the **Users** tab in the **Configuration** menu of your Grafana instance. + > **NOTE:** To edit a user's profile username, email, or role, you must do so in the **Users** tab in the **Configuration** menu of your Grafana instance. 1. Configure notification settings. - - Specify the notification medium and frequency for each user. Notification steps will be followed in the order they are listed. - - The settings you specify in **Default Notifications** dictate how a user is notified for most escalation thresholds. - - **Important Notifications** are labeled in escalation chains. If an escalation event is marked as an important notification, it will bypass **Default Notification** settings and notify the user by the method specified. + + Specify the notification medium and frequency for each user. Notification steps will be followed in the order they are listed. + + The settings you specify in **Default Notifications** dictate how a user is notified for most escalation thresholds. + + **Important Notifications** are labeled in escalation chains. If an escalation event is marked as an important notification, it will bypass **Default Notification** settings and notify the user by the method specified. ## Configure Telegram user settings in OnCall @@ -45,4 +54,4 @@ If you want to connect manually, you can click the URL provided and then **SEND ## Configure Slack user settings in OnCall 1. In your profile, find the Slack setting and click **Connect**. -1. Follow the instructions to verify your account. \ No newline at end of file +1. Follow the instructions to verify your account. diff --git a/docs/sources/escalation-policies/_index.md b/docs/sources/escalation-policies/_index.md index 36e90fe5..0919df7c 100644 --- a/docs/sources/escalation-policies/_index.md +++ b/docs/sources/escalation-policies/_index.md @@ -1,8 +1,17 @@ -+++ -title = "Escalation Chains and Routes" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 500 -+++ +--- +aliases: + - /docs/oncall/latest/escalation-policies/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - integrations +title: Escalation Chains and Routes +weight: 500 +--- # Escalation Chains and Routes for Grafana OnCall @@ -10,4 +19,4 @@ Administrators can create escalation policies to automatically send alert group See the following topics for more information: -{{< section >}} \ No newline at end of file +{{< section >}} diff --git a/docs/sources/escalation-policies/configure-escalation-chains.md b/docs/sources/escalation-policies/configure-escalation-chains.md index a0b058f3..9430dd24 100644 --- a/docs/sources/escalation-policies/configure-escalation-chains.md +++ b/docs/sources/escalation-policies/configure-escalation-chains.md @@ -1,22 +1,34 @@ -+++ -title = "Configure and manage Escalation Chains" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 100 -+++ +--- +aliases: + - /docs/oncall/latest/escalation-policies/configure-escalation-chains/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - integrations +title: Configure and manage Escalation Chains +weight: 100 +--- # Configure and manage Escalation Chains -Escalation policies dictate how users and groups are notified when an alert notification is created. They can be very simple, or very complex. You can define as many escalation configurations for an integration as you need, and you can send notifications for certain alerts to a designated place when certain conditions are met, or not met. +Escalation policies dictate how users and groups are notified when an alert notification is created. They can be very simple, or very complex. You can define as many escalation configurations for an integration as you need, and you can send notifications for certain alerts to a designated place when certain conditions are met, or not met. Escalation policies have three main parts: -* User settings, where a user sets up their preferred or required notification method. -* An **escalation chain**, which can have one or more steps that are followed in order when a notification is triggered. -* A **route**, that allows administrators to manage notifications by flagging expressions in an alert payload. + +- User settings, where a user sets up their preferred or required notification method. +- An **escalation chain**, which can have one or more steps that are followed in order when a notification is triggered. +- A **route**, that allows administrators to manage notifications by flagging expressions in an alert payload. ## Escalation chains + An escalation chain can have many steps, or only one step. For example, steps can be configured to notify multiple users in some order, notify users that are scheduled for on-call shifts, ping groups in Slack, use outgoing webhooks to integrate with other services, such as JIRA, and do a number of other automated notification tasks. ## Routes + An escalation workflow can employ **routes** that administrators can configure to filter alerts by regular expressions in their payloads. Notifications for these alerts can be sent to individuals, or they can make use of a new or existing escalation chain. -To learn how to configure escalation chains and routes, see [Configure escalation policies]({{< relref "configure-escalation-policies">}}). \ No newline at end of file +To learn how to configure escalation chains and routes, see [Configure escalation policies]({{< relref "configure-escalation-policies">}}). diff --git a/docs/sources/escalation-policies/configure-routes.md b/docs/sources/escalation-policies/configure-routes.md index 855363fb..18666e4c 100644 --- a/docs/sources/escalation-policies/configure-routes.md +++ b/docs/sources/escalation-policies/configure-routes.md @@ -1,42 +1,53 @@ -+++ -title = "Configure and manage Routes" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 300 -+++ +--- +aliases: + - /docs/oncall/latest/escalation-policies/configure-routes/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - integrations +title: Configure and manage Routes +weight: 300 +--- # Configure and manage Routes -Set up escalation chains and routes to configure escalation behavior for alert group notifications. + +Set up escalation chains and routes to configure escalation behavior for alert group notifications. ## Configure escalation chains -You can create and edit escalation chains in two places: within **Integrations**, by clicking on an integration tile, and in **Escalation Chains**. The following steps are for the **Integrations** workflow, but are generally applicable in both situations. -You can use **escalation chains** and **routes** to determine ordered escalation procedures. Escalation chains allow you to set up a series of alert group notification actions that trigger if certain conditions that you specify are met or not met. +You can create and edit escalation chains in two places: within **Integrations**, by clicking on an integration tile, and in **Escalation Chains**. The following steps are for the **Integrations** workflow, but are generally applicable in both situations. + +You can use **escalation chains** and **routes** to determine ordered escalation procedures. Escalation chains allow you to set up a series of alert group notification actions that trigger if certain conditions that you specify are met or not met. 1. Click on the integration tile for which you want to define escalation policies. - - The **Escalations** section for the notification is in the pane to the right of the list of notifications. - You can click **Change alert template and grouping** to customize the look of the alert. You can also do this by clicking the **Settings** (gear) icon in the integration tile. + + The **Escalations** section for the notification is in the pane to the right of the list of notifications. + You can click **Change alert template and grouping** to customize the look of the alert. You can also do this by clicking the **Settings** (gear) icon in the integration tile. 1. Create an escalation chain. - - In the escalation pane, click **Escalate to** to choose from previously added escalation chains, or create a new one by clicking **Make a copy** or **Create a new chain**. This will be the name of the escalation policy you define. + + In the escalation pane, click **Escalate to** to choose from previously added escalation chains, or create a new one by clicking **Make a copy** or **Create a new chain**. This will be the name of the escalation policy you define. 1. Add escalation steps. - Click **Add escalation step** to choose from a set of actions and specify their triggering conditions. By default, the first step is to notify a slack channel or user. Specify users or channels or toggle the switch to turn this step off. + Click **Add escalation step** to choose from a set of actions and specify their triggering conditions. By default, the first step is to notify a slack channel or user. Specify users or channels or toggle the switch to turn this step off. - To mark an escalation as **Important**, select the option from the step **Start** dropdown menu. User notification policies can be separately defined for **Important** and **Default** escalations. + To mark an escalation as **Important**, select the option from the step **Start** dropdown menu. User notification policies can be separately defined for **Important** and **Default** escalations. ## Create a route -To add a route, click **Add Route**. - -You can set up a single route and specify notification escalation steps, or you can add multiple routes, each with its own configuration. +To add a route, click **Add Route**. -Each route added to an escalation policy follows an `IF`, `ELSE IF`, or `ELSE` path and depends on the type of alert you specify using a regular expression that matches content in the payload body of the alert. You can also specify where to send the notification for each route. - -For example, you can send notifications for alerts with `\"severity\": \"critical\"` in the payload to an escalation chain called `Bob_OnCall`. You can create a different route for alerts with the payload `\"namespace\" *: *\"synthetic-monitoring-dev-.*\"` and select a escalation chain called `NotifySecurity`. +You can set up a single route and specify notification escalation steps, or you can add multiple routes, each with its own configuration. + +Each route added to an escalation policy follows an `IF`, `ELSE IF`, or `ELSE` path and depends on the type of alert you specify using a regular expression that matches content in the payload body of the alert. You can also specify where to send the notification for each route. + +For example, you can send notifications for alerts with `\"severity\": \"critical\"` in the payload to an escalation chain called `Bob_OnCall`. You can create a different route for alerts with the payload `\"namespace\" *: *\"synthetic-monitoring-dev-.*\"` and select a escalation chain called `NotifySecurity`. You can set up escalation steps for each route in a chain. ->**NOTE:** When you modify an escalation chain or a route, it will modify that escalation chain across all integrations that use it. \ No newline at end of file +> **NOTE:** When you modify an escalation chain or a route, it will modify that escalation chain across all integrations that use it. diff --git a/docs/sources/getting-started.md b/docs/sources/getting-started.md index 97aac06b..336058ff 100644 --- a/docs/sources/getting-started.md +++ b/docs/sources/getting-started.md @@ -1,110 +1,116 @@ -+++ -title = "Getting started with Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call"] -aliases = ["/docs/grafana-cloud/oncall/getting-started"] -weight = 100 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/getting-started/ + - /docs/oncall/latest/getting-started/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call +title: Getting started with Grafana OnCall +weight: 100 +--- # Getting started with Grafana OnCall -These procedures introduce you to the configuration of user settings, how to set up escalation policies, and how to use your calendar service for on-call scheduling. +These procedures introduce you to the configuration of user settings, how to set up escalation policies, and how to use your calendar service for on-call scheduling. -## Before you begin +## Before you begin -You must have a Grafana Cloud account. +You must have a Grafana Cloud account. -Each supported integration and the associated monitoring system has a slightly different configuration method. These methods will not be explained in this guide, however, you can follow the online instructions provided when adding an integration. +Each supported integration and the associated monitoring system has a slightly different configuration method. These methods will not be explained in this guide, however, you can follow the online instructions provided when adding an integration. ## Configure user notification policies -You can configure how each user will receive notifications when they are assigned in escalation policies. +You can configure how each user will receive notifications when they are assigned in escalation policies. 1. Find users. - - Select the **Users** tab and use the browser to search for a user in your organization. + + Select the **Users** tab and use the browser to search for a user in your organization. 1. Configure user settings. - Add and verify a phone number and a Slack username if you want to deliver notifications using these mediums. -
+ Add and verify a phone number and a Slack username if you want to deliver notifications using these mediums. +
- >**NOTE:** To edit a user's username, email, or role, you must do so in the **Users** tab in the **Configuration** menu of your Grafana instance. + > **NOTE:** To edit a user's username, email, or role, you must do so in the **Users** tab in the **Configuration** menu of your Grafana instance. 1. Configure notification settings. - - You can configure the notification medium and frequency for each user. **Important Notifications** are specified in escalation steps. + + You can configure the notification medium and frequency for each user. **Important Notifications** are specified in escalation steps. ## Connect to integration data sources You use Grafana OnCall to connect to the monitoring services of your alert sources listed in the Grafana OnCall **Integrations** section. 1. Connect to a alert source with configured alerts. - - In Grafana OnCall, click on the **Integrations** tab and click **+ New integration for receiving alerts**. + + In Grafana OnCall, click on the **Integrations** tab and click **+ New integration for receiving alerts**. 1. Select an integration from the provided options. - - If you want to use an integration that is not listed, you must use webhooks. + + If you want to use an integration that is not listed, you must use webhooks. 1. Configure your integration. - - Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana alert source, select Grafana and follow the instructions. + + Each integration has a different method of connecting to Grafana OnCall. For example, if you want to connect to your Grafana alert source, select Grafana and follow the instructions. ## Configure escalation policies -You can use **escalation chains** to determine ordered escalation procedures. Configuring escalation chains allows you to set up a chain of incident notification actions that trigger if certain conditions that you specify are not met. +You can use **escalation chains** to determine ordered escalation procedures. Configuring escalation chains allows you to set up a chain of incident notification actions that trigger if certain conditions that you specify are not met. 1. Click on the integration tile for which you want to define escalation policies. - - The **Escalations** section for the notification is in the pane to the right of the list of notifications. - You can click **Change alert template and grouping** to customize the look of the alert. You can also do this by clicking the **Settings** (gear) icon in the integration tile. + + The **Escalations** section for the notification is in the pane to the right of the list of notifications. + You can click **Change alert template and grouping** to customize the look of the alert. You can also do this by clicking the **Settings** (gear) icon in the integration tile. 1. Create an escalation chain. - - In the escalation pane, click the **escalate to** menu to choose from previously added escalation chains, or create a new one by clicking **Create a new**. This will be the name of the escalation policy you define. + + In the escalation pane, click the **escalate to** menu to choose from previously added escalation chains, or create a new one by clicking **Create a new**. This will be the name of the escalation policy you define. 1. Add escalation steps. - Click **Add escalation step** to choose from a set of actions and specify their triggering conditions. By default, the first step is to notify a slack channel or user. Specify users or channels or toggle the switch to turn this step off. + Click **Add escalation step** to choose from a set of actions and specify their triggering conditions. By default, the first step is to notify a slack channel or user. Specify users or channels or toggle the switch to turn this step off. - To mark an escalation as **Important**, select the option from the step **Start** dropdown menu. User notification policies can be separately defined for **Important** and **Default** escalations. + To mark an escalation as **Important**, select the option from the step **Start** dropdown menu. User notification policies can be separately defined for **Important** and **Default** escalations. 1. Add a route. - To add a route, click **Add Route**. - - You can set up a single route and specify notification escalation steps, or you can add multiple routes, each with its own configuration. + To add a route, click **Add Route**. - Each route added to an escalation policy follows an `IF`, `ELSE IF`, and `ELSE` path and depends on the type of alert you specify using a regular expression that matches content in the payload body of the alert. You can also specify where to send the notification for each route. - - For example, you can send notifications for alert incidents with `\"severity\": \"critical\"` in the payload to an escalation chain called `Bob_OnCall`. You can create a different route for alerts with the payload `\"namespace\" *: *\"synthetic-monitoring-dev-.*\"` and select a escalation chain called `NotifySecurity`. + You can set up a single route and specify notification escalation steps, or you can add multiple routes, each with its own configuration. - You can set up escalation steps for each route in a chain. + Each route added to an escalation policy follows an `IF`, `ELSE IF`, and `ELSE` path and depends on the type of alert you specify using a regular expression that matches content in the payload body of the alert. You can also specify where to send the notification for each route. + + For example, you can send notifications for alert incidents with `\"severity\": \"critical\"` in the payload to an escalation chain called `Bob_OnCall`. You can create a different route for alerts with the payload `\"namespace\" *: *\"synthetic-monitoring-dev-.*\"` and select a escalation chain called `NotifySecurity`. + + You can set up escalation steps for each route in a chain. + + > **NOTE:** When you modify an escalation chain or a route, it will modify that escalation chain across all integrations that use it. - >**NOTE:** When you modify an escalation chain or a route, it will modify that escalation chain across all integrations that use it. - ## Use calendars to configure on-call schedules You can use any calendar with an iCal address to schedule on-call times for users. During these times, notifications configured in escalation chains with the **Notify users from an on-call schedule** setting will be sent to the the person scheduled. You can also schedule multiple users for overlapping times, and assign prioritization labels for the user that you would like to notify. 1. In the **Scheduling** section of Grafana OnCall, click **+ Create schedule**. -1. Give the schedule a name. +1. Give the schedule a name. 1. Create a new calendar in your calendar service and locate the secret iCal URL. For example, in a Google calendar, this URL can be found in **Settings > Settings for my calendars > Integrate calendar**. -1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. - The permissions you set for the calendar determine who can modify the calendar. +1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. + The permissions you set for the calendar determine who can modify the calendar. 1. Click **Create Schedule**. 1. Schedule on-call times for team members. - Use the usersname of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. + Use the usersname of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. -1. (Optional) Create overlapping schedules. +1. (Optional) Create overlapping schedules. - When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including level 9, or `[L9]`. + When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including level 9, or `[L9]`. ### (Optional) Create an override calendar. @@ -112,10 +118,10 @@ You can use an override calendar to allow team members to schedule on-call dutie 1. Create a new calendar using the same calendar service you used to create the primary calendar. - Be sure to set permissions that allow team members to edit the calendar. + Be sure to set permissions that allow team members to edit the calendar. -1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. +1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. -1. Click **Edit**. +1. Click **Edit**. 1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index ba58b183..cfbed723 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -1,21 +1,29 @@ -+++ -title = "Connect to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "oncall", "integrations"] -weight = 300 -aliases = ["/docs/grafana-cloud/oncall/integrations/"] -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/integrations/ + - /docs/oncall/latest/integrations/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - integrations +title: Connect to Grafana OnCall +weight: 300 +--- # Connect to Grafana OnCall -Integrations allow you to connect monitoring systems of your choice to send alerts to Grafana OnCall. Regardless of where your alerts originate, you can configure alerts to be sent to Grafana OnCall for alert escalation and notification. Grafana OnCall receives alerts in JSON format via a POST request, OnCall then parses alert data using preconfigured alert templates to determine alert grouping, apply routes, and determine correct escalation. +Integrations allow you to connect monitoring systems of your choice to send alerts to Grafana OnCall. Regardless of where your alerts originate, you can configure alerts to be sent to Grafana OnCall for alert escalation and notification. Grafana OnCall receives alerts in JSON format via a POST request, OnCall then parses alert data using preconfigured alert templates to determine alert grouping, apply routes, and determine correct escalation. -There are many integrations that are directly supported by Grafana OnCall. Those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. +There are many integrations that are directly supported by Grafana OnCall. Those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. ## Configure and manage integrations You can configure and manage your integrations from the **Integrations** tab in Grafana OnCall. The following sections describe how to configure and customize your integrations to ensure alerts are treated appropriately. - ### Connect an integration to Grafana OnCall To configure an integration for Grafana OnCall: @@ -25,10 +33,9 @@ To configure an integration for Grafana OnCall: 3. Follow the configuration steps on the integration settings page. 4. Complete any necessary configurations in your tool to send alerts to Grafana OnCall. - ### Manage Grafana OnCall integrations -To manage existing integrations, navigate to the **Integrations** tab in Grafana OnCall and select the integration you want to manage. +To manage existing integrations, navigate to the **Integrations** tab in Grafana OnCall and select the integration you want to manage. #### Customize alert templates and grouping @@ -37,17 +44,16 @@ To customize the alert template for an integration: 1. Select an integration from your list of enabled integrations in the **Integrations** tab. 2. Click **Change alert template and grouping**. 3. Select a template to edit from the **Edit template for** dropdown menu. -4. Edit alert templates as needed to customize the fields and content rendered for an alert. +4. Edit alert templates as needed to customize the fields and content rendered for an alert. To customize alert grouping for an integration: 1. Click **Change alert template and grouping**. 2. Select **Alert Behavior** from the dropdown menu next to **Edit template for**. -3. Edit the **grouping id**, **acknowledge condition**, and **resolve condition** templates as needed to customize your alert behavior. +3. Edit the **grouping id**, **acknowledge condition**, and **resolve condition** templates as needed to customize your alert behavior. For more information on alert templates, see [Configure alerts in Grafana OnCall]({{< relref " ../create-custom-templates/" >}}) - #### Add Routes To add a route to an integration using regular expression: @@ -56,25 +62,24 @@ To add a route to an integration using regular expression: 2. Click **+ Add Route**. 3. Use python style regex to match on your alert content. 4. Click **Create Route**. -5. Select an escalation chain for “**IF** alert payload matches regex” and “**ELSE**” to specify where to route each type of alert. +5. Select an escalation chain for “**IF** alert payload matches regex” and “**ELSE**” to specify where to route each type of alert. To learn more about routes, refer to [Configure and manage Routes]({{< relref " ../configure-routes/" >}}) - #### Edit integration name + To edit the name of an integration: -1. Navigate to the **Integrations** tab, select an integration from the list of enabled integrations. +1. Navigate to the **Integrations** tab, select an integration from the list of enabled integrations. 2. Click the **pencil icon** next to the integration name. 3. Provide a new name and click **Update**. -#### Delete integration +#### Delete integration + To delete an integration: 1. Select an integration from your list of enabled integrations in the **Integrations** tab. 2. Click the **trash can** icon next to the selected integration. 3. Confirm by clicking **Delete**. - - {{< section >}} diff --git a/docs/sources/integrations/add-webhook-integration.md b/docs/sources/integrations/add-webhook-integration.md index ebde152a..e0579381 100644 --- a/docs/sources/integrations/add-webhook-integration.md +++ b/docs/sources/integrations/add-webhook-integration.md @@ -1,36 +1,45 @@ -+++ -title = "Webhook integration for Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] -weight = 700 -+++ +--- +aliases: + - /docs/oncall/latest/integrations/add-webhook-integration/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Alertmanager + - Prometheus +title: Webhook integration for Grafana OnCall +weight: 700 +--- # Configure Webhook integrations for Grafana OnCall -Grafana OnCall directly supports many integrations, those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. +Grafana OnCall directly supports many integrations, those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. -With the webhook integration, you can connect to any alert source that isn't listed in the **Create Integration** page. +With the webhook integration, you can connect to any alert source that isn't listed in the **Create Integration** page. There are two available formats, **Webhook** and **Formatted Webhook**. -* **Webhook** will pull all of the raw JSON payload and display it in the manner that it's received. -* **Formatted Webhook** can be used if the alert payload sent by your monitoring service is formatted in a way that OnCall recognizes. - - The following fields are recognized, but none are required: - * `alert_uid`: a unique alert ID for grouping. - * `title`: a title. - * `image_url`: a URL for an image attached to alert. - * `state`: either `ok` or `alerting`. Helpful for auto-resolving. - * `link_to_upstream_details`: link back to your monitoring system. - * `message`: alert details. +- **Webhook** will pull all of the raw JSON payload and display it in the manner that it's received. +- **Formatted Webhook** can be used if the alert payload sent by your monitoring service is formatted in a way that OnCall recognizes. + + The following fields are recognized, but none are required: + + - `alert_uid`: a unique alert ID for grouping. + - `title`: a title. + - `image_url`: a URL for an image attached to alert. + - `state`: either `ok` or `alerting`. Helpful for auto-resolving. + - `link_to_upstream_details`: link back to your monitoring system. + - `message`: alert details. To configure a webhook integration: 1. In the **Integrations** tab, click **+ New integration for receiving alerts**. -2. Select either **Webhook** or **Formatted Webhook** integration. +2. Select either **Webhook** or **Formatted Webhook** integration. 3. Follow the configuration steps in the **How to connect** section of the integration settings. 4. Use the unique webhook URL to complete any configuration in your monitoring service to send POST requests. Use any http client, e.g. curl to send POST requests with any payload. - - For example: + +For example: ```json curl -X POST \ @@ -46,5 +55,4 @@ To configure a webhook integration: }' ``` - -To learn how to use custom alert templates for formatted webhooks, see [Configure alerts in Grafana OnCall]({{< relref "../create-custom-templates/" >}}). \ No newline at end of file +To learn how to use custom alert templates for formatted webhooks, see [Configure alerts in Grafana OnCall]({{< relref "../create-custom-templates/" >}}). diff --git a/docs/sources/integrations/available-integrations /_index.md b/docs/sources/integrations/available-integrations /_index.md index 6898f87a..6e30a415 100644 --- a/docs/sources/integrations/available-integrations /_index.md +++ b/docs/sources/integrations/available-integrations /_index.md @@ -1,21 +1,26 @@ -+++ -title = "Currently available integrations for Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] -aliases = ["/docs/grafana-cloud/oncall/integrations/add-integration/"] -weight = 100 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/integrations/add-integration/ + - /docs/oncall/latest/integrations/available-integrations / +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Alertmanager + - Prometheus +title: Currently available integrations for Grafana OnCall +weight: 100 +--- # Currently available integrations Grafana OnCall can connect directly to the monitoring services where your alerts originate. All currently available integrations are listed in the Grafana OnCall **Create Integration** section. -If the integration you're looking for isn't currently listed, see [Configure Webhook integrations for Grafana OnCall]({{< relref " ../add-webhook-integration/" >}}) to integration your monitoring system with Grafana OnCall. - ->**Note:** Some integrations are available for Grafana Cloud instances only. See individual integration guides for more information. +If the integration you're looking for isn't currently listed, see [Configure Webhook integrations for Grafana OnCall]({{< relref " ../add-webhook-integration/" >}}) to integration your monitoring system with Grafana OnCall. +> **Note:** Some integrations are available for Grafana Cloud instances only. See individual integration guides for more information. The following integrations are currently available for Grafana OnCall and have documentation: - - {{< section >}} diff --git a/docs/sources/integrations/available-integrations /add-alertmanager.md b/docs/sources/integrations/available-integrations /add-alertmanager.md index 2fd195fb..f5604f4e 100644 --- a/docs/sources/integrations/available-integrations /add-alertmanager.md +++ b/docs/sources/integrations/available-integrations /add-alertmanager.md @@ -1,13 +1,21 @@ -+++ -title = "Connect Alert Manager to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Alertmanager", "Prometheus"] -aliases = ["/docs/grafana-cloud/oncall/available-integrations/add-alertmanager/"] -weight = 300 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/available-integrations/add-alertmanager/ + - /docs/oncall/latest/integrations/available-integrations /add-alertmanager/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Alertmanager + - Prometheus +title: Connect Alert Manager to Grafana OnCall +weight: 300 +--- # Connect AlertManager to Grafana OnCall -The AlertManager integration for Grafana OnCall handles alerts sent by client applications such as the Prometheus server. +The AlertManager integration for Grafana OnCall handles alerts sent by client applications such as the Prometheus server. Grafana OnCall provides grouping abilities when processing alerts from Alert Manager, including initial deduplicating, grouping, and routing the alerts to Grafana OnCall. @@ -26,6 +34,7 @@ You must have an Admin role to create integrations in Grafana OnCall. ## Configure AlertManager Update the `receivers` section of your Alertmanager configuration to use a unique integration URL: + ``` route: receiver: 'oncall' @@ -47,12 +56,12 @@ AlertManager offers three alert grouping options: - `group_by` provides two options, `instance` or `job`. - `group_wait` sets the length of time to initially wait before sending a notification for a particular group of alerts. For example, `group_wait` can be set to 45s. - Setting a high value for `group_wait` reduces alert noise and minimizes interruption, but it may introduce delays in receiving alert notifications. To set an appropriate wait time, consider whether the group of alerts will be the same as those previously sent. + Setting a high value for `group_wait` reduces alert noise and minimizes interruption, but it may introduce delays in receiving alert notifications. To set an appropriate wait time, consider whether the group of alerts will be the same as those previously sent. - `group_interval` sets the length of time to wait before sending notifications about new alerts that have been added to a group of alerts that have been previously alerted on. This setting is usually set to five minutes or more. - During high alert volume periods, AlertManager will send alerts at each `group_interval`, which can mean a lot of distraction. Grafana OnCall grouping will help manage this in the following ways: + During high alert volume periods, AlertManager will send alerts at each `group_interval`, which can mean a lot of distraction. Grafana OnCall grouping will help manage this in the following ways: - - Grafana OnCall groups alerts based on the first label of each alert. + - Grafana OnCall groups alerts based on the first label of each alert. - - Grafana OnCall marks an incident as resolved only when the amount of grouped alerts with state `resolved` equals the amount of alerts with state `firing`. + - Grafana OnCall marks an incident as resolved only when the amount of grouped alerts with state `resolved` equals the amount of alerts with state `firing`. diff --git a/docs/sources/integrations/available-integrations /add-grafana-alerting.md b/docs/sources/integrations/available-integrations /add-grafana-alerting.md index 885e9be6..0e8519dd 100644 --- a/docs/sources/integrations/available-integrations /add-grafana-alerting.md +++ b/docs/sources/integrations/available-integrations /add-grafana-alerting.md @@ -1,9 +1,16 @@ -+++ -title = "Connect Grafana Alerting to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Prometheus"] -aliases = ["/docs/grafana-cloud/oncall/integrations/add-grafana-alerting/"] -weight = 100 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/integrations/add-grafana-alerting/ + - /docs/oncall/latest/integrations/available-integrations /add-grafana-alerting/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Prometheus +title: Connect Grafana Alerting to Grafana OnCall +weight: 100 +--- # Connect Grafana Alerting to Grafana OnCall @@ -13,7 +20,7 @@ Grafana Alerting for Grafana OnCall can be set up using two methods: - Grafana (Other Grafana): Grafana OnCall is connected to one or more Grafana instances separate from the one being used to manage Grafana OnCall. -## Configure Grafana Alerting for Grafana OnCall +## Configure Grafana Alerting for Grafana OnCall You must have an Admin role to create integrations in Grafana OnCall. @@ -23,21 +30,21 @@ You must have an Admin role to create integrations in Grafana OnCall. 3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL and complete any necessary configurations. - ### Configure Grafana Cloud Alerting + Use the following method if you are connecting Grafana OnCall with alerts coming from the same Grafana instance from which Grafana OnCall is being managed. 1. In Grafana OnCall, navigate to the **Integrations** tab and select **New Integration for receiving alerts**. -1. Click **Quick connect** in the **Grafana Alerting** tile. This will automatically create the integration in Grafana OnCall as well as the required contact point in Alerting. +1. Click **Quick connect** in the **Grafana Alerting** tile. This will automatically create the integration in Grafana OnCall as well as the required contact point in Alerting. - >**Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/) + > **Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/) -1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new escalation chain. +1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new escalation chain. -2. In Grafana Cloud Alerting, navigate to **Alerting > Contact Points** and find a contact point with a name matching the integration you created in Grafana OnCall. +1. In Grafana Cloud Alerting, navigate to **Alerting > Contact Points** and find a contact point with a name matching the integration you created in Grafana OnCall. -3. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. +1. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. ### Configure Grafana (Other Grafana) @@ -57,6 +64,6 @@ Connect Grafana OnCall with alerts coming from a Grafana instance that is differ 7. Choose the contact point type `webhook`, then paste the URL generated in step 3 into the URL field. - >**Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/). + > **Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/). -8. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. \ No newline at end of file +8. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. diff --git a/docs/sources/integrations/available-integrations /add-zabbix.md b/docs/sources/integrations/available-integrations /add-zabbix.md index 26b04f65..a85e2477 100644 --- a/docs/sources/integrations/available-integrations /add-zabbix.md +++ b/docs/sources/integrations/available-integrations /add-zabbix.md @@ -1,14 +1,20 @@ -+++ -title = "Connect Zabbix to Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Zabbix"] -weight = 500 -+++ +--- +aliases: + - /docs/oncall/latest/integrations/available-integrations /add-zabbix/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Zabbix +title: Connect Zabbix to Grafana OnCall +weight: 500 +--- # Connect Zabbix to Grafana OnCall Zabbix is an open-source monitoring software tool for diverse IT components, including networks, servers, virtual machines, and cloud services. Zabbix provides monitoring for metrics such as network utilization, CPU load, and disk space consumption. - ## Configure Zabbix integration for Grafana OnCall This integration is available for Grafana Cloud OnCall. You must have an Admin role to create integrations in Grafana OnCall. @@ -17,86 +23,92 @@ This integration is available for Grafana Cloud OnCall. You must have an Admin r 2. Select **Zabbix** from the list of available integrations 3. Follow the instructions in the **How to connect** window to get your unique integration URL and review next steps. - ## Configure the Zabbix server 1. Deploy a Zabbix playground if you don't have one set up: - ```bash - docker run --name zabbix-appliance -t \ - -p 10051:10051 \ - -p 80:80 \ - -d zabbix/zabbix-appliance:latest - ``` + + ```bash + docker run --name zabbix-appliance -t \ + -p 10051:10051 \ + -p 80:80 \ + -d zabbix/zabbix-appliance:latest + ``` 1. Establish an ssh connection to a Zabbix server. - ```bash - docker exec -it zabbix-appliance bash - ``` + ```bash + docker exec -it zabbix-appliance bash + ``` 1. Place the [grafana_oncall.sh](#grafana_oncallsh-script) script in the `AlertScriptsPath` directory specified within the Zabbix server configuration file (zabbix_server.conf). - ```bash - grep AlertScriptsPath /etc/zabbix/zabbix_server.conf - ``` - >**Note:** The script must be executable by the user running the zabbix_server binary (usually "zabbix") on the Zabbix server. For example, `chmod +x grafana_oncall.sh` + ```bash + grep AlertScriptsPath /etc/zabbix/zabbix_server.conf + ``` - ``` bash - ls -lh /usr/lib/zabbix/alertscripts/grafana_oncall.sh - -rw-r--r-- 1 root root 1.5K Jun 6 07:52 /usr/lib/zabbix/alertscripts/grafana_oncall.sh - ``` + > **Note:** The script must be executable by the user running the zabbix_server binary (usually "zabbix") on the Zabbix server. For example, `chmod +x grafana_oncall.sh` + + ```bash + ls -lh /usr/lib/zabbix/alertscripts/grafana_oncall.sh + -rw-r--r-- 1 root root 1.5K Jun 6 07:52 /usr/lib/zabbix/alertscripts/grafana_oncall.sh + ``` ## Configure Zabbix alerts + Within Zabbix web interface, do the following: 1. In a browser, open localhost:80. 1. Navigate to **Adminitstration > Media Types > Create Media Type**. - + 1. Create a Media Type with the following fields. - * Name: Grafana OnCall - * Type: script - * Script parameters: - * {ALERT.SENDTO} - * {ALERT.SUBJECT} - * {ALERT.MESSAGE} - + - Name: Grafana OnCall + - Type: script + - Script parameters: + - {ALERT.SENDTO} + - {ALERT.SUBJECT} + - {ALERT.MESSAGE} + + ### Set the {ALERT.SEND_TO} value + To send alerts to Grafana OnCall, the {ALERT.SEND_TO} value must be set in the [user media configuration](https://www.zabbix.com/documentation/3.4/manual/config/notifications/media/script#user_media). -1. In the web UI, navigate to **Administration > Users** and open the **user properties** form. +1. In the web UI, navigate to **Administration > Users** and open the **user properties** form. 1. In the **Media** tab, click **Add** and copy the link from Grafana OnCall in the `Send to` field. - + 1. Click **Test** in the last column to send a test alert to Grafana OnCall. - + 1. Specify **Send to** OnCall using the unique integration URL from the above step in the testing window that opens. -Create a test message with a body and optional subject and click **Test**. - + Create a test message with a body and optional subject and click **Test**. + ## Grouping and auto-resolve of Zabbix notifications + Grafana OnCall provides grouping and auto-resolve of Zabbix notifications. Use the following procedure to configure grouping and auto-resolve. -1. Provide a parameter as an identifier for group differentiation to Grafana OnCall. +1. Provide a parameter as an identifier for group differentiation to Grafana OnCall. -1. Append that variable to the subject of the action as `ONCALL_GROUP: ID`, where `ID` is any of the Zabbix [macros](https://www.zabbix.com/documentation/4.2/manual/appendix/macros/supported_by_location). -For example, `{EVENT.ID}`. The Grafana OnCall script [grafana_oncall.sh](#grafana_oncallsh-script) extracts this event and passes the `alert_uid` to Grafana OnCall. +1. Append that variable to the subject of the action as `ONCALL_GROUP: ID`, where `ID` is any of the Zabbix [macros](https://www.zabbix.com/documentation/4.2/manual/appendix/macros/supported_by_location). + For example, `{EVENT.ID}`. The Grafana OnCall script [grafana_oncall.sh](#grafana_oncallsh-script) extracts this event and passes the `alert_uid` to Grafana OnCall. 1. To enable auto-resolve within Grafana Oncall, the "Resolved" keyword is required in the **Default subject** field in **Recovered operations**. - + ## grafana_oncall.sh script + ```bash #!/bin/bash # This is the modification of original ericos's shell script. @@ -137,4 +149,5 @@ return=$(curl $url -d "${payload}" -H "Content-Type: application/json" -X POST) ``` ## More Information -For more information on Zabbix scripts, see [scripts for notifications](https://www.zabbix.com/documentation/4.2/manual/config/notifications/media/script). \ No newline at end of file + +For more information on Zabbix scripts, see [scripts for notifications](https://www.zabbix.com/documentation/4.2/manual/config/notifications/media/script). diff --git a/docs/sources/integrations/configure-outgoing-webhooks.md b/docs/sources/integrations/configure-outgoing-webhooks.md index 4a0b56ab..dda09988 100644 --- a/docs/sources/integrations/configure-outgoing-webhooks.md +++ b/docs/sources/integrations/configure-outgoing-webhooks.md @@ -1,37 +1,45 @@ -+++ -title = "Configure outgoing webhooks for Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "amixr", "webhooks"] -weight = 500 -+++ +--- +aliases: + - /docs/oncall/latest/integrations/configure-outgoing-webhooks/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - webhooks +title: Configure outgoing webhooks for Grafana OnCall +weight: 500 +--- # Configure outgoing webhooks for Grafana OnCall -Outgoing webhooks allow you to send alert details to a specified URL from Grafana OnCall. Once an outgoing webhook is configured, you can use it as a notification method in escalation chains. +Outgoing webhooks allow you to send alert details to a specified URL from Grafana OnCall. Once an outgoing webhook is configured, you can use it as a notification method in escalation chains. +To automatically send alert data to a destination URL via outgoing webhook: -To automatically send alert data to a destination URL via outgoing webhook: 1. In Grafana OnCall, navigate to **Outgoing Webhooks** and click **+ Create**. - This is also the place to edit and delete existing outgoing webhooks. + This is also the place to edit and delete existing outgoing webhooks. 2. Provide a name for your outgoing webhook and enter the destination URL. 3. If the destination requires authentication, enter your credentials. - You can enter a username and password (HTTP) or an authorization header formatted in JSON. + You can enter a username and password (HTTP) or an authorization header formatted in JSON. -4. Configure the webhook payload in the **Data** field. - +4. Configure the webhook payload in the **Data** field. 5. Click **Create Webhook**. The format you use to call the variables must match the structure of how the fields are nested in the alert payload. The **Data** field can use the following four variables to auto-populate the webhook payload with information about the first alert in the alert group: + - `{{ alert_title }}` - `{{ alert_message }}` -- `{{ alert_url }}` +- `{{ alert_url }}` - `{{ alert_payload }}` -
+
`alert_payload` is always the first level of any variable you want to call. -The following is an example of an entry in the **Data** field that might return an alert name and description. +The following is an example of an entry in the **Data** field that might return an alert name and description. ```json { @@ -40,5 +48,4 @@ The following is an example of an entry in the **Data** field that might return } ``` ->**NOTE:** If you receive an error message and cannot create an outgoing webhook, verify that your JSON is formatted correctly. - +> **NOTE:** If you receive an error message and cannot create an outgoing webhook, verify that your JSON is formatted correctly. diff --git a/docs/sources/integrations/create-custom-templates.md b/docs/sources/integrations/create-custom-templates.md index 9d2add94..676278db 100644 --- a/docs/sources/integrations/create-custom-templates.md +++ b/docs/sources/integrations/create-custom-templates.md @@ -1,12 +1,19 @@ -+++ -title = "Configure alerts in Grafana OnCall" -keywords = ["Grafana Cloud", "Alerts", "Notifications", "on-call", "Jinja"] -weight = 300 -+++ +--- +aliases: + - /docs/oncall/latest/integrations/create-custom-templates/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Jinja +title: Configure alerts in Grafana OnCall +weight: 300 +--- # Configure alerts in Grafana OnCall - Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default pre configured alert template is applied to modify the alert payload to be more human readable. These alert templates are customizable for any integration. +Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default pre configured alert template is applied to modify the alert payload to be more human readable. These alert templates are customizable for any integration. See Format alerts with alert templates in this document to learn more about how to customize alert templates. @@ -24,83 +31,88 @@ Alerts received by Grafana OnCall contain metadata as keys and values in a JSON ```json { - "dashboardId":1, - "title":"[Alerting] Panel Title alert", - "message":"Notification Message", - "evalMatches":[ + "dashboardId": 1, + "title": "[Alerting] Panel Title alert", + "message": "Notification Message", + "evalMatches": [ { - "value":1, - "metric":"Count", - "tags":{} + "value": 1, + "metric": "Count", + "tags": {} } ], - "imageUrl":"https://grafana.com/static/assets/img/blog/mixed_styles.png", - "orgId":1, - "panelId":2, - "ruleId":1, - "ruleName":"Panel Title alert", - "ruleUrl":"http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1", - "state":"alerting", - "tags":{ - "tag name":"tag value" + "imageUrl": "https://grafana.com/static/assets/img/blog/mixed_styles.png", + "orgId": 1, + "panelId": 2, + "ruleId": 1, + "ruleName": "Panel Title alert", + "ruleUrl": "http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1", + "state": "alerting", + "tags": { + "tag name": "tag value" } } ``` In Grafana OnCall every alert and alert group has the following fields: + - `Title`, `message` and `image url` - `Grouping Id` - `Resolve Signal` -The JSON payload is converted. For example: -* `{{ payload.title }}` -> Title -* `{{ payload.message }}` -> Message -* `{{ payload.imageUrl }}` -> Image Url +The JSON payload is converted. For example: + +- `{{ payload.title }}` -> Title +- `{{ payload.message }}` -> Message +- `{{ payload.imageUrl }}` -> Image Url The result is that each field of the alert in OnCall is now mapped to the JSON payload keys. This also true for the alert behavior: -* `{{ payload.ruleId }}` -> Grouping Id -* `{{ 1 if payload.state == 'OK' else 0 }}` -> Resolve Signal +- `{{ payload.ruleId }}` -> Grouping Id +- `{{ 1 if payload.state == 'OK' else 0 }}` -> Resolve Signal Grafana OnCall provides a pre configured default Jinja template for supported integrations. If your monitoring system is not in the Grafana OnCall integrations list, you can create a generic `webhook` integration, send an alert, and configure your templates. +## Customize alerts with alert templates -## Customize alerts with alert templates - -Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert templates for all the different ways you receive your alerts such as web, slack, SMS, and email. For more advanced customization, use Jinja templates. +Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert templates for all the different ways you receive your alerts such as web, slack, SMS, and email. For more advanced customization, use Jinja templates. As a best practice, add _Playbooks_, _Useful links_, or _Checklists_ to the alert message. To customize alert templates in Grafana OnCall: -1. Navigate to the **Integrations** tab, select the integration, then click **Change alert template and grouping**. +1. Navigate to the **Integrations** tab, select the integration, then click **Change alert template and grouping**. 2. In Alert Templates, select a template from the **Edit template for** dropdown. 3. Edit the Appearances template as needed: - * `Title`, `Message`, `Image url` for Web - * `Title`, `Message`, `Image url` for Slack - * `Title` used for SMS - * `Title` used for Phone - * `Title`, `Message` used for Email + + - `Title`, `Message`, `Image url` for Web + - `Title`, `Message`, `Image url` for Slack + - `Title` used for SMS + - `Title` used for Phone + - `Title`, `Message` used for Email 4. Edit the alert behavior as needed: - * `Grouping Id` - This output groups other alerts into a single alert group. - * `Acknowledge Condition` - The output should be `ok`, `true`, or `1` to auto-acknowledge the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. - * `Resolve Condition` - The output should be `ok`, `true` or `1` to auto-resolve the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. - * `Source Link` - Used to customize the URL link to provide as the "source" of the alert. + - `Grouping Id` - This output groups other alerts into a single alert group. + - `Acknowledge Condition` - The output should be `ok`, `true`, or `1` to auto-acknowledge the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. + - `Resolve Condition` - The output should be `ok`, `true` or `1` to auto-resolve the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. + - `Source Link` - Used to customize the URL link to provide as the "source" of the alert. ## Advanced Jinja templates - Grafana OnCall uses [Jinja templating language](http://jinja.pocoo.org/docs/2.10/) to format alert groups for the Web, Slack, phone calls, SMS messages, and more because the JSON format is not easily readable by humans. As a result, you can decide what you want to see when an alert group is triggered as well as how it should be presented. - + +Grafana OnCall uses [Jinja templating language](http://jinja.pocoo.org/docs/2.10/) to format alert groups for the Web, Slack, phone calls, SMS messages, and more because the JSON format is not easily readable by humans. As a result, you can decide what you want to see when an alert group is triggered as well as how it should be presented. + Jinja2 offers simple but multi-faceted functionality by using loops, conditions, functions, and more. -> **NOTE:** Every alert from a monitoring system comes in the key/value format. +> **NOTE:** Every alert from a monitoring system comes in the key/value format. + Grafana OnCall has rules about which of the keys match to: `__title`, `message`, `image`, `grouping`, and `auto-resolve__`. ### Loops Monitoring systems can send an array of values. In this example, you can use Jinja to iterate and format the alert using a Grafana example: + ```.jinja2 *Values:* {% for evalMatch in payload.evalMatches -%} @@ -109,9 +121,10 @@ Monitoring systems can send an array of values. In this example, you can use Jin ``` ### Conditions + You can add instructions if an alert comes from a specified Grafana alert rule: -```jinja2 +````jinja2 {% if payload.ruleId == '1' -%} *Alert TODOs* 1. Get acess to the container @@ -122,22 +135,26 @@ You can add instructions if an alert comes from a specified Grafana alert rule: 3. Open the container and reload caches. 4. Click Custom Button `Send to Jira` {%- endif -%} -``` +```` ### Built-in Jinja functions Jinja2 includes built-in functions that can also be used in Grafana OnCall. For example: + ```.jinja2 {{ payload | tojson_pretty }} ``` + Built-in functions: -* `abs` -* `capitalize` -* `trim` -* You can see the full list of Jinja built-in functions on github [here](https://github.com/pallets/jinja/blob/3915eb5c2a7e2e4d49ebdf0ecb167ea9c21c60b2/src/jinja2/filters.py#L1307) + +- `abs` +- `capitalize` +- `trim` +- You can see the full list of Jinja built-in functions on github [here](https://github.com/pallets/jinja/blob/3915eb5c2a7e2e4d49ebdf0ecb167ea9c21c60b2/src/jinja2/filters.py#L1307) ### Functions added by Grafana OnCall -* `time` - current time -* `tojson_pretty` - JSON prettified -* `iso8601_to_time` - converts time from iso8601 (`2015-02-17T18:30:20.000Z`) to datetime -* `datetimeformat` - converts time from datetime to the given format (`%H:%M / %d-%m-%Y` by default) + +- `time` - current time +- `tojson_pretty` - JSON prettified +- `iso8601_to_time` - converts time from iso8601 (`2015-02-17T18:30:20.000Z`) to datetime +- `datetimeformat` - converts time from datetime to the given format (`%H:%M / %d-%m-%Y` by default) diff --git a/docs/sources/oncall-api-reference/_index.md b/docs/sources/oncall-api-reference/_index.md index 2fee042b..b696b0fc 100644 --- a/docs/sources/oncall-api-reference/_index.md +++ b/docs/sources/oncall-api-reference/_index.md @@ -1,7 +1,9 @@ -+++ -title = "Grafana OnCall HTTP API reference" -weight = 1300 -+++ +--- +aliases: + - /docs/oncall/latest/oncall-api-reference/ +title: Grafana OnCall HTTP API reference +weight: 1300 +--- # HTTP API Reference @@ -23,7 +25,7 @@ curl "api_endpoint_here" --header "Authorization: meowmeowmeow" ``` Note that `meowmeowmeow` is a valid key for test purposes. -Replace `meowmeowmeow` with your API key in production. +Replace `meowmeowmeow` with your API key in production. Grafana OnCall uses API keys to allow access to the API. You can request a new OnCall API key in the API section. @@ -31,33 +33,34 @@ An API key is specific to a user and a Grafana stack. If you want to switch to a ## Pagination -List endpoints such as List Integrations or List Alert Groups return multiple objects. +List endpoints such as List Integrations or List Alert Groups return multiple objects. -The OnCall API returns them in pages. Note that the page size may vary. +The OnCall API returns them in pages. Note that the page size may vary. -| Parameter | Meaning | -|-----------|:-------:| -`count` | The total number of items. It can be `0` if a request does not return any data. -`next` | A link to the next page. It can be `null` if the next page does not contain any data. -`previous` | A link to the previous page. It can be `null` if the previous page does not contain any data. -`results` | The data list. Can be `[]` if a request does not return any data. +| Parameter | Meaning | +| ---------- | :-------------------------------------------------------------------------------------------: | +| `count` | The total number of items. It can be `0` if a request does not return any data. | +| `next` | A link to the next page. It can be `null` if the next page does not contain any data. | +| `previous` | A link to the previous page. It can be `null` if the previous page does not contain any data. | +| `results` | The data list. Can be `[]` if a request does not return any data. | ## Rate Limits Grafana OnCall provides rate limits to ensure alert group notifications will be delivered to your Slack workspace even when some integrations produce a large number of alerts. ### Monitoring integrations Rate Limits + Rate limited response HTTP status: 429 - | Scope | Amount | Time Frame | -|------------------------------|:------:|:----------:| -| Alerts from each integration | 300 | 5 minutes | -| Alerts from the whole team | 500 | 5 minutes | +| ---------------------------- | :----: | :--------: | +| Alerts from each integration | 300 | 5 minutes | +| Alerts from the whole team | 500 | 5 minutes | ## API rate limits + You can reduce or increase rate limits depending on platform status. | Scope | Amount | Time Frame | -|--------------------------|:------:|:--------:| -| API requests per API key | 300 | 5 minutes | \ No newline at end of file +| ------------------------ | :----: | :--------: | +| API requests per API key | 300 | 5 minutes | diff --git a/docs/sources/oncall-api-reference/alertgroups.md b/docs/sources/oncall-api-reference/alertgroups.md index 4094f0b3..9ebec034 100644 --- a/docs/sources/oncall-api-reference/alertgroups.md +++ b/docs/sources/oncall-api-reference/alertgroups.md @@ -1,8 +1,10 @@ -+++ -title = "Alert groups HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/alertgroups/"] -weight = 400 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/alertgroups/ + - /docs/oncall/latest/oncall-api-reference/alertgroups/ +title: Alert groups HTTP API +weight: 400 +--- # List alert groups @@ -10,36 +12,36 @@ weight = 400 curl "{{API_URL}}/api/v1/alert_groups/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ - { - "id": "I68T24C13IFW1", - "integration_id": "CFRPV98RPR1U8", - "route_id": "RIYGUJXCPFHXY", - "alerts_count": 3, - "state": "resolved", - "created_at": "2020-05-19T12:37:01.430444Z", - "resolved_at": "2020-05-19T13:37:01.429805Z", - "acknowledged_at": null, - "title": "Memory above 90% threshold" - } - ] + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "I68T24C13IFW1", + "integration_id": "CFRPV98RPR1U8", + "route_id": "RIYGUJXCPFHXY", + "alerts_count": 3, + "state": "resolved", + "created_at": "2020-05-19T12:37:01.430444Z", + "resolved_at": "2020-05-19T13:37:01.429805Z", + "acknowledged_at": null, + "title": "Memory above 90% threshold" + } + ] } ``` These available filter parameters should be provided as `GET` arguments: -* `route_id` -* `integration_id` +- `route_id` +- `integration_id` **HTTP request** @@ -57,12 +59,12 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \ }' ``` -|Parameter | Required | Description | -|--------- |:--------:|:------------| -`mode` | No | Default setting is `wipe`. `wipe` will remove the payload of all Grafana OnCall group alerts. This is useful if you sent sensitive data to OnCall. All metadata will remain. `DELETE` will trigger the removal of alert groups, alerts, and all related metadata. It will also remove alert group notifications in Slack and other destinations. +| Parameter | Required | Description | +| --------- | :------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mode` | No | Default setting is `wipe`. `wipe` will remove the payload of all Grafana OnCall group alerts. This is useful if you sent sensitive data to OnCall. All metadata will remain. `DELETE` will trigger the removal of alert groups, alerts, and all related metadata. It will also remove alert group notifications in Slack and other destinations. | ->**NOTE:** `DELETE` can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs such as Slack. Please check objects using `GET` to be sure the data is removed. +> **NOTE:** `DELETE` can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs such as Slack. Please check objects using `GET` to be sure the data is removed. **HTTP request** -`DELETE {{API_URL}}/api/v1/alert_groups/` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/alert_groups/` diff --git a/docs/sources/oncall-api-reference/alerts.md b/docs/sources/oncall-api-reference/alerts.md index f0c65a38..ca67add1 100644 --- a/docs/sources/oncall-api-reference/alerts.md +++ b/docs/sources/oncall-api-reference/alerts.md @@ -1,8 +1,10 @@ -+++ -title = "Alerts HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/alerts"] -weight = 100 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/alerts/ + - /docs/oncall/latest/oncall-api-reference/alerts/ +title: Alerts HTTP API +weight: 100 +--- # List Alerts @@ -10,101 +12,101 @@ weight = 100 curl "{{API_URL}}/api/v1/alerts/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 3, - "next": null, - "previous": null, - "results": [ - { - "id": "AA74DN7T4JQB6", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-05-11T20:07:43Z", - "payload": { - "state": "alerting", - "title": "[Alerting] Test notification", - "ruleId": 0, - "message": "Someone is testing the alert notification within Grafana.", - "ruleUrl": "{{API_URL}}/", - "ruleName": "Test notification", - "evalMatches": [ - { - "tags": null, - "value": 100, - "metric": "High value" - }, - { - "tags": null, - "value": 200, - "metric": "Higher Value" - } - ] - } - }, - { - "id": "AR9SSYFKE2PV7", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-05-11T20:07:54Z", - "payload": { - "state": "alerting", - "title": "[Alerting] Test notification", - "ruleId": 0, - "message": "Someone is testing the alert notification within Grafana.", - "ruleUrl": "{{API_URL}}/", - "ruleName": "Test notification", - "evalMatches": [ - { - "tags": null, - "value": 100, - "metric": "High value" - }, - { - "tags": null, - "value": 200, - "metric": "Higher Value" - } - ] - } - }, - { - "id": "AWJQSGEYYUFGH", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-05-11T20:07:58Z", - "payload": { - "state": "alerting", - "title": "[Alerting] Test notification", - "ruleId": 0, - "message": "Someone is testing the alert notification within Grafana.", - "ruleUrl": "{{API_URL}}/", - "ruleName": "Test notification", - "evalMatches": [ - { - "tags": null, - "value": 100, - "metric": "High value" - }, - { - "tags": null, - "value": 200, - "metric": "Higher Value" - } - ] - } - } - ] + "count": 3, + "next": null, + "previous": null, + "results": [ + { + "id": "AA74DN7T4JQB6", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-05-11T20:07:43Z", + "payload": { + "state": "alerting", + "title": "[Alerting] Test notification", + "ruleId": 0, + "message": "Someone is testing the alert notification within Grafana.", + "ruleUrl": "{{API_URL}}/", + "ruleName": "Test notification", + "evalMatches": [ + { + "tags": null, + "value": 100, + "metric": "High value" + }, + { + "tags": null, + "value": 200, + "metric": "Higher Value" + } + ] + } + }, + { + "id": "AR9SSYFKE2PV7", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-05-11T20:07:54Z", + "payload": { + "state": "alerting", + "title": "[Alerting] Test notification", + "ruleId": 0, + "message": "Someone is testing the alert notification within Grafana.", + "ruleUrl": "{{API_URL}}/", + "ruleName": "Test notification", + "evalMatches": [ + { + "tags": null, + "value": 100, + "metric": "High value" + }, + { + "tags": null, + "value": 200, + "metric": "Higher Value" + } + ] + } + }, + { + "id": "AWJQSGEYYUFGH", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-05-11T20:07:58Z", + "payload": { + "state": "alerting", + "title": "[Alerting] Test notification", + "ruleId": 0, + "message": "Someone is testing the alert notification within Grafana.", + "ruleUrl": "{{API_URL}}/", + "ruleName": "Test notification", + "evalMatches": [ + { + "tags": null, + "value": 100, + "metric": "High value" + }, + { + "tags": null, + "value": 200, + "metric": "Higher Value" + } + ] + } + } + ] } ``` The following available filter parameters should be provided as `GET` arguments: -* `alert_group_id` -* `search`—string-based inclusion search by alert payload +- `alert_group_id` +- `search`—string-based inclusion search by alert payload **HTTP request** -`GET {{API_URL}}/api/v1/alerts/` \ No newline at end of file +`GET {{API_URL}}/api/v1/alerts/` diff --git a/docs/sources/oncall-api-reference/escalation_chains.md b/docs/sources/oncall-api-reference/escalation_chains.md index e11d59dc..24a7eb50 100644 --- a/docs/sources/oncall-api-reference/escalation_chains.md +++ b/docs/sources/oncall-api-reference/escalation_chains.md @@ -1,8 +1,10 @@ -+++ -title = "Escalation Chains HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/escalation_chains"] -weight = 200 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/escalation_chains/ + - /docs/oncall/latest/oncall-api-reference/escalation_chains/ +title: Escalation Chains HTTP API +weight: 200 +--- # Create an escalation chain @@ -20,16 +22,16 @@ The above command returns JSON structured in the following way: ```json { - "id": "FWDL7M6N6I9HE", - "name": "example-chain", - "team_id": null + "id": "FWDL7M6N6I9HE", + "name": "example-chain", + "team_id": null } ``` -| Parameter | Required | Description | -|-----------|:--------:|:------------| -| name | yes | Name of the escalation chain | -| team_id | no | ID of the team | +| Parameter | Required | Description | +| --------- | :------: | :--------------------------- | +| name | yes | Name of the escalation chain | +| team_id | no | ID of the team | **HTTP request** @@ -48,9 +50,9 @@ The above command returns JSON structured in the following way: ```json { - "id": "F5JU6KJET33FE", - "name": "default", - "team_id": null + "id": "F5JU6KJET33FE", + "name": "default", + "team_id": null } ``` @@ -64,23 +66,23 @@ The above command returns JSON structured in the following way: curl "{{API_URL}}/api/v1/escalation_chains/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 2, - "next": null, - "previous": null, - "results": [ - { - "id": "F5JU6KJET33FE", - "name": "default", - "team_id": null - } - ] + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": "F5JU6KJET33FE", + "name": "default", + "team_id": null + } + ] } ``` @@ -99,4 +101,4 @@ curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/escalation_chains//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/escalation_chains//` diff --git a/docs/sources/oncall-api-reference/escalation_policies.md b/docs/sources/oncall-api-reference/escalation_policies.md index c2ee1ffb..bc1262e4 100644 --- a/docs/sources/oncall-api-reference/escalation_policies.md +++ b/docs/sources/oncall-api-reference/escalation_policies.md @@ -1,8 +1,10 @@ -+++ -title = "Escalation Policies HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/escalation_policies"] -weight = 300 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/escalation_policies/ + - /docs/oncall/latest/oncall-api-reference/escalation_policies/ +title: Escalation Policies HTTP API +weight: 300 +--- # Create an escalation policy @@ -22,28 +24,28 @@ The above command returns JSON structured in the following way: ```json { - "id": "E3GA6SJETWWJS", - "escalation_chain_id": "F5JU6KJET33FE", - "position": 0, - "type": "wait", - "duration": 60 + "id": "E3GA6SJETWWJS", + "escalation_chain_id": "F5JU6KJET33FE", + "position": 0, + "type": "wait", + "duration": 60 } ``` -|Parameter | Required | Description | -|----------|:--------:|:------------| -`escalation_chain_id` | Yes | Each escalation policy is assigned to a specific escalation chain. -`position` | Optional | Escalation policies execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down in the list. -`type` | Yes | One of: `wait`, `notify_persons`, `notify_person_next_each_time`, `notify_on_call_from_schedule`, `notify_user_group`, `trigger_action`, `resolve`, `notify_whole_channel`, `notify_if_time_from_to`. -`duration` | Optional | The duration, in seconds, when type `wait` is chosen. -`important` | Optional | Default is `false`. Will assign "important" to personal notification rules if `true`. This can be used to distinguish alerts on which you want to be notified immediately by phone. Applicable for types `notify_persons`, `notify_on_call_from_schedule`, and `notify_user_group`. -`action_to_trigger` | If type = `trigger_action` | ID of an action, or webhook. -`group_to_notify` | If type = `notify_user_group` | ID of a `User Group`. -`persons_to_notify` | If type = `notify_persons` | List of user IDs. -`persons_to_notify_next_each_time` | If type = `notify_person_next_each_time` | List of user IDs. -`notify_on_call _from_schedule` | If type = `notify_on_call_from_schedule` | ID of a Schedule. -`notify_if_time_from` | If type = `notify_if_time_from_to` | UTC time represents the beginning of the time period, for example `09:00:00Z`. -`notify_if_time_to` | If type = `notify_if_time_from_to` | UTC time represents the end of the time period, for example `18:00:00Z`. +| Parameter | Required | Description | +| ---------------------------------- | :--------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `escalation_chain_id` | Yes | Each escalation policy is assigned to a specific escalation chain. | +| `position` | Optional | Escalation policies execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down in the list. | +| `type` | Yes | One of: `wait`, `notify_persons`, `notify_person_next_each_time`, `notify_on_call_from_schedule`, `notify_user_group`, `trigger_action`, `resolve`, `notify_whole_channel`, `notify_if_time_from_to`. | +| `duration` | Optional | The duration, in seconds, when type `wait` is chosen. | +| `important` | Optional | Default is `false`. Will assign "important" to personal notification rules if `true`. This can be used to distinguish alerts on which you want to be notified immediately by phone. Applicable for types `notify_persons`, `notify_on_call_from_schedule`, and `notify_user_group`. | +| `action_to_trigger` | If type = `trigger_action` | ID of an action, or webhook. | +| `group_to_notify` | If type = `notify_user_group` | ID of a `User Group`. | +| `persons_to_notify` | If type = `notify_persons` | List of user IDs. | +| `persons_to_notify_next_each_time` | If type = `notify_person_next_each_time` | List of user IDs. | +| `notify_on_call _from_schedule` | If type = `notify_on_call_from_schedule` | ID of a Schedule. | +| `notify_if_time_from` | If type = `notify_if_time_from_to` | UTC time represents the beginning of the time period, for example `09:00:00Z`. | +| `notify_if_time_to` | If type = `notify_if_time_from_to` | UTC time represents the end of the time period, for example `18:00:00Z`. | **HTTP request** @@ -62,11 +64,11 @@ The above command returns JSON structured in the following way: ```json { - "id": "E3GA6SJETWWJS", - "escalation_chain_id": "F5JU6KJET33FE", - "position": 0, - "type": "wait", - "duration": 60 + "id": "E3GA6SJETWWJS", + "escalation_chain_id": "F5JU6KJET33FE", + "position": 0, + "type": "wait", + "duration": 60 } ``` @@ -80,40 +82,38 @@ The above command returns JSON structured in the following way: curl "{{API_URL}}/api/v1/escalation_policies/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 2, - "next": null, - "previous": null, - "results": [ - { - "id": "E3GA6SJETWWJS", - "escalation_chain_id": "F5JU6KJET33FE", - "position": 0, - "type": "wait", - "duration": 60 - }, - { - "id": "E5JJTU52M5YM4", - "escalation_chain_id": "F5JU6KJET33FE", - "position": 1, - "type": "notify_person_next_each_time", - "persons_to_notify_next_each_time": [ - "U4DNY931HHJS5" - ] - } - ] + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": "E3GA6SJETWWJS", + "escalation_chain_id": "F5JU6KJET33FE", + "position": 0, + "type": "wait", + "duration": 60 + }, + { + "id": "E5JJTU52M5YM4", + "escalation_chain_id": "F5JU6KJET33FE", + "position": 1, + "type": "notify_person_next_each_time", + "persons_to_notify_next_each_time": ["U4DNY931HHJS5"] + } + ] } ``` The following available filter parameter should be provided as a `GET` argument: -* `escalation_chain_id` +- `escalation_chain_id` **HTTP request** @@ -130,4 +130,4 @@ curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/escalation_policies//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/escalation_policies//` diff --git a/docs/sources/oncall-api-reference/integrations.md b/docs/sources/oncall-api-reference/integrations.md index 4e5ed02b..d6d7e729 100644 --- a/docs/sources/oncall-api-reference/integrations.md +++ b/docs/sources/oncall-api-reference/integrations.md @@ -1,8 +1,10 @@ -+++ -title = "Integrations HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/integrations/"] -weight = 500 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/integrations/ + - /docs/oncall/latest/oncall-api-reference/integrations/ +title: Integrations HTTP API +weight: 500 +--- # Create an integration @@ -20,52 +22,52 @@ The above command returns JSON structured in the following way: ```json { - "id": "CFRPV98RPR1U8", - "name": "Grafana :blush:", - "team_id": null, - "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", - "type": "grafana", - "default_route": { - "id": "RVBE4RKQSCGJ2", - "escalation_chain_id": "F5JU6KJET33FE", - "slack": { - "channel_id": "CH23212D" - } - }, - "templates": { - "grouping_key": null, - "resolve_signal": null, - "slack": { - "title": null, - "message": null, - "image_url": null - }, - "web": { - "title": null, - "message": null, - "image_url": null - }, - "email": { - "title": null, - "message": null - }, - "sms": { - "title": null - }, - "phone_call": { - "title": null - }, - "telegram": { - "title": null, - "message": null, - "image_url": null - } + "id": "CFRPV98RPR1U8", + "name": "Grafana :blush:", + "team_id": null, + "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", + "type": "grafana", + "default_route": { + "id": "RVBE4RKQSCGJ2", + "escalation_chain_id": "F5JU6KJET33FE", + "slack": { + "channel_id": "CH23212D" } + }, + "templates": { + "grouping_key": null, + "resolve_signal": null, + "slack": { + "title": null, + "message": null, + "image_url": null + }, + "web": { + "title": null, + "message": null, + "image_url": null + }, + "email": { + "title": null, + "message": null + }, + "sms": { + "title": null + }, + "phone_call": { + "title": null + }, + "telegram": { + "title": null, + "message": null, + "image_url": null + } + } } ``` Integrations are sources of alerts and alert groups for Grafana OnCall. -For example, to learn how to integrate Grafana OnCall with Alertmanager see [Alertmanager]({{< relref "../integrations/add-alertmanager" >}}). +For example, to learn how to integrate Grafana OnCall with Alertmanager see [Alertmanager]({{< relref "../integrations/add-alertmanager" >}}). **HTTP request** @@ -84,51 +86,51 @@ The above command returns JSON structured in the following way: ```json { - "id": "CFRPV98RPR1U8", - "name": "Grafana :blush:", - "team_id": null, - "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", - "type": "grafana", - "default_route": { - "id": "RVBE4RKQSCGJ2", - "escalation_chain_id": "F5JU6KJET33FE", - "slack": { - "channel_id": "CH23212D" - } - }, - "templates": { - "grouping_key": null, - "resolve_signal": null, - "slack": { - "title": null, - "message": null, - "image_url": null - }, - "web": { - "title": null, - "message": null, - "image_url": null - }, - "email": { - "title": null, - "message": null - }, - "sms": { - "title": null - }, - "phone_call": { - "title": null - }, - "telegram": { - "title": null, - "message": null, - "image_url": null - } + "id": "CFRPV98RPR1U8", + "name": "Grafana :blush:", + "team_id": null, + "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", + "type": "grafana", + "default_route": { + "id": "RVBE4RKQSCGJ2", + "escalation_chain_id": "F5JU6KJET33FE", + "slack": { + "channel_id": "CH23212D" } + }, + "templates": { + "grouping_key": null, + "resolve_signal": null, + "slack": { + "title": null, + "message": null, + "image_url": null + }, + "web": { + "title": null, + "message": null, + "image_url": null + }, + "email": { + "title": null, + "message": null + }, + "sms": { + "title": null + }, + "phone_call": { + "title": null + }, + "telegram": { + "title": null, + "message": null, + "image_url": null + } + } } ``` -This endpoint retrieves an integration. Integrations are sources of alerts and alert groups for Grafana OnCall. +This endpoint retrieves an integration. Integrations are sources of alerts and alert groups for Grafana OnCall. **HTTP request** @@ -147,54 +149,54 @@ The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ - { - "id": "CFRPV98RPR1U8", - "name": "Grafana :blush:", - "team_id": null, - "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", - "type": "grafana", - "default_route": { - "id": "RVBE4RKQSCGJ2", - "escalation_chain_id": "F5JU6KJET33FE", - "slack": { - "channel_id": "CH23212D" - } - }, - "templates": { - "grouping_key": null, - "resolve_signal": null, - "slack": { - "title": null, - "message": null, - "image_url": null - }, - "web": { - "title": null, - "message": null, - "image_url": null - }, - "email": { - "title": null, - "message": null - }, - "sms": { - "title": null - }, - "phone_call": { - "title": null - }, - "telegram": { - "title": null, - "message": null, - "image_url": null - } - } + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "CFRPV98RPR1U8", + "name": "Grafana :blush:", + "team_id": null, + "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", + "type": "grafana", + "default_route": { + "id": "RVBE4RKQSCGJ2", + "escalation_chain_id": "F5JU6KJET33FE", + "slack": { + "channel_id": "CH23212D" } - ] + }, + "templates": { + "grouping_key": null, + "resolve_signal": null, + "slack": { + "title": null, + "message": null, + "image_url": null + }, + "web": { + "title": null, + "message": null, + "image_url": null + }, + "email": { + "title": null, + "message": null + }, + "sms": { + "title": null + }, + "phone_call": { + "title": null + }, + "telegram": { + "title": null, + "message": null, + "image_url": null + } + } + } + ] } ``` @@ -226,47 +228,47 @@ The above command returns JSON structured in the following way: ```json { - "id": "CFRPV98RPR1U8", - "name": "Grafana :blush:", - "team_id": null, - "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", - "type": "grafana", - "default_route": { - "id": "RVBE4RKQSCGJ2", - "escalation_chain_id": "F5JU6KJET33FE", - "slack": { - "channel_id": "CH23212D" - } - }, - "templates": { - "grouping_key": null, - "resolve_signal": null, - "slack": { - "title": null, - "message": null, - "image_url": null - }, - "web": { - "title": null, - "message": null, - "image_url": null - }, - "email": { - "title": null, - "message": null - }, - "sms": { - "title": null - }, - "phone_call": { - "title": null - }, - "telegram": { - "title": null, - "message": null, - "image_url": null - } + "id": "CFRPV98RPR1U8", + "name": "Grafana :blush:", + "team_id": null, + "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/", + "type": "grafana", + "default_route": { + "id": "RVBE4RKQSCGJ2", + "escalation_chain_id": "F5JU6KJET33FE", + "slack": { + "channel_id": "CH23212D" } + }, + "templates": { + "grouping_key": null, + "resolve_signal": null, + "slack": { + "title": null, + "message": null, + "image_url": null + }, + "web": { + "title": null, + "message": null, + "image_url": null + }, + "email": { + "title": null, + "message": null + }, + "sms": { + "title": null + }, + "phone_call": { + "title": null + }, + "telegram": { + "title": null, + "message": null, + "image_url": null + } + } } ``` @@ -275,6 +277,7 @@ The above command returns JSON structured in the following way: `PUT {{API_URL}}/api/v1/integrations//` # Delete integration + Deleted integrations will stop recording new alerts from monitoring. Integration removal won't trigger removal of related alert groups or alerts. ```shell diff --git a/docs/sources/oncall-api-reference/on_call_shifts.md b/docs/sources/oncall-api-reference/on_call_shifts.md index fc78a9ed..c3f3a5d0 100644 --- a/docs/sources/oncall-api-reference/on_call_shifts.md +++ b/docs/sources/oncall-api-reference/on_call_shifts.md @@ -1,8 +1,10 @@ -+++ -title = "OnCall shifts HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/on_call_shifts/"] -weight = 600 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/on_call_shifts/ + - /docs/oncall/latest/oncall-api-reference/on_call_shifts/ +title: OnCall shifts HTTP API +weight: 600 +--- # Create an OnCall shift @@ -29,38 +31,36 @@ The above command returns JSON structured in the following way: ```json { - "id": "OH3V5FYQEYJ6M", - "name": "Demo single event", - "type": "single_event", - "team_id": null, - "time_zone": null, - "level": 0, - "start": "2020-09-10T08:00:00", - "duration": 10800, - "users": [ - "U4DNY931HHJS5" - ] + "id": "OH3V5FYQEYJ6M", + "name": "Demo single event", + "type": "single_event", + "team_id": null, + "time_zone": null, + "level": 0, + "start": "2020-09-10T08:00:00", + "duration": 10800, + "users": ["U4DNY931HHJS5"] } ``` -| Parameter | Unique | Required | Description | -|-----------|:------:|:--------:|:------------| -`name` | Yes | Yes | On-call shift name. -`type` | No | Yes | One of: `single_event`, `recurrent_event`, `rolling_users`. -`team_id` | No | ID of the team. -`time_zone` | No | Optional | On-call shift time zone. Default is local schedule time zone. **This field will override the schedule time zone if changed**. For more information see [time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). -`level` | No | Optional | Priority level. The higher the value, the higher the priority. If two events overlap in one schedule, Grafana OnCall will choose the event with higher level. For example: Alex is on-call from 8AM till 11AM with level 1, Bob is on-call from 9AM till 11AM with level 2. At 10AM Grafana OnCall will notify Bob. At 8AM OnCall will notify Alex. -`start` | No | Yes | Start time of the on-call shift. This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example "2020-09-05T08:00:00"). -`duration` | No | Yes | Duration of the event. -`frequency` | No | If type = `recurrent_event` or `rolling_users` | One of: `daily`, `weekly`, `monthly`. -`interval` | No | Optional | This parameter takes a positive integer that represents the intervals that the recurrence rule repeats. -`week_start` | No | Optional | Start day of the week in iCal format. One of: `SU` (Sunday), `MO` (Monday), `TU` (Tuesday), `WE` (Wednesday), `TH` (Thursday), `FR` (Friday), `SA` (Saturday). Default: `SU`. -`by_day` | No | Optional | List of days in iCal format. Valid values are: `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA`. -`by_month` | No | Optional | List of months. Valid values are `1` to `12`. -`by_monthday` | No | Optional | List of days of the month. Valid values are `1` to `31` or `-31` to `-1`. -`users` | No | Optional | List of on-call users. -`rolling_users` | No | Optional | List of lists with on-call users (for `rolling_users` event type). Grafana OnCall will iterate over lists of users for every time frame specified in `frequency`. For example: there are two lists of users in `rolling_users` : [[Alex, Bob], [Alice]] and `frequency` = `daily` . This means that the first day Alex and Bob will be notified. The next day: Alice. The day after: Alex and Bob again and so on. -`start_rotation_from_user_index` | No | Optional | Index of the list of users in `rolling_users`, from which on-call rotation starts. By default, the start index is `0` +| Parameter | Unique | Required | Description | +| -------------------------------- | :----: | :--------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Yes | Yes | On-call shift name. | +| `type` | No | Yes | One of: `single_event`, `recurrent_event`, `rolling_users`. | +| `team_id` | No | ID of the team. | +| `time_zone` | No | Optional | On-call shift time zone. Default is local schedule time zone. **This field will override the schedule time zone if changed**. For more information see [time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | +| `level` | No | Optional | Priority level. The higher the value, the higher the priority. If two events overlap in one schedule, Grafana OnCall will choose the event with higher level. For example: Alex is on-call from 8AM till 11AM with level 1, Bob is on-call from 9AM till 11AM with level 2. At 10AM Grafana OnCall will notify Bob. At 8AM OnCall will notify Alex. | +| `start` | No | Yes | Start time of the on-call shift. This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example "2020-09-05T08:00:00"). | +| `duration` | No | Yes | Duration of the event. | +| `frequency` | No | If type = `recurrent_event` or `rolling_users` | One of: `daily`, `weekly`, `monthly`. | +| `interval` | No | Optional | This parameter takes a positive integer that represents the intervals that the recurrence rule repeats. | +| `week_start` | No | Optional | Start day of the week in iCal format. One of: `SU` (Sunday), `MO` (Monday), `TU` (Tuesday), `WE` (Wednesday), `TH` (Thursday), `FR` (Friday), `SA` (Saturday). Default: `SU`. | +| `by_day` | No | Optional | List of days in iCal format. Valid values are: `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA`. | +| `by_month` | No | Optional | List of months. Valid values are `1` to `12`. | +| `by_monthday` | No | Optional | List of days of the month. Valid values are `1` to `31` or `-31` to `-1`. | +| `users` | No | Optional | List of on-call users. | +| `rolling_users` | No | Optional | List of lists with on-call users (for `rolling_users` event type). Grafana OnCall will iterate over lists of users for every time frame specified in `frequency`. For example: there are two lists of users in `rolling_users` : [[Alex, Bob], [Alice]] and `frequency` = `daily` . This means that the first day Alex and Bob will be notified. The next day: Alice. The day after: Alex and Bob again and so on. | +| `start_rotation_from_user_index` | No | Optional | Index of the list of users in `rolling_users`, from which on-call rotation starts. By default, the start index is `0` | Please see [RFC 5545](https://tools.ietf.org/html/rfc5545#section-3.3.10) for more information about recurrence rules. @@ -81,17 +81,15 @@ The above command returns JSON structured in the following way: ```json { - "id": "OH3V5FYQEYJ6M", - "name": "Demo single event", - "type": "single_event", - "team_id": null, - "time_zone": null, - "level": 0, - "start": "2020-09-10T08:00:00", - "duration": 10800, - "users": [ - "U4DNY931HHJS5" - ] + "id": "OH3V5FYQEYJ6M", + "name": "Demo single event", + "type": "single_event", + "team_id": null, + "time_zone": null, + "level": 0, + "start": "2020-09-10T08:00:00", + "duration": 10800, + "users": ["U4DNY931HHJS5"] } ``` @@ -105,61 +103,53 @@ The above command returns JSON structured in the following way: curl "{{API_URL}}/api/v1/on_call_shifts/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 2, - "next": null, - "previous": null, - "results": [ - { - "id": "OH3V5FYQEYJ6M", - "name": "Demo single event", - "type": "single_event", - "team_id": null, - "time_zone": null, - "level": 0, - "start": "2020-09-10T08:00:00", - "duration": 10800, - "users": [ - "U4DNY931HHJS5" - ] - }, - { - "id": "O9WTH7CKM3KZW", - "name": "Demo recurrent event", - "type": "recurrent_event", - "team_id": null, - "time_zone": null, - "level": 0, - "start": "2020-09-10T16:00:00", - "duration": 10800, - "frequency": "weekly", - "interval": 2, - "week_start": "SU", - "by_day": [ - "MO", - "WE", - "FR" - ], - "by_month": null, - "by_monthday": null, - "users": [ - "U4DNY931HHJS5" - ] - } - ] + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": "OH3V5FYQEYJ6M", + "name": "Demo single event", + "type": "single_event", + "team_id": null, + "time_zone": null, + "level": 0, + "start": "2020-09-10T08:00:00", + "duration": 10800, + "users": ["U4DNY931HHJS5"] + }, + { + "id": "O9WTH7CKM3KZW", + "name": "Demo recurrent event", + "type": "recurrent_event", + "team_id": null, + "time_zone": null, + "level": 0, + "start": "2020-09-10T16:00:00", + "duration": 10800, + "frequency": "weekly", + "interval": 2, + "week_start": "SU", + "by_day": ["MO", "WE", "FR"], + "by_month": null, + "by_monthday": null, + "users": ["U4DNY931HHJS5"] + } + ] } ``` The following available filter parameters should be provided as `GET` arguments: -* `name` (Exact match) -* `schedule_id` (Exact match) +- `name` (Exact match) +- `schedule_id` (Exact match) **HTTP request** @@ -188,17 +178,15 @@ The above command returns JSON structured in the following way: ```json { - "id": "OH3V5FYQEYJ6M", - "name": "Demo single event", - "type": "single_event", - "team_id": null, - "time_zone": null, - "level": 0, - "start": "2020-09-10T08:00:00", - "duration": 10800, - "users": [ - "U4DNY931HHJS5" - ] + "id": "OH3V5FYQEYJ6M", + "name": "Demo single event", + "type": "single_event", + "team_id": null, + "time_zone": null, + "level": 0, + "start": "2020-09-10T08:00:00", + "duration": 10800, + "users": ["U4DNY931HHJS5"] } ``` @@ -217,4 +205,4 @@ curl "{{API_URL}}/api/v1/on_call_shifts/S3Z477AHDXTMF/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/on_call_shifts//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/on_call_shifts//` diff --git a/docs/sources/oncall-api-reference/outgoing_webhooks.md b/docs/sources/oncall-api-reference/outgoing_webhooks.md index 5e7e399f..f42d1c07 100644 --- a/docs/sources/oncall-api-reference/outgoing_webhooks.md +++ b/docs/sources/oncall-api-reference/outgoing_webhooks.md @@ -1,8 +1,10 @@ -+++ -title = "Outgoing webhooks HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/outgoing_webhooks/"] -weight = 700 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/outgoing_webhooks/ + - /docs/oncall/latest/oncall-api-reference/outgoing_webhooks/ +title: Outgoing webhooks HTTP API +weight: 700 +--- # Outgoing webhooks (actions) @@ -14,25 +16,25 @@ Used in escalation policies with type `trigger_action`. curl "{{API_URL}}/api/v1/actions/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ - { - "id": "KGEFG74LU1D8L", - "name": "Publish alert group notification to JIRA" - } - ] + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "KGEFG74LU1D8L", + "name": "Publish alert group notification to JIRA" + } + ] } ``` **HTTP request** -`GET {{API_URL}}/api/v1/actions/` \ No newline at end of file +`GET {{API_URL}}/api/v1/actions/` diff --git a/docs/sources/oncall-api-reference/personal_notification_rules.md b/docs/sources/oncall-api-reference/personal_notification_rules.md index dca60f79..2b22ec07 100644 --- a/docs/sources/oncall-api-reference/personal_notification_rules.md +++ b/docs/sources/oncall-api-reference/personal_notification_rules.md @@ -1,8 +1,10 @@ -+++ -title = "Personal Notification Rules HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/personal_notification_rules/"] -weight = 800 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/personal_notification_rules/ + - /docs/oncall/latest/oncall-api-reference/personal_notification_rules/ +title: Personal Notification Rules HTTP API +weight: 800 +--- # Post a personal notification rule @@ -21,21 +23,21 @@ The above command returns JSON structured in the following way: ```json { - "id": "NT79GA9I7E4DJ", - "user_id": "U4DNY931HHJS5", - "position": 0, - "important": false, - "type": "notify_by_sms" + "id": "NT79GA9I7E4DJ", + "user_id": "U4DNY931HHJS5", + "position": 0, + "important": false, + "type": "notify_by_sms" } ``` -| Parameter | Required | Description | -|-----------|:--------:|:------------| -`user_id` | Yes | User ID -`position` | Optional | Personal notification rules execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down on the list. -`type` | Yes | One of: `wait`, `notify_by_slack`, `notify_by_sms`, `notify_by_phone_call`, `notify_by_telegram`, `notify_by_email`. -`duration` | Optional | A time in secs when type `wait` is chosen for `type`. -`important` | Optional | Boolean value indicates if a rule is "important". Default is `false`. +| Parameter | Required | Description | +| ----------- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `user_id` | Yes | User ID | +| `position` | Optional | Personal notification rules execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down on the list. | +| `type` | Yes | One of: `wait`, `notify_by_slack`, `notify_by_sms`, `notify_by_phone_call`, `notify_by_telegram`, `notify_by_email`. | +| `duration` | Optional | A time in secs when type `wait` is chosen for `type`. | +| `important` | Optional | Boolean value indicates if a rule is "important". Default is `false`. | **HTTP request** @@ -47,19 +49,19 @@ The above command returns JSON structured in the following way: curl "{{API_URL}}/api/v1/personal_notification_rules/ND9EHN5LN1DUU/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "id": "ND9EHN5LN1DUU", - "user_id": "U4DNY931HHJS5", - "position": 1, - "duration": 300, - "important": false, - "type": "wait" + "id": "ND9EHN5LN1DUU", + "user_id": "U4DNY931HHJS5", + "position": 1, + "duration": 300, + "important": false, + "type": "wait" } ``` @@ -67,61 +69,60 @@ The above command returns JSON structured in the following way: `GET {{API_URL}}/api/v1/personal_notification_rules//` - # List personal notification rules ```shell curl "{{API_URL}}/api/v1/personal_notification_rules/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following ways: ```json { - "count": 4, - "next": null, - "previous": null, - "results": [ - { - "id": "NT79GA9I7E4DJ", - "user_id": "U4DNY931HHJS5", - "position": 0, - "important": false, - "type": "notify_by_sms" - }, - { - "id": "ND9EHN5LN1DUU", - "user_id": "U4DNY931HHJS5", - "position": 1, - "duration": 300, - "important": false, - "type": "wait" - }, - { - "id": "NEF49YQ1HNPDD", - "user_id": "U4DNY931HHJS5", - "position": 2, - "important": false, - "type": "notify_by_phone_call" - }, - { - "id": "NWAL6WFJNWDD8", - "user_id": "U4DNY931HHJS5", - "position": 0, - "important": true, - "type": "notify_by_phone_call" - } - ] + "count": 4, + "next": null, + "previous": null, + "results": [ + { + "id": "NT79GA9I7E4DJ", + "user_id": "U4DNY931HHJS5", + "position": 0, + "important": false, + "type": "notify_by_sms" + }, + { + "id": "ND9EHN5LN1DUU", + "user_id": "U4DNY931HHJS5", + "position": 1, + "duration": 300, + "important": false, + "type": "wait" + }, + { + "id": "NEF49YQ1HNPDD", + "user_id": "U4DNY931HHJS5", + "position": 2, + "important": false, + "type": "notify_by_phone_call" + }, + { + "id": "NWAL6WFJNWDD8", + "user_id": "U4DNY931HHJS5", + "position": 0, + "important": true, + "type": "notify_by_phone_call" + } + ] } ``` The following available filter parameters should be provided as `GET` arguments: -* `user_id` -* `important` +- `user_id` +- `important` **HTTP Request** @@ -129,7 +130,6 @@ The following available filter parameters should be provided as `GET` arguments: # Delete a personal notification rule - ```shell curl "{{API_URL}}/api/v1/personal_notification_rules/NWAL6WFJNWDD8/" \ --request DELETE \ @@ -139,4 +139,4 @@ curl "{{API_URL}}/api/v1/personal_notification_rules/NWAL6WFJNWDD8/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/personal_notification_rules//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/personal_notification_rules//` diff --git a/docs/sources/oncall-api-reference/postmortem_messages.md b/docs/sources/oncall-api-reference/postmortem_messages.md index d156fc71..ba3e9252 100644 --- a/docs/sources/oncall-api-reference/postmortem_messages.md +++ b/docs/sources/oncall-api-reference/postmortem_messages.md @@ -1,9 +1,11 @@ -+++ -title = "Postmortem Messages HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/postmortem_messages/"] -weight = 900 -draft = true -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/postmortem_messages/ + - /docs/oncall/latest/oncall-api-reference/postmortem_messages/ +draft: true +title: Postmortem Messages HTTP API +weight: 900 +--- # Create a postmortem message @@ -22,14 +24,14 @@ The above command returns JSON structured in the following way: ```json { - "id": "M4BTQUS3PRHYQ", - "alert_group_id": "I68T24C13IFW1", - "author": "U4DNY931HHJS5", - "source": "web", - "created_at": "2020-06-19T12:40:01.429805Z", - "text": "Demo postmortem message" + "id": "M4BTQUS3PRHYQ", + "alert_group_id": "I68T24C13IFW1", + "author": "U4DNY931HHJS5", + "source": "web", + "created_at": "2020-06-19T12:40:01.429805Z", + "text": "Demo postmortem message" } -``` +``` **HTTP request** @@ -48,12 +50,12 @@ The above command returns JSON structured in the following way: ```json { - "id": "M4BTQUS3PRHYQ", - "alert_group_id": "I68T24C13IFW1", - "author": "U4DNY931HHJS5", - "source": "web", - "created_at": "2020-06-19T12:40:01.429805Z", - "text": "Demo postmortem message" + "id": "M4BTQUS3PRHYQ", + "alert_group_id": "I68T24C13IFW1", + "author": "U4DNY931HHJS5", + "source": "web", + "created_at": "2020-06-19T12:40:01.429805Z", + "text": "Demo postmortem message" } ``` @@ -74,26 +76,25 @@ The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ - { - "id": "M4BTQUS3PRHYQ", - "alert_group_id": "I68T24C13IFW1", - "author": "U4DNY931HHJS5", - "source": "web", - "created_at": "2020-06-19T12:40:01.429805Z", - "text": "Demo postmortem message" - } - ] + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "M4BTQUS3PRHYQ", + "alert_group_id": "I68T24C13IFW1", + "author": "U4DNY931HHJS5", + "source": "web", + "created_at": "2020-06-19T12:40:01.429805Z", + "text": "Demo postmortem message" + } + ] } ``` The following available filter parameter should be provided as a `GET` argument: -* `alert_group_id` - +- `alert_group_id` **HTTP request** @@ -115,12 +116,12 @@ The above command returns JSON structured in the following way: ```json { - "id": "M4BTQUS3PRHYQ", - "alert_group_id": "I68T24C13IFW1", - "author": "U4DNY931HHJS5", - "source": "web", - "created_at": "2020-06-19T12:40:01.429805Z", - "text": "Demo postmortem message" + "id": "M4BTQUS3PRHYQ", + "alert_group_id": "I68T24C13IFW1", + "author": "U4DNY931HHJS5", + "source": "web", + "created_at": "2020-06-19T12:40:01.429805Z", + "text": "Demo postmortem message" } ``` @@ -138,4 +139,4 @@ curl "{{API_URL}}/api/v1/postmortem_messages/M4BTQUS3PRHYQ/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/postmortem_messages//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/postmortem_messages//` diff --git a/docs/sources/oncall-api-reference/postmortems.md b/docs/sources/oncall-api-reference/postmortems.md index df8580f5..95197687 100644 --- a/docs/sources/oncall-api-reference/postmortems.md +++ b/docs/sources/oncall-api-reference/postmortems.md @@ -1,9 +1,11 @@ -+++ -title = "Postmortem HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/postmortems/"] -weight = 1000 -draft = true -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/postmortems/ + - /docs/oncall/latest/oncall-api-reference/postmortems/ +draft: true +title: Postmortem HTTP API +weight: 1000 +--- # Create a postmortem @@ -22,12 +24,12 @@ The above command returns JSON structured in the following way: ```json { - "id": "P658FE5K87EWZ", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-06-19T12:37:01.430444Z", - "text": "Demo postmortem text" + "id": "P658FE5K87EWZ", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-06-19T12:37:01.430444Z", + "text": "Demo postmortem text" } -``` +``` **HTTP request** @@ -46,20 +48,20 @@ The above command returns JSON structured in the following way: ```json { - "id": "P658FE5K87EWZ", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-06-19T12:37:01.430444Z", - "text": "Demo postmortem text", - "postmortem_messages": [ - { - "id": "M4BTQUS3PRHYQ", - "alert_group_id": "I68T24C13IFW1", - "author": "U4DNY931HHJS5", - "source": "web", - "created_at": "2020-06-19T12:40:01.429805Z", - "text": "Demo postmortem message" - } - ] + "id": "P658FE5K87EWZ", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-06-19T12:37:01.430444Z", + "text": "Demo postmortem text", + "postmortem_messages": [ + { + "id": "M4BTQUS3PRHYQ", + "alert_group_id": "I68T24C13IFW1", + "author": "U4DNY931HHJS5", + "source": "web", + "created_at": "2020-06-19T12:40:01.429805Z", + "text": "Demo postmortem message" + } + ] } ``` @@ -80,33 +82,33 @@ The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "P658FE5K87EWZ", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-06-19T12:37:01.430444Z", + "text": "Demo postmortem text", + "postmortem_messages": [ { - "id": "P658FE5K87EWZ", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-06-19T12:37:01.430444Z", - "text": "Demo postmortem text", - "postmortem_messages": [ - { - "id": "M4BTQUS3PRHYQ", - "alert_group_id": "I68T24C13IFW1", - "author": "U4DNY931HHJS5", - "source": "web", - "created_at": "2020-06-19T12:40:01.429805Z", - "text": "Demo postmortem message" - } - ] + "id": "M4BTQUS3PRHYQ", + "alert_group_id": "I68T24C13IFW1", + "author": "U4DNY931HHJS5", + "source": "web", + "created_at": "2020-06-19T12:40:01.429805Z", + "text": "Demo postmortem message" } - ] + ] + } + ] } ``` The following available filter parameter should be provided with a `GET` argument: -* `alert_group_id` +- `alert_group_id` **HTTP request** @@ -128,10 +130,10 @@ The above command returns JSON structured in the following way: ```json { - "id": "P658FE5K87EWZ", - "alert_group_id": "I68T24C13IFW1", - "created_at": "2020-06-19T12:37:01.430444Z", - "text": "Demo postmortem text" + "id": "P658FE5K87EWZ", + "alert_group_id": "I68T24C13IFW1", + "created_at": "2020-06-19T12:37:01.430444Z", + "text": "Demo postmortem text" } ``` @@ -149,4 +151,4 @@ curl "{{API_URL}}/api/v1/postmortems/P658FE5K87EWZ/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/postmortems//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/postmortems//` diff --git a/docs/sources/oncall-api-reference/routes.md b/docs/sources/oncall-api-reference/routes.md index e75cb388..11a1a460 100644 --- a/docs/sources/oncall-api-reference/routes.md +++ b/docs/sources/oncall-api-reference/routes.md @@ -1,8 +1,10 @@ -+++ -title = "Routes HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/routes/"] -weight = 1100 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/routes/ + - /docs/oncall/latest/oncall-api-reference/routes/ +title: Routes HTTP API +weight: 1100 +--- # Create a route @@ -26,31 +28,31 @@ The above command returns JSON structured in the following way: ```json { - "id": "RIYGUJXCPFHXY", - "integration_id": "CFRPV98RPR1U8", - "escalation_chain_id": "F5JU6KJET33FE", - "routing_regex": "us-(east|west)", - "position": 0, - "is_the_last_route": false, - "slack": { - "channel_id": "CH23212D" - } + "id": "RIYGUJXCPFHXY", + "integration_id": "CFRPV98RPR1U8", + "escalation_chain_id": "F5JU6KJET33FE", + "routing_regex": "us-(east|west)", + "position": 0, + "is_the_last_route": false, + "slack": { + "channel_id": "CH23212D" + } } ``` Routes allow you to direct different alerts to different messenger channels and escalation chains. Useful for: -* Important/non-important alerts -* Alerts for different engineering groups -* Snoozing spam & debugging alerts +- Important/non-important alerts +- Alerts for different engineering groups +- Snoozing spam & debugging alerts -| Parameter | Unique | Required | Description | -|-----------|:------:|:--------:|:------------| -`integration_id` | No | Yes | Each route is assigned to a specific integration. -`escalation_chain_id` | No | Yes | Each route is assigned a specific escalation chain. -`routing_regex` | Yes | Yes | Python Regex query (use https://regex101.com/ for debugging). OnCall chooses the route for an alert in case there is a match inside the whole alert payload. -`position` | Yes | Optional | Route matching is performed one after another starting from position=`0`. Position=`-1` will put the route to the end of the list before `is_the_last_route`. A new route created with a position of an existing route will move the old route (and all following routes) down in the list. -`slack` | Yes | Optional | Dictionary with Slack-specific settings for a route. +| Parameter | Unique | Required | Description | +| --------------------- | :----: | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `integration_id` | No | Yes | Each route is assigned to a specific integration. | +| `escalation_chain_id` | No | Yes | Each route is assigned a specific escalation chain. | +| `routing_regex` | Yes | Yes | Python Regex query (use https://regex101.com/ for debugging). OnCall chooses the route for an alert in case there is a match inside the whole alert payload. | +| `position` | Yes | Optional | Route matching is performed one after another starting from position=`0`. Position=`-1` will put the route to the end of the list before `is_the_last_route`. A new route created with a position of an existing route will move the old route (and all following routes) down in the list. | +| `slack` | Yes | Optional | Dictionary with Slack-specific settings for a route. | **HTTP request** @@ -69,15 +71,15 @@ The above command returns JSON structured in the following way: ```json { - "id": "RIYGUJXCPFHXY", - "integration_id": "CFRPV98RPR1U8", - "escalation_chain_id": "F5JU6KJET33FE", - "routing_regex": "us-(east|west)", - "position": 0, - "is_the_last_route": false, - "slack": { - "channel_id": "CH23212D" - } + "id": "RIYGUJXCPFHXY", + "integration_id": "CFRPV98RPR1U8", + "escalation_chain_id": "F5JU6KJET33FE", + "routing_regex": "us-(east|west)", + "position": 0, + "is_the_last_route": false, + "slack": { + "channel_id": "CH23212D" + } } ``` @@ -85,7 +87,6 @@ The above command returns JSON structured in the following way: `GET {{API_URL}}/api/v1/routes//` - # List routes ```shell @@ -99,40 +100,40 @@ The above command returns JSON structured in the following way: ```json { - "count": 2, - "next": null, - "previous": null, - "results": [ - { - "id": "RIYGUJXCPFHXY", - "integration_id": "CFRPV98RPR1U8", - "escalation_chain_id": "F5JU6KJET33FE", - "routing_regex": "us-(east|west)", - "position": 0, - "is_the_last_route": false, - "slack": { - "channel_id": "CH23212D" - } - }, - { - "id": "RVBE4RKQSCGJ2", - "integration_id": "CFRPV98RPR1U8", - "escalation_chain_id": "F5JU6KJET33FE", - "routing_regex": ".*", - "position": 1, - "is_the_last_route": true, - "slack": { - "channel_id": "CH23212D" - } - } - ] + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": "RIYGUJXCPFHXY", + "integration_id": "CFRPV98RPR1U8", + "escalation_chain_id": "F5JU6KJET33FE", + "routing_regex": "us-(east|west)", + "position": 0, + "is_the_last_route": false, + "slack": { + "channel_id": "CH23212D" + } + }, + { + "id": "RVBE4RKQSCGJ2", + "integration_id": "CFRPV98RPR1U8", + "escalation_chain_id": "F5JU6KJET33FE", + "routing_regex": ".*", + "position": 1, + "is_the_last_route": true, + "slack": { + "channel_id": "CH23212D" + } + } + ] } ``` The following available filter parameters should be provided as `GET` arguments: -* `integration_id` -* `routing_regex` (Exact match) +- `integration_id` +- `routing_regex` (Exact match) **HTTP request** @@ -158,15 +159,15 @@ The above command returns JSON structured in the following way: ```json { - "id": "RIYGUJXCPFHXY", - "integration_id": "CFRPV98RPR1U8", - "escalation_chain_id": "F5JU6KJET33FE", - "routing_regex": "us-(east|west)", - "position": 0, - "is_the_last_route": false, - "slack": { - "channel_id": "CH23212D" - } + "id": "RIYGUJXCPFHXY", + "integration_id": "CFRPV98RPR1U8", + "escalation_chain_id": "F5JU6KJET33FE", + "routing_regex": "us-(east|west)", + "position": 0, + "is_the_last_route": false, + "slack": { + "channel_id": "CH23212D" + } } ``` @@ -185,4 +186,4 @@ curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/routes//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/routes//` diff --git a/docs/sources/oncall-api-reference/schedules.md b/docs/sources/oncall-api-reference/schedules.md index 22b41b3b..f8de9cb9 100644 --- a/docs/sources/oncall-api-reference/schedules.md +++ b/docs/sources/oncall-api-reference/schedules.md @@ -1,8 +1,10 @@ -+++ -title = "Schedule HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/schedules/"] -weight = 1200 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/schedules/ + - /docs/oncall/latest/oncall-api-reference/schedules/ +title: Schedule HTTP API +weight: 1200 +--- # Create a schedule @@ -25,32 +27,30 @@ The above command returns JSON structured in the following way: ```json { - "id": "SBM7DV7BKFUYU", - "name": "Demo schedule iCal", - "type": "ical", - "team_id": null, - "ical_url_primary": "https://example.com/meow_calendar.ics", - "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", - "on_call_now": [ - "U4DNY931HHJS5" - ], - "slack": { - "channel_id": "MEOW_SLACK_ID", - "user_group_id": "MEOW_SLACK_ID" - } + "id": "SBM7DV7BKFUYU", + "name": "Demo schedule iCal", + "type": "ical", + "team_id": null, + "ical_url_primary": "https://example.com/meow_calendar.ics", + "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", + "on_call_now": ["U4DNY931HHJS5"], + "slack": { + "channel_id": "MEOW_SLACK_ID", + "user_group_id": "MEOW_SLACK_ID" + } } ``` -| Parameter | Unique | Required | Description | -|-----------|:------:|:--------:|:------------| -`name` | Yes | Yes | Schedule name. -`type` | No | Yes | Schedule type. May be `ical` (used for iCalendar integration) or `calendar` (used for manually created on-call shifts). -`team_id` | No | No | ID of the team. -`time_zone` | No | Optional | Schedule time zone. Is used for manually added on-call shifts in Schedules with type `calendar`. Default time zone is `UTC`. For more information about time zones, see [time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). -`ical_url_primary` | No | If type = `ical` | URL of external iCal calendar for schedule with type `ical`. -`ical_url_overrides` | No | Optional | URL of external iCal calendar for schedule with any type. Events from this calendar override events from primary calendar or from on-call shifts. -`slack` | No | Optional | Dictionary with Slack-specific settings for a schedule. Includes `channel_id` and `user_group_id` fields, that take a channel ID and a user group ID from Slack. -`shifts` | No | Optional | List of shifts. Used for manually added on-call shifts in Schedules with type `calendar`. +| Parameter | Unique | Required | Description | +| -------------------- | :----: | :--------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Yes | Yes | Schedule name. | +| `type` | No | Yes | Schedule type. May be `ical` (used for iCalendar integration) or `calendar` (used for manually created on-call shifts). | +| `team_id` | No | No | ID of the team. | +| `time_zone` | No | Optional | Schedule time zone. Is used for manually added on-call shifts in Schedules with type `calendar`. Default time zone is `UTC`. For more information about time zones, see [time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | +| `ical_url_primary` | No | If type = `ical` | URL of external iCal calendar for schedule with type `ical`. | +| `ical_url_overrides` | No | Optional | URL of external iCal calendar for schedule with any type. Events from this calendar override events from primary calendar or from on-call shifts. | +| `slack` | No | Optional | Dictionary with Slack-specific settings for a schedule. Includes `channel_id` and `user_group_id` fields, that take a channel ID and a user group ID from Slack. | +| `shifts` | No | Optional | List of shifts. Used for manually added on-call shifts in Schedules with type `calendar`. | **HTTP request** @@ -69,19 +69,17 @@ The above command returns JSON structured in the following way: ```json { - "id": "SBM7DV7BKFUYU", - "name": "Demo schedule iCal", - "type": "ical", - "team_id": null, - "ical_url_primary": "https://example.com/meow_calendar.ics", - "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", - "on_call_now": [ - "U4DNY931HHJS5" - ], - "slack": { - "channel_id": "MEOW_SLACK_ID", - "user_group_id": "MEOW_SLACK_ID" - } + "id": "SBM7DV7BKFUYU", + "name": "Demo schedule iCal", + "type": "ical", + "team_id": null, + "ical_url_primary": "https://example.com/meow_calendar.ics", + "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", + "on_call_now": ["U4DNY931HHJS5"], + "slack": { + "channel_id": "MEOW_SLACK_ID", + "user_group_id": "MEOW_SLACK_ID" + } } ``` @@ -95,58 +93,51 @@ The above command returns JSON structured in the following way: curl "{{API_URL}}/api/v1/schedules/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 2, - "next": null, - "previous": null, - "results": [ - { - "id": "SBM7DV7BKFUYU", - "name": "Demo schedule iCal", - "type": "ical", - "team_id": null, - "ical_url_primary": "https://example.com/meow_calendar.ics", - "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", - "on_call_now": [ - "U4DNY931HHJS5" - ], - "slack": { - "channel_id": "MEOW_SLACK_ID", - "user_group_id": "MEOW_SLACK_ID" - } - }, - { - "id": "S3Z477AHDXTMF", - "name": "Demo schedule Calendar", - "type": "calendar", - "team_id": null, - "time_zone": "America/New_York", - "on_call_now": [ - "U4DNY931HHJS5" - ], - "shifts": [ - "OH3V5FYQEYJ6M", - "O9WTH7CKM3KZW" - ], - "ical_url_overrides": null, - "slack": { - "channel_id": "MEOW_SLACK_ID", - "user_group_id": "MEOW_SLACK_ID" - } - } - ] + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": "SBM7DV7BKFUYU", + "name": "Demo schedule iCal", + "type": "ical", + "team_id": null, + "ical_url_primary": "https://example.com/meow_calendar.ics", + "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", + "on_call_now": ["U4DNY931HHJS5"], + "slack": { + "channel_id": "MEOW_SLACK_ID", + "user_group_id": "MEOW_SLACK_ID" + } + }, + { + "id": "S3Z477AHDXTMF", + "name": "Demo schedule Calendar", + "type": "calendar", + "team_id": null, + "time_zone": "America/New_York", + "on_call_now": ["U4DNY931HHJS5"], + "shifts": ["OH3V5FYQEYJ6M", "O9WTH7CKM3KZW"], + "ical_url_overrides": null, + "slack": { + "channel_id": "MEOW_SLACK_ID", + "user_group_id": "MEOW_SLACK_ID" + } + } + ] } ``` The following available filter parameter should be provided as a `GET` argument: -* `name` (Exact match) +- `name` (Exact match) **HTTP request** @@ -172,19 +163,17 @@ The above command returns JSON structured in the following way: ```json { - "id": "SBM7DV7BKFUYU", - "name": "Demo schedule iCal", - "type": "ical", - "team_id": null, - "ical_url_primary": "https://example.com/meow_calendar.ics", - "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", - "on_call_now": [ - "U4DNY931HHJS5" - ], - "slack": { - "channel_id": "MEOW_SLACK_ID", - "user_group_id": "MEOW_SLACK_ID" - } + "id": "SBM7DV7BKFUYU", + "name": "Demo schedule iCal", + "type": "ical", + "team_id": null, + "ical_url_primary": "https://example.com/meow_calendar.ics", + "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics", + "on_call_now": ["U4DNY931HHJS5"], + "slack": { + "channel_id": "MEOW_SLACK_ID", + "user_group_id": "MEOW_SLACK_ID" + } } ``` @@ -203,4 +192,4 @@ curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \ **HTTP request** -`DELETE {{API_URL}}/api/v1/schedules//` \ No newline at end of file +`DELETE {{API_URL}}/api/v1/schedules//` diff --git a/docs/sources/oncall-api-reference/slack_channels.md b/docs/sources/oncall-api-reference/slack_channels.md index 8426cbfc..6dda924b 100644 --- a/docs/sources/oncall-api-reference/slack_channels.md +++ b/docs/sources/oncall-api-reference/slack_channels.md @@ -1,8 +1,10 @@ -+++ -title = "Slack Channels HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/slack_channels/"] -weight = 1300 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/slack_channels/ + - /docs/oncall/latest/oncall-api-reference/slack_channels/ +title: Slack Channels HTTP API +weight: 1300 +--- # List Slack Channels @@ -10,29 +12,29 @@ weight = 1300 curl "{{API_URL}}/api/v1/slack_channels/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ - { - "name": "meow_channel", - "slack_id": "MEOW_SLACK_ID" - } - ] + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "name": "meow_channel", + "slack_id": "MEOW_SLACK_ID" + } + ] } ``` The following available filter parameter should be provided as a `GET` argument: -* `channel_name` +- `channel_name` **HTTP Request** -`GET {{API_URL}}/api/v1/slack_channels/` \ No newline at end of file +`GET {{API_URL}}/api/v1/slack_channels/` diff --git a/docs/sources/oncall-api-reference/user_groups.md b/docs/sources/oncall-api-reference/user_groups.md index a336b1db..7fdef887 100644 --- a/docs/sources/oncall-api-reference/user_groups.md +++ b/docs/sources/oncall-api-reference/user_groups.md @@ -1,46 +1,49 @@ -+++ -title = "OnCall User Groups HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/user_groups/"] -weight = 1400 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/user_groups/ + - /docs/oncall/latest/oncall-api-reference/user_groups/ +title: OnCall User Groups HTTP API +weight: 1400 +--- + # List user groups ```shell curl "{{API_URL}}/api/v1/user_groups/" \ --request GET \ --header "Authorization: meowmeowmeow" \ - --header "Content-Type: application/json" + --header "Content-Type: application/json" ``` The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ - { - "id": "GPFAPH7J7BKJB", - "type": "slack_based", - "slack": { - "id": "MEOW_SLACK_ID", - "name": "Meow Group", - "handle": "meow_group" - } - } - ] + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "GPFAPH7J7BKJB", + "type": "slack_based", + "slack": { + "id": "MEOW_SLACK_ID", + "name": "Meow Group", + "handle": "meow_group" + } + } + ] } ``` -| Parameter | Unique | Description | -|-----------|:------:|:------------| -`id` | Yes| User Group ID -`type` | No | [Slack-defined user groups](https://slack.com/intl/en-ru/help/articles/212906697-Create-a-user-group) -`slack` | No | Metadata retrieved from Slack. +| Parameter | Unique | Description | +| --------- | :----: | :---------------------------------------------------------------------------------------------------- | +| `id` | Yes | User Group ID | +| `type` | No | [Slack-defined user groups](https://slack.com/intl/en-ru/help/articles/212906697-Create-a-user-group) | +| `slack` | No | Metadata retrieved from Slack. | **HTTP request** -`GET {{API_URL}}/api/v1/user_groups/` \ No newline at end of file +`GET {{API_URL}}/api/v1/user_groups/` diff --git a/docs/sources/oncall-api-reference/users.md b/docs/sources/oncall-api-reference/users.md index 9dde2cfb..a64514dc 100644 --- a/docs/sources/oncall-api-reference/users.md +++ b/docs/sources/oncall-api-reference/users.md @@ -1,35 +1,37 @@ -+++ -title = "Grafana OnCall Users HTTP API" -aliases = ["/docs/grafana-cloud/oncall/oncall-api-reference/users/"] -weight = 1500 -+++ +--- +aliases: + - /docs/grafana-cloud/oncall/oncall-api-reference/users/ + - /docs/oncall/latest/oncall-api-reference/users/ +title: Grafana OnCall Users HTTP API +weight: 1500 +--- # Get a user This endpoint retrieves the user object. -```shell +````shell ```shell curl "{{API_URL}}/api/v1/users/current/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "Content-Type: application/json" -``` +```` The above command returns JSON structured in the following way: ```json { - "id": "U4DNY931HHJS5", - "email": "public-api-demo-user-1@grafana.com", - "slack": [ - { - "user_id": "UALEXSLACKDJPK", - "team_id": "TALEXSLACKDJPK" - } - ], - "username": "alex", - "role": "admin" + "id": "U4DNY931HHJS5", + "email": "public-api-demo-user-1@grafana.com", + "slack": [ + { + "user_id": "UALEXSLACKDJPK", + "team_id": "TALEXSLACKDJPK" + } + ], + "username": "alex", + "role": "admin" } ``` @@ -37,15 +39,15 @@ The above command returns JSON structured in the following way: `GET {{API_URL}}/api/v1/users//` -Use `{{API_URL}}/api/v1/users/current` to retrieve the current user. +Use `{{API_URL}}/api/v1/users/current` to retrieve the current user. -| Parameter | Unique | Description | -|-----------|:------:|:------------| -`id` | Yes/org | User ID -`email` | Yes/org | User e-mail -`slack` | Yes/org | List of user IDs from connected Slack. User linking key is e-mail. -`username` | Yes/org | User username -`role` | No | One of: `user`, `observer`, `admin`. +| Parameter | Unique | Description | +| ---------- | :-----: | :----------------------------------------------------------------- | +| `id` | Yes/org | User ID | +| `email` | Yes/org | User e-mail | +| `slack` | Yes/org | List of user IDs from connected Slack. User linking key is e-mail. | +| `username` | Yes/org | User username | +| `role` | No | One of: `user`, `observer`, `admin`. | # List Users @@ -60,23 +62,23 @@ The above command returns JSON structured in the following way: ```json { - "count": 1, - "next": null, - "previous": null, - "results": [ + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "U4DNY931HHJS5", + "email": "public-api-demo-user-1@grafana.com", + "slack": [ { - "id": "U4DNY931HHJS5", - "email": "public-api-demo-user-1@grafana.com", - "slack": [ - { - "user_id": "UALEXSLACKDJPK", - "team_id": "TALEXSLACKDJPK" - } - ], - "username": "alex", - "role": "admin" + "user_id": "UALEXSLACKDJPK", + "team_id": "TALEXSLACKDJPK" } - ] + ], + "username": "alex", + "role": "admin" + } + ] } ``` @@ -84,8 +86,8 @@ This endpoint retrieves all users. The following available filter parameter should be provided as a `GET` argument: -* `username` (Exact match) +- `username` (Exact match) **HTTP request** -`GET {{API_URL}}/api/v1/users/` \ No newline at end of file +`GET {{API_URL}}/api/v1/users/` From eb87a57b43f8a4864baab36a9af3339743653520 Mon Sep 17 00:00:00 2001 From: Matvey Kukuy Date: Mon, 13 Jun 2022 12:11:38 +0300 Subject: [PATCH 8/9] Open Source page --- docs/Makefile | 2 +- docs/README.md | 2 +- docs/sources/open-source.md | 174 ++++++++++++++++++++++++++++++++++++ 3 files changed, 176 insertions(+), 2 deletions(-) create mode 100644 docs/sources/open-source.md diff --git a/docs/Makefile b/docs/Makefile index 5ddacacf..e66f1c1c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,5 +1,5 @@ IMAGE = grafana/docs-base:latest -CONTENT_PATH = /hugo/content/docs/amixr/latest +CONTENT_PATH = /hugo/content/docs/oncall/latest PORT = 3002:3002 .PHONY: pull diff --git a/docs/README.md b/docs/README.md index 8d702ceb..b6a557c7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,5 +4,5 @@ Source for documentation at https://grafana.com/docs/amixr/ ## Preview the website -Run `make docs`. This launches a preview of the website with the current grafana docs at `http://localhost:3002/docs/amixr/` which will refresh automatically when changes are made to content in the `sources` directory. +Run `make docs`. This launches a preview of the website with the current grafana docs at `http://localhost:3002/docs/oncall/latest/` which will refresh automatically when changes are made to content in the `sources` directory. Make sure Docker is running. diff --git a/docs/sources/open-source.md b/docs/sources/open-source.md new file mode 100644 index 00000000..db0dacf5 --- /dev/null +++ b/docs/sources/open-source.md @@ -0,0 +1,174 @@ +--- +aliases: + - /docs/grafana-cloud/oncall/open-source/ + - /docs/oncall/latest/open-source/ +keywords: + - Open Source +title: Open Source +weight: 100 +--- + +# Open Source + +We prepared three environments for OSS users: +- **Hobby** environment for local usage & playing around: [README.md](https://github.com/grafana/oncall#getting-started). +- **Development** environment for contributors: [DEVELOPER.md](https://github.com/grafana/oncall/blob/dev/DEVELOPER.md) +- **Production** environment for reliable cloud installation using Helm: #production + +## Slack Setup + +Grafana OnCall Slack integration use most of the features Slack API provides. +- Subscription on Slack events requires OnCall to be externally available and provide https endpoint. +- You will need to register new Slack App. + +1. Make sure your OnCall is up and running. + +2. You need OnCall to be accessible through https. For development purposes we suggest using [localtunnel](https://github.com/localtunnel/localtunnel). For production purposes please consider setting up proper web server with HTTPS termination. For localtunnel: +```bash +# Choose the unique prefix instead of pretty-turkey-83 +# Localtunnel will generate an url, e.g. https://pretty-turkey-83.loca.lt +# it is referred as below +lt --port 8000 -s pretty-turkey-83 --print-requests +``` + +2. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. + +3. Go to https://api.slack.com/apps and click Create New App button + +4. Select `From an app manifest` option and choose the right workspace + +5. Copy and paste the following block with the correct and fields + +
+ Click to expand! + + ```yaml + _metadata: + major_version: 1 + minor_version: 1 + display_information: + name: + features: + app_home: + home_tab_enabled: true + messages_tab_enabled: true + messages_tab_read_only_enabled: false + bot_user: + display_name: + always_online: true + shortcuts: + - name: Create a new incident + type: message + callback_id: incident_create + description: Creates a new OnCall incident + - name: Add to postmortem + type: message + callback_id: add_postmortem + description: Add this message to postmortem + slash_commands: + - command: /oncall + url: /slack/interactive_api_endpoint/ + description: oncall + should_escape: false + oauth_config: + redirect_urls: + - /api/internal/v1/complete/slack-install-free/ + - /api/internal/v1/complete/slack-login/ + scopes: + user: + - channels:read + - chat:write + - identify + - users.profile:read + bot: + - app_mentions:read + - channels:history + - channels:read + - chat:write + - chat:write.customize + - chat:write.public + - commands + - files:write + - groups:history + - groups:read + - im:history + - im:read + - im:write + - mpim:history + - mpim:read + - mpim:write + - reactions:write + - team:read + - usergroups:read + - usergroups:write + - users.profile:read + - users:read + - users:read.email + - users:write + settings: + event_subscriptions: + request_url: /slack/event_api_endpoint/ + bot_events: + - app_home_opened + - app_mention + - channel_archive + - channel_created + - channel_deleted + - channel_rename + - channel_unarchive + - member_joined_channel + - message.channels + - message.im + - subteam_created + - subteam_members_changed + - subteam_updated + - user_change + interactivity: + is_enabled: true + request_url: /slack/interactive_api_endpoint/ + org_deploy_enabled: false + socket_mode_enabled: false + ``` +
+ +6. Click `Install to workspace` button to generate the credentials + +7. Populate the environment with variables related to Slack. + + Go to your OnCall plugin -> Env Variables and set: + ``` + SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID + SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret + SLACK_API_TOKEN = OAuth & Permissions -> Bot User OAuth Token + SLACK_INSTALL_RETURN_REDIRECT_HOST = https://pretty-turkey-83.loca.lt + ``` + +8. Set BASE_URL Env variable through web interface or edit `grafana-plugin/grafana-plugin.yml` to set `onCallApiUrl` fields with publicly available url: + ``` + onCallApiUrl: https://pretty-turkey-83.loca.lt + ``` + +9. For dev environment only: Edit grafana-plugin/src/plugin.json to add `Bypass-Tunnel-Reminder` header section for all existing routes + > this headers required for the local development only, otherwise localtunnel blocks requests from grafana plugin + + ``` + { + "path": ..., + ... + "headers": [ + ... + { + "name": "Bypass-Tunnel-Reminder", + "content": "True" + } + ] + }, + ``` +10. Rebuild the plugin + ``` + yarn watch + ``` +11. Restart grafana instance + +12. All set! Go to Slack and check if your application is functional. + From 34e94ce8233f732b795efe66eacbd75d7b51d373 Mon Sep 17 00:00:00 2001 From: Matvey Kukuy Date: Mon, 13 Jun 2022 15:33:56 +0300 Subject: [PATCH 9/9] Slack polishing & docs --- DEVELOPER.md | 156 +----------------- README.md | 2 +- docs/sources/getting-started.md | 2 +- docs/sources/open-source.md | 59 ++----- engine/apps/base/models/live_setting.py | 26 ++- engine/apps/slack/views.py | 3 + .../live_setting_django_strategy.py | 4 +- 7 files changed, 42 insertions(+), 210 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 551a4592..8af642f3 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -124,161 +124,7 @@ extra_hosts: ### Slack application setup -This instruction is also applicable if you set up self-hosted OnCall. - -1. Start a [localtunnel](https://github.com/localtunnel/localtunnel) reverse proxy to make oncall engine api accessible to slack (if you don't have OnCall backend accessible from https), -```bash -# Choose the unique prefix instead of pretty-turkey-83 -# Localtunnel will generate an url, e.g. https://pretty-turkey-83.loca.lt -# it is referred as below -lt --port 8000 -s pretty-turkey-83 --print-requests -``` - -2. [Create a Slack Workspace](https://slack.com/create) for development. - -3. Go to https://api.slack.com/apps and click Create New App button - -4. Select `From an app manifest` option and choose the right workspace - -5. Copy and paste the following block with the correct and fields - -
- Click to expand! - - ```yaml - _metadata: - major_version: 1 - minor_version: 1 - display_information: - name: - features: - app_home: - home_tab_enabled: true - messages_tab_enabled: true - messages_tab_read_only_enabled: false - bot_user: - display_name: - always_online: true - shortcuts: - - name: Create a new incident - type: message - callback_id: incident_create - description: Creates a new OnCall incident - - name: Add to postmortem - type: message - callback_id: add_postmortem - description: Add this message to postmortem - slash_commands: - - command: /oncall - url: /slack/interactive_api_endpoint/ - description: oncall - should_escape: false - oauth_config: - redirect_urls: - - /api/internal/v1/complete/slack-install-free/ - - /api/internal/v1/complete/slack-login/ - scopes: - user: - - channels:read - - chat:write - - identify - - users.profile:read - bot: - - app_mentions:read - - channels:history - - channels:read - - chat:write - - chat:write.customize - - chat:write.public - - commands - - files:write - - groups:history - - groups:read - - im:history - - im:read - - im:write - - mpim:history - - mpim:read - - mpim:write - - reactions:write - - team:read - - usergroups:read - - usergroups:write - - users.profile:read - - users:read - - users:read.email - - users:write - settings: - event_subscriptions: - request_url: /slack/event_api_endpoint/ - bot_events: - - app_home_opened - - app_mention - - channel_archive - - channel_created - - channel_deleted - - channel_rename - - channel_unarchive - - member_joined_channel - - message.channels - - message.im - - subteam_created - - subteam_members_changed - - subteam_updated - - user_change - interactivity: - is_enabled: true - request_url: /slack/interactive_api_endpoint/ - org_deploy_enabled: false - socket_mode_enabled: false - ``` -
- -6. Click `Install to workspace` button to generate the credentials - -6. Populate the environment with variables related to Slack - - In your `.env` file, fill out the following variables: - - ``` - SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID - SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret - SLACK_API_TOKEN = OAuth & Permissions -> Bot User OAuth Token - SLACK_INSTALL_RETURN_REDIRECT_HOST = https://pretty-turkey-83.loca.lt - ``` - - Don't forget to export variables from the `.env` file and restart the server! - -7. Edit `grafana-plugin/grafana-plugin.yml` to set `onCallApiUrl` fields with localtunnel url - ``` - onCallApiUrl: https://pretty-turkey-83.loca.lt - ``` - - or set BASE_URL Env variable through web interface. - -8. Edit grafana-plugin/src/plugin.json to add `Bypass-Tunnel-Reminder` header section for all existing routes - > this headers required for the local development only, otherwise localtunnel blocks requests from grafana plugin, An alternative to this is you can modify your user-agent in your browser to bypass the tunnel warning, it only filters the common browsers. - - ``` - { - "path": ..., - ... - "headers": [ - ... - { - "name": "Bypass-Tunnel-Reminder", - "content": "True" - } - ] - }, - ``` -9. Rebuild the plugin - ``` - yarn watch - ``` -10. Restart grafana instance - -11. All set! Go to Slack and check if your application is functional. +For Slack app configuration check our docs: https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup ## Troubleshooting diff --git a/README.md b/README.md index fb44183c..6e94081a 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Developer-friendly, incident response with brilliant Slack integration. ## Getting Started -We prepared multiple environments: [production](PRODUCTION.md), [developer](DEVELOPER.md) and hobby: +We prepared multiple environments: [production](https://grafana.com/docs/grafana-cloud/oncall/open-source/#production-environment), [developer](DEVELOPER.md) and hobby: 1. Download docker-compose.yaml: ```bash diff --git a/docs/sources/getting-started.md b/docs/sources/getting-started.md index 336058ff..dac5232b 100644 --- a/docs/sources/getting-started.md +++ b/docs/sources/getting-started.md @@ -17,7 +17,7 @@ These procedures introduce you to the configuration of user settings, how to set ## Before you begin -You must have a Grafana Cloud account. +You must have a [Grafana Cloud](https://grafana.com/products/cloud/) account or [Open Source Grafana OnCall]({{< relref " open-source.md" >}}) Each supported integration and the associated monitoring system has a slightly different configuration method. These methods will not be explained in this guide, however, you can follow the online instructions provided when adding an integration. diff --git a/docs/sources/open-source.md b/docs/sources/open-source.md index db0dacf5..dab2f168 100644 --- a/docs/sources/open-source.md +++ b/docs/sources/open-source.md @@ -13,11 +13,15 @@ weight: 100 We prepared three environments for OSS users: - **Hobby** environment for local usage & playing around: [README.md](https://github.com/grafana/oncall#getting-started). - **Development** environment for contributors: [DEVELOPER.md](https://github.com/grafana/oncall/blob/dev/DEVELOPER.md) -- **Production** environment for reliable cloud installation using Helm: #production +- **Production** environment for reliable cloud installation using Helm: [Production Environment](#production-environment) + +## Production Environment + +TBD ## Slack Setup -Grafana OnCall Slack integration use most of the features Slack API provides. +Grafana OnCall Slack integration use a lot of Slack API features: - Subscription on Slack events requires OnCall to be externally available and provide https endpoint. - You will need to register new Slack App. @@ -31,16 +35,15 @@ Grafana OnCall Slack integration use most of the features Slack API provides. lt --port 8000 -s pretty-turkey-83 --print-requests ``` -2. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. +3. If you use localtunnel, open your external URL and click "Continue" to allow requests to bypass the warning page. -3. Go to https://api.slack.com/apps and click Create New App button +4. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. -4. Select `From an app manifest` option and choose the right workspace +5. Go to https://api.slack.com/apps and click Create New App button -5. Copy and paste the following block with the correct and fields +6. Select `From an app manifest` option and choose the right workspace -
- Click to expand! +7. Copy and paste the following block with the correct and fields ```yaml _metadata: @@ -129,46 +132,16 @@ lt --port 8000 -s pretty-turkey-83 --print-requests org_deploy_enabled: false socket_mode_enabled: false ``` -
-6. Click `Install to workspace` button to generate the credentials - -7. Populate the environment with variables related to Slack. - - Go to your OnCall plugin -> Env Variables and set: +6. Go to your "OnCall" -> "Env Variables" and set: ``` SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret - SLACK_API_TOKEN = OAuth & Permissions -> Bot User OAuth Token - SLACK_INSTALL_RETURN_REDIRECT_HOST = https://pretty-turkey-83.loca.lt + SLACK_SIGNING_SECRET = Basic Information -> App Credentials -> Signing Secret + SLACK_INSTALL_RETURN_REDIRECT_HOST = << OnCall external URL >> ``` -8. Set BASE_URL Env variable through web interface or edit `grafana-plugin/grafana-plugin.yml` to set `onCallApiUrl` fields with publicly available url: - ``` - onCallApiUrl: https://pretty-turkey-83.loca.lt - ``` +7. Go to "OnCall" -> "ChatOps" -> "Slack" and install Slack Integration -9. For dev environment only: Edit grafana-plugin/src/plugin.json to add `Bypass-Tunnel-Reminder` header section for all existing routes - > this headers required for the local development only, otherwise localtunnel blocks requests from grafana plugin - - ``` - { - "path": ..., - ... - "headers": [ - ... - { - "name": "Bypass-Tunnel-Reminder", - "content": "True" - } - ] - }, - ``` -10. Rebuild the plugin - ``` - yarn watch - ``` -11. Restart grafana instance - -12. All set! Go to Slack and check if your application is functional. +8. All set! diff --git a/engine/apps/base/models/live_setting.py b/engine/apps/base/models/live_setting.py index ca3331de..eee3579e 100644 --- a/engine/apps/base/models/live_setting.py +++ b/engine/apps/base/models/live_setting.py @@ -41,6 +41,7 @@ class LiveSetting(models.Model): "SLACK_CLIENT_OAUTH_ID", "SLACK_CLIENT_OAUTH_SECRET", "SLACK_SIGNING_SECRET", + "SLACK_INSTALL_RETURN_REDIRECT_HOST", "SEND_ANONYMOUS_USAGE_STATS", "GRAFANA_CLOUD_ONCALL_TOKEN", "GRAFANA_CLOUD_ONCALL_HEARTBEAT_ENABLED", @@ -50,24 +51,31 @@ class LiveSetting(models.Model): DESCRIPTIONS = { "SLACK_SIGNING_SECRET": ( "Check this instruction for details how to set up Slack. " + "https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup" + "'>instruction for details how to set up Slack. " "Slack secrets can't be verified on the backend, please try installing the Slack Bot " - "after you update Slack credentials." + "after you update them." ), "SLACK_CLIENT_OAUTH_SECRET": ( "Check this instruction for details how to set up Slack. " + "https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup" + "'>instruction for details how to set up Slack. " "Slack secrets can't be verified on the backend, please try installing the Slack Bot " - "after you update Slack credentials." + "after you update them." ), "SLACK_CLIENT_OAUTH_ID": ( "Check this instruction for details how to set up Slack. " + "https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup" + "'>instruction for details how to set up Slack. " "Slack secrets can't be verified on the backend, please try installing the Slack Bot " - "after you update Slack credentials." + "after you update them." + ), + "SLACK_INSTALL_RETURN_REDIRECT_HOST": ( + "Check instruction for details how to set up Slack. " + "Slack secrets can't be verified on the backend, please try installing the Slack Bot " + "after you update them." ), "TWILIO_ACCOUNT_SID": ( "Twilio username to allow amixr send sms and make phone calls, " diff --git a/engine/apps/slack/views.py b/engine/apps/slack/views.py index 8988594c..5990b0b6 100644 --- a/engine/apps/slack/views.py +++ b/engine/apps/slack/views.py @@ -119,6 +119,9 @@ class SlackEventApiEndpointView(APIView): return Response(status=403) if not settings.DEBUG: + if live_settings.SLACK_SIGNING_SECRET is None and settings.SLACK_SIGNING_SECRET_LIVE: + raise Exception("Please specify SLACK_SIGNING_SECRET or use DEBUG.") + if not ( SlackEventApiEndpointView.verify_signature( slack_request_timestamp, slack_signature, body, live_settings.SLACK_SIGNING_SECRET diff --git a/engine/apps/social_auth/live_setting_django_strategy.py b/engine/apps/social_auth/live_setting_django_strategy.py index dd913e67..d2cf0fe1 100644 --- a/engine/apps/social_auth/live_setting_django_strategy.py +++ b/engine/apps/social_auth/live_setting_django_strategy.py @@ -34,8 +34,10 @@ class LiveSettingDjangoStrategy(DjangoStrategy): def build_absolute_uri(self, path=None): """ - Overriden DjangoStrategy's method to substitute and force the host value from ENV + Overridden DjangoStrategy's method to substitute and force the host value from ENV """ + if live_settings.SLACK_INSTALL_RETURN_REDIRECT_HOST is not None and path is not None: + return live_settings.SLACK_INSTALL_RETURN_REDIRECT_HOST + path if settings.SLACK_INSTALL_RETURN_REDIRECT_HOST is not None and path is not None: return settings.SLACK_INSTALL_RETURN_REDIRECT_HOST + path if self.request: