From e9ae4cc3e98cb6f13ea22071f3bd1d3c048eeb12 Mon Sep 17 00:00:00 2001 From: Matvey Kukuy Date: Wed, 24 May 2023 14:11:21 +0300 Subject: [PATCH] Docs restructure (#1703) Restructured docs. Based on: https://github.com/grafana/oncall-private/issues/1698 --- docs/sources/alert-behavior/_index.md | 24 ------ docs/sources/calendar-schedules/_index.md | 64 -------------- .../web-schedule/calendar-export/index.md | 74 ---------------- .../web-schedule/create-schedule/index.md | 77 ----------------- .../_index.md} | 54 +++++++----- docs/sources/escalation-policies/_index.md | 18 ---- .../configure-escalation-chains/index.md | 39 --------- docs/sources/get-started/_index.md | 12 +-- docs/sources/integrations/_index.md | 85 ++++++++++--------- .../index.md | 4 +- .../index.md | 2 +- .../available-integrations/_index.md | 30 ------- .../chatops-integrations/_index.md | 26 ------ .../index.md | 2 +- .../index.md | 6 +- .../configure-jira => jira}/index.md | 4 +- docs/sources/integrations/manual/index.md | 35 ++++++++ .../configure-webhook => webhook}/index.md | 32 +++---- .../configure-zabbix => zabbix}/index.md | 2 +- .../configure-zendesk => zendesk}/index.md | 2 +- .../index.md => jinja2-templating/_index.md} | 36 +++----- .../migration-from-other-tools/_index.md | 18 ++++ docs/sources/mobile-app/_index.md | 6 +- docs/sources/notify/_index.md | 51 +++++++++++ docs/sources/notify/mattermost/index.md | 23 +++++ .../ms-teams}/index.md | 2 +- docs/sources/notify/phone-calls-sms/index.md | 32 +++++++ .../configure-slack => notify/slack}/index.md | 4 +- .../telegram}/index.md | 2 +- docs/sources/on-call-schedules/_index.md | 46 ++++++++++ .../api-terraform-schedule/_index.md | 21 +++++ .../ical-schedules/index.md | 11 ++- .../web-schedule/_index.md | 21 ++--- .../oncall-api-reference/integrations.md | 2 +- docs/sources/open-source/_index.md | 4 +- .../index.md => outgoing-webhooks/_index.md} | 10 +-- .../_index.md | 52 ++---------- 37 files changed, 385 insertions(+), 548 deletions(-) delete mode 100644 docs/sources/alert-behavior/_index.md delete mode 100644 docs/sources/calendar-schedules/_index.md delete mode 100644 docs/sources/calendar-schedules/web-schedule/calendar-export/index.md delete mode 100644 docs/sources/calendar-schedules/web-schedule/create-schedule/index.md rename docs/sources/{escalation-policies/configure-routes/index.md => escalation-chains-and-routes/_index.md} (56%) delete mode 100644 docs/sources/escalation-policies/_index.md delete mode 100644 docs/sources/escalation-policies/configure-escalation-chains/index.md rename docs/sources/integrations/{available-integrations/configure-alertmanager => alertmanager}/index.md (97%) rename docs/sources/integrations/{available-integrations/configure-appdynamics => appdynamics}/index.md (96%) delete mode 100644 docs/sources/integrations/available-integrations/_index.md delete mode 100644 docs/sources/integrations/chatops-integrations/_index.md rename docs/sources/integrations/{available-integrations/configure-grafana-alerting => grafana-alerting}/index.md (98%) rename docs/sources/integrations/{available-integrations/configure-inbound-email => inbound-email}/index.md (89%) rename docs/sources/integrations/{available-integrations/configure-jira => jira}/index.md (95%) create mode 100644 docs/sources/integrations/manual/index.md rename docs/sources/integrations/{available-integrations/configure-webhook => webhook}/index.md (71%) rename docs/sources/integrations/{available-integrations/configure-zabbix => zabbix}/index.md (99%) rename docs/sources/integrations/{available-integrations/configure-zendesk => zendesk}/index.md (96%) rename docs/sources/{alert-behavior/alert-templates/index.md => jinja2-templating/_index.md} (83%) create mode 100644 docs/sources/migration-from-other-tools/_index.md create mode 100644 docs/sources/notify/_index.md create mode 100644 docs/sources/notify/mattermost/index.md rename docs/sources/{integrations/chatops-integrations/configure-teams => notify/ms-teams}/index.md (98%) create mode 100644 docs/sources/notify/phone-calls-sms/index.md rename docs/sources/{integrations/chatops-integrations/configure-slack => notify/slack}/index.md (97%) rename docs/sources/{integrations/chatops-integrations/configure-telegram => notify/telegram}/index.md (98%) create mode 100644 docs/sources/on-call-schedules/_index.md create mode 100644 docs/sources/on-call-schedules/api-terraform-schedule/_index.md rename docs/sources/{calendar-schedules => on-call-schedules}/ical-schedules/index.md (90%) rename docs/sources/{calendar-schedules => on-call-schedules}/web-schedule/_index.md (87%) rename docs/sources/{alert-behavior/outgoing-webhooks/index.md => outgoing-webhooks/_index.md} (89%) rename docs/sources/{configure-user-settings => user-and-team-management}/_index.md (66%) diff --git a/docs/sources/alert-behavior/_index.md b/docs/sources/alert-behavior/_index.md deleted file mode 100644 index 2a2ffa82..00000000 --- a/docs/sources/alert-behavior/_index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -aliases: - - /docs/oncall/latest/alert-behavior/ -canonical: https://grafana.com/docs/oncall/latest/alert-behavior/ -title: Configure alert behavior for Grafana OnCall -weight: 900 ---- - -# Configure alert behavior for Grafana OnCall - -The available alert configurations in Grafana OnCall allow you to define how certain alerts are handled and ensure that -alerts are routed, escalated, and grouped to fit your specific alerting needs. Grafana OnCall can receive alerts from -any monitoring system that sends alerts via webhook. - -## About 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. - -{{< section >}} diff --git a/docs/sources/calendar-schedules/_index.md b/docs/sources/calendar-schedules/_index.md deleted file mode 100644 index 8b7a3cb7..00000000 --- a/docs/sources/calendar-schedules/_index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: On-call schedules -aliases: - - /docs/oncall/latest/calendar-schedules/ -canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/ -description: "Learn more about on-call schedules" -keywords: - - Grafana - - oncall - - schedule - - calendar -weight: 1100 ---- - -# On-call schedules - -Grafana OnCall makes it easier to establish consistent and thoughtful on-call coverage while ensuring that alerts don’t -go unnoticed. Use Grafana OnCall to: - -- Define coverage needs and avoid gaps in coverage -- Automate alert escalation -- Configure on-call shift notifications - -This section provides conceptual information about Grafana OnCall schedule options. - -## About on-call schedules - -An on-call schedule consist of one or more rotations that contain on-call shifts. A schedule must be referenced in the -corresponding escalation chain for alert notifications to be sent to an on-call user. - -A fully configured on-call schedule consists of three main components: - -- **Rotations**: A recurring schedule containing a set of on-call shifts that users rotate through. -- **On-call shifts**: The period of time that an individual user is on-call for a particular rotation -- **Escalation Chains**: Automated steps that determine who to notify of an alert group. - -## Types of on-call schedules - -On-call schedules look different for different organizations and even teams. Grafana OnCall offers three different -options for managing your on-call schedules, so you can choose the option that best fits your needs. - -### Web-based schedule - -Configure and manage on-call schedules directly in the Grafana OnCall plugin. Easily configure and preview rotations, -see teammates' time zones, and add overrides. - -Learn more about [Web-based schedules]({{< relref "web-schedule" >}}) - -### iCal import - -Use any calendar service that uses the iCal format to manage and customize on-call schedules - Import rotations and -shifts from your calendar app to Grafana OnCall for widely accessible scheduling. iCal imports appear in Grafana -OnCall as read-only schedules but can be leveraged similarly to a web-based schedule. - -Learn more about [iCal import schedules]({{< relref "ical-schedules" >}}) - -### Terraform - -Use the Grafana OnCall Terraform provider to manage schedules within your “as-code” workflow. Rotations configured -via Terraform are automatically added to your schedules in Grafana OnCall. Similar to the iCal import, these schedules -read-only and cannot be edited from the UI. - -To learn more, read our [Get started with Grafana OnCall and Terraform]( -) blog post. diff --git a/docs/sources/calendar-schedules/web-schedule/calendar-export/index.md b/docs/sources/calendar-schedules/web-schedule/calendar-export/index.md deleted file mode 100644 index 08503744..00000000 --- a/docs/sources/calendar-schedules/web-schedule/calendar-export/index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Export on-call schedules -aliases: - - /docs/oncall/latest/calendar-schedules/web-schedule/calendar-export/ -canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/web-schedule/calendar-export/ -description: "Learn how to export an on-call schedule from Grafana OnCall" -keywords: - - Grafana - - oncall - - on-call - - calendar - - iCal export -weight: 500 ---- - -# Export on-call schedules - -Export on-call schedules from Grafana OnCall to your preferred calendar app with a one-time secret iCal URL. -The schedule export allows you to add on-call schedules to your existing calendar to view on-call shifts alongside the -rest of your schedule. - -There are two schedule export options available: - -- **On-call schedule export** - Exports all on-call shifts for a particular schedule, including rotations, overrides, -and assigned users. -- **User-specific schedule export** - Exports assigned on-call shifts for a particular user. Use this export option to -add your assigned on-call shifts to your calendar. - -> **Note:** Calendar exports include all scheduled shifts, including those which are lower priority or overridden. - -## Export an on-call schedule - -Use this export option to add all on-call shifts associated with a schedule to a calendar. Best for a team or shared -calendars. - -To export a schedule from Grafana OnCall: - -1. In Grafana OnCall, navigate to the **Schedules** tab. -1. Open the schedule you’d like to export by clicking on the schedule name. -1. Click **Export** in the upper right corner, then click **+ Create iCal link** to generate a secret iCal URL. -1. Copy the iCal link and store it somewhere you’ll remember. Once you close the schedule export window, you won't be -able to access the iCal link. -1. Open your calendar settings to add a calendar from a URL (This step varies based on your calendar app). - -## Export a user on-call schedule - -Use this export option to add your assigned on-call shifts to your calendar. Best for personal calendars. - -To export your on-call schedule: - -1. In Grafana OnCall, navigate to the **Users** tab. -1. Click **View my profile** in the upper right corner. -1. From the **User Info** tab, navigate to the iCal link section. -1. Click **+ Create iCal link** to generate your secret iCal URL. -1. Copy the iCal link and store it somewhere you’ll remember. Once you close your user profile, you won't be able to -access the iCal link again. -1. Open your calendar settings to add a calendar from a URL (This step varies based on your calendar app). - -## Revoke an iCal export link - -iCal links are displayed upon creation, and users are advised to copy their link and store it for future reference. -To ensure the security of your and your teams' calendar data, after an iCal link is generated, the link is hidden and -cannot be accessed again. - -If you need to revoke an iCal link, you can do so anytime. By doing so, any calendar that references the revoked link -will lose access to the calendar data. - -To revoke an active iCal link: - -1. Navigate to the schedule or user profile associated with the iCal link. -1. For schedules, click **Export** to open the Schedule export window. -1. For users, navigate to the iCal link section of the **User info** tab. -1. If there is an active iCal link, click **Revoke iCal link**. -1. Once revoked, you can generate a new iCal link by clicking **+ Create iCal link**. diff --git a/docs/sources/calendar-schedules/web-schedule/create-schedule/index.md b/docs/sources/calendar-schedules/web-schedule/create-schedule/index.md deleted file mode 100644 index d2856451..00000000 --- a/docs/sources/calendar-schedules/web-schedule/create-schedule/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Create on-call schedules -aliases: - - /docs/oncall/latest/calendar-schedules/web-schedule/create-schedule/ -canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/web-schedule/create-schedule/ -description: "Create on-call schedules with Grafana OnCall" -keywords: - - Grafana - - oncall - - on-call - - schedule - - calendar -weight: 300 ---- - -# Create on-call schedules in Grafana OnCall - -Schedules allow you to map out recurring on-call coverage and automate the escalation of alert notifications to -currently on-call users. With Grafana OnCall, you can customize rotations with a live schedule preview to visualize -your schedule, add users, reorder users, and reference teammates' time zones. - -To learn more, see [On-call schedules]({{< relref "../../../calendar-schedules" >}}) which provides the fundamental -concepts for this task. - ->**Note:** User working hours are currently hardcoded and cannot be changed. Profile settings to configure this and other options will be added in a future release. - -## Before you begin - -- Users with Admin or Editor roles can create, edit and delete schedules. -- Users with Viewer role cannot receive alert notifications, therefore, cannot be on-call. - -For more information about permissions, refer to -[Manage users and teams for Grafana OnCall]({{< relref "../../../configure-user-settings" >}}) - -## Create an on-call schedule - -To create a new on-call schedule: - -1. In Grafana OnCall, navigate to the **Schedules** tab and click **+ New schedule** -1. Navigate to **Set up on-call rotation schedule** and click **+ Create** -1. Provide a name and review available schedule settings -1. When you’re done, click **Create Schedule** - ->**Note:** You can edit your schedule settings at any time. - -### Add a rotation to your on-call schedule - -After creating your schedule, you can add rotations to build out your coverage needs. -Think of a rotation as a recurring schedule containing on-call shifts that users rotate through. - -To add a rotation to an on-call schedule: - -1. From your newly created schedule, click **+ Add rotation** and select **New Layer**. -1. Complete the rotation creation form according to your rotation parameters. -1. Add users to the rotation from the dropdown. -You can separate users into user groups to rotate through individual users per shift. -User groups that contain -multiple users results in all users in the group being included in corresponding shifts. -1. When you’re satisfied with the rotation preview, click **Create**. - -### Add an on-call schedule to escalation chains - -Now that you’ve created your schedule, it must be referenced in the steps of an escalation chain for on-call users -to receive alert notifications. - -To connect a schedule to an escalation chain: - -1. In Grafana OnCall, go to the **Escalation Chains** tab. -1. Navigate to an existing escalation chain or click **+ New Escalation Chain**. -1. Select **Notify users from on-call schedule** from the **Add escalation step** dropdown. -1. Specify which notification policy to use and the appropriate schedule. -1. Click and drag the escalation steps to reorder, if needed. - -Escalation chain steps are saved automatically. - -For more information about Escalation Chains, refer to -[Configure and manage Escalation Chains]({{< relref "../../../escalation-policies/configure-escalation-chains" >}}) diff --git a/docs/sources/escalation-policies/configure-routes/index.md b/docs/sources/escalation-chains-and-routes/_index.md similarity index 56% rename from docs/sources/escalation-policies/configure-routes/index.md rename to docs/sources/escalation-chains-and-routes/_index.md index b4475fd2..5045fb28 100644 --- a/docs/sources/escalation-policies/configure-routes/index.md +++ b/docs/sources/escalation-chains-and-routes/_index.md @@ -1,22 +1,40 @@ --- aliases: - - /docs/oncall/latest/escalation-policies/configure-routes/ -canonical: https://grafana.com/docs/oncall/latest/escalation-policies/configure-routes/ -keywords: - - Grafana Cloud - - Alerts - - Notifications - - on-call - - amixr - - oncall - - integrations -title: Configure and manage routes -weight: 300 + - /docs/oncall/latest/escalation-chains-and-routes/ +canonical: https://grafana.com/docs/oncall/latest/escalation-chains-and-routes/ +title: Escalation Chains and Routes +weight: 600 --- -# Configure and manage Routes +# Escalation Chains and Routes -Set up escalation chains and routes to configure escalation behavior for alert group notifications. +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. + +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. + +## 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 +(outdated) or Jinja2 templates +in their payloads. Notifications for these alerts can be sent to individuals, or they can make use of a new +or existing escalation chain. ## Configure escalation chains @@ -59,14 +77,10 @@ specify using a Jinja template that matches content in the payload body of the f specify where to send the notification for each route. For example, you can send notifications for alerts with `{{ payload.severity == "critical" and payload.service == -"database" }}` in the payload to an escalation chain called `Bob_OnCall`. You can create a different route for alerts +"database" }}` [(Check Jinja2 reference)]({{< relref "jinja2-templating" >}}) in the payload to an escalation chain +called `Bob_OnCall`. You can create a different route for alerts with the payload `{{ "synthetic-monitoring-dev-" in payload.namespace }}` and select a escalation chain called `NotifySecurity`. -Alternatively you can use regular expressions, e.g. `\"severity\": \"critical\"` or `\"namespace\" *: -*\"synthetic-monitoring-dev-.*\"` - -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. diff --git a/docs/sources/escalation-policies/_index.md b/docs/sources/escalation-policies/_index.md deleted file mode 100644 index 02dc9d96..00000000 --- a/docs/sources/escalation-policies/_index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -aliases: - - /docs/oncall/latest/escalation-policies/ -canonical: https://grafana.com/docs/oncall/latest/escalation-policies/ -title: Escalation Chains and Routes -weight: 700 ---- - -# Escalation Chains and Routes - -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. - -See the following topics for more information: - -{{< section >}} diff --git a/docs/sources/escalation-policies/configure-escalation-chains/index.md b/docs/sources/escalation-policies/configure-escalation-chains/index.md deleted file mode 100644 index a5cb85bf..00000000 --- a/docs/sources/escalation-policies/configure-escalation-chains/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -aliases: - - /docs/oncall/latest/escalation-policies/configure-escalation-chains/ -canonical: https://grafana.com/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 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. - -## 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. diff --git a/docs/sources/get-started/_index.md b/docs/sources/get-started/_index.md index 8c6987ab..6aaf394e 100644 --- a/docs/sources/get-started/_index.md +++ b/docs/sources/get-started/_index.md @@ -24,7 +24,7 @@ The following diagram details an example alert workflow with Grafana OnCall: These procedures introduce you to initial Grafana OnCall configuration steps, including monitoring system integration, -how to set up escalation chains, and how to use your calendar service for on-call scheduling. +how to set up escalation chains, and how to set up calendar for on-call scheduling. ## Before you begin @@ -68,7 +68,7 @@ For more information on Grafana OnCall integrations and further configuration gu ### Learn Alert Flow -All Alerts in OnCall are grouped to Alert Groups ([read more about Grouping ID]({{< relref "../alert-behavior/alert-templates" >}})). Alert Group could have mutually +All Alerts in OnCall are grouped to Alert Groups ([read more about Grouping ID]({{< relref "jinja2-templating" >}})). Alert Group could have mutually exclusive states: - **Firing:** Once Alert Group is registered, Escalation Policy associated with it is getting started. Escalation policy will work while Alert Group is in this status. @@ -112,7 +112,7 @@ To configure Escalation Chains: Alerts from this integration will now follow the escalation steps configured in your Escalation Chain. For more information on Escalation Chains and more ways to customize them, refer to -[Configure and manage Escalation Chains]({{< relref "../escalation-policies/configure-escalation-chains" >}}) +[Configure and manage Escalation Chains]({{< relref "escalation-chains-and-routes" >}}) ## Get notified of an alert @@ -124,7 +124,7 @@ policies, chatops integrations, and on-call schedules allow you to automate how Personal notification policies determine how a user is notified for a certain type of alert. Get notified by SMS, phone call, or Slack mentions. Administrators can configure how users receive notification for certain types of alerts. For more information on personal notification policies, refer to -[Manage users and teams for Grafana OnCall]({{< relref "../configure-user-settings" >}}) +[Manage users and teams for Grafana OnCall]({{< relref "user-and-team-management" >}}) To configure users personal notification policies: @@ -148,7 +148,7 @@ To configure Slack for Grafana OnCall: 6. Ensure users verify their Slack accounts in their user profile in Grafana OnCall. For further instruction on connecting to your Slack workspace, refer to -[Slack integration for Grafana OnCall]({{< relref "../integrations/chatops-integrations/configure-slack/" >}}) +[Slack integration for Grafana OnCall]({{< relref "../notify/slack/" >}}) ### Add your on-call schedule @@ -163,4 +163,4 @@ To integrate your on-call calendar with Grafana OnCall: 4. Configure the rest of the schedule settings and click Create Schedule For more information on on-call schedules, refer to -[Configure and manage on-call schedules]({{< relref "../calendar-schedules" >}}) +[Configure and manage on-call schedules]({{< relref "on-call-schedules" >}}) diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index e575df09..da9dec7d 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -1,7 +1,7 @@ --- aliases: - - /docs/oncall/latest/integrations/ -canonical: https://grafana.com/docs/oncall/latest/integrations/ + - /docs/oncall/latest/integration-with-alert-sources/ +canonical: https://grafana.com/docs/oncall/latest/integration-with-alert-sources/ keywords: - Grafana Cloud - Alerts @@ -10,26 +10,35 @@ keywords: - amixr - oncall - integrations -title: Grafana OnCall integrations +title: Integrations weight: 500 --- -# Grafana OnCall integrations +# Integrations -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. +"Integration" is a main entry point for alerts being consumed by OnCall. Rendering, grouping and routing are configured +within integrations. -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. +"Integration" is a set of Jinja2 templates which is transforming alert payload to the format suitable to OnCall. +You could check pre-configured templates in the list of avaliable integrations (Integrations -> +"New integration to receive alerts"), create your own or adjust existing. + +Read more about Jinja2 templating used in OnCall [here]({{< relref "jinja2-templating" >}}). + +Alert flow within integration: + +1. Alert is registered by unique integration url (or [e-mail]({{< relref "inbound-email" >}}) in case of inbound e-mail +integration) +2. If there is a non-resolved "alert group" with the same "grouping id", alert will be added to this "alert group". +3. If there is no non-resolved "alert group" with the same "grouping id", new "alert group" will be issued. +4. New "alert group" will be routed using routing engine and escalation chain will be started (TODO: link). ## 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 +### Connect an integration To configure an integration for Grafana OnCall: @@ -38,40 +47,42 @@ 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 +### Manage 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 +#### Manage integration behaviour and rendering -To customize the alert template for an integration: +"Integration templates" are Jinja2 templates which are applied to each alert to define it's rendering and behaviour. +For templates editor: -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. +1. Navigate to the **Integrations** tab, select an integration from the list. +2. Click the **gear icon** next to the integration name. -To customize alert grouping for an integration: +Here are a few templates responsible for alert group formation: -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. +- **Alert Behaviour, Grouping id** - defining how alerts will be grouped into alert groups. Alerts with the same result +- of executing of this template will be grouped together. For example: -For more information on alert templates, see -[Configure alerts templates]({{< relref "../alert-behavior/alert-templates" >}}) +Alert 1 payload:`{"name": "CPU 90%", "cluster": "EU"}` -#### Add Routes +Alert 2 payload:`{"name": "CPU 90%", "cluster": "US"}` -To add a route to an integration using regular expression: +If we want to group them together by name, we could use template `{{ payload.name }}` which will result to the equal +grouping id "CPU 90%". If we want to group them by region and end up with 2 separate alert groups, we could use such a +template: `{{ payload.region }}}` -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. +- **Alert Behaviour, Acknowledge Condition** - If this template will be rendered as "True" or "1", containing alert +- group will change it's state to "acknowledged". + +- **Alert Behaviour, Resolve Condition** - Similar to Acknowledge Condition, will make alert group "resolved". + +- **Alert Behaviour, Source Link** - result of rendering of this template will be used in various places of the UI. +Should point to the most specific place in the alert source related to the alert group. Also rendering result will be +available in other templates as a variable `{{ source_link }}`. + +Read more about Jinja2 (TODO: link) in a specific section. #### Edit integration name @@ -81,12 +92,4 @@ To edit the name of an integration: 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/available-integrations/configure-alertmanager/index.md b/docs/sources/integrations/alertmanager/index.md similarity index 97% rename from docs/sources/integrations/available-integrations/configure-alertmanager/index.md rename to docs/sources/integrations/alertmanager/index.md index b43a5aa4..df0e6f5d 100644 --- a/docs/sources/integrations/available-integrations/configure-alertmanager/index.md +++ b/docs/sources/integrations/alertmanager/index.md @@ -10,7 +10,7 @@ keywords: - on-call - Alertmanager - Prometheus -title: Alertmanager integration for Grafana OnCall +title: Alertmanager weight: 300 --- @@ -69,4 +69,4 @@ Alertmanager offers three alert grouping options: - Grafana OnCall groups alerts based on the first label of each alert. - Grafana OnCall marks an alert group as resolved only when there are fewer than 500 grouped - alerts, and every `firing` alert with the same labels has a corresponding `resolved` alert + alerts, and every `firing` alert with the same labels has a corresponding `resolved` alert. diff --git a/docs/sources/integrations/available-integrations/configure-appdynamics/index.md b/docs/sources/integrations/appdynamics/index.md similarity index 96% rename from docs/sources/integrations/available-integrations/configure-appdynamics/index.md rename to docs/sources/integrations/appdynamics/index.md index acf0a8e1..6740458f 100644 --- a/docs/sources/integrations/available-integrations/configure-appdynamics/index.md +++ b/docs/sources/integrations/appdynamics/index.md @@ -9,7 +9,7 @@ keywords: - Notifications - on-call - AppDynamics -title: AppDynamics integration for Grafana OnCall +title: AppDynamics weight: 500 --- diff --git a/docs/sources/integrations/available-integrations/_index.md b/docs/sources/integrations/available-integrations/_index.md deleted file mode 100644 index 4babb8e2..00000000 --- a/docs/sources/integrations/available-integrations/_index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -aliases: - - /docs/oncall/latest/integrations/available-integrations/ -canonical: https://grafana.com/docs/oncall/latest/integrations/available-integrations/ -keywords: - - Grafana Cloud - - Alerts - - Notifications - - on-call - - Alertmanager - - Prometheus -title: Currently available integrations for Grafana OnCall -weight: 100 ---- - -# 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 -[Webhook integrations for Grafana OnCall]({{< relref "../available-integrations/configure-webhook" >}}) 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/chatops-integrations/_index.md b/docs/sources/integrations/chatops-integrations/_index.md deleted file mode 100644 index 038042aa..00000000 --- a/docs/sources/integrations/chatops-integrations/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -aliases: - - ../chat-options/ - - /docs/oncall/latest/integrations/chatops-integrations/ -canonical: https://grafana.com/docs/oncall/latest/integrations/chatops-integrations/ -keywords: - - Grafana Cloud - - Alerts - - Notifications - - on-call - - amixr - - oncall - - slack -title: Available ChatOps integrations -weight: 300 ---- - -# Available ChatOps integrations - -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 "../../alert-behavior/outgoing-webhooks/" >}}). - -To configure supported messaging apps, see the following topics: - -{{< section >}} diff --git a/docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md b/docs/sources/integrations/grafana-alerting/index.md similarity index 98% rename from docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md rename to docs/sources/integrations/grafana-alerting/index.md index f6beab61..776fed61 100644 --- a/docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md +++ b/docs/sources/integrations/grafana-alerting/index.md @@ -9,7 +9,7 @@ keywords: - Notifications - on-call - Prometheus -title: Grafana Alerting integration for Grafana OnCall +title: Grafana Alerting weight: 100 --- diff --git a/docs/sources/integrations/available-integrations/configure-inbound-email/index.md b/docs/sources/integrations/inbound-email/index.md similarity index 89% rename from docs/sources/integrations/available-integrations/configure-inbound-email/index.md rename to docs/sources/integrations/inbound-email/index.md index 7af163d4..c96fce3c 100644 --- a/docs/sources/integrations/available-integrations/configure-inbound-email/index.md +++ b/docs/sources/integrations/inbound-email/index.md @@ -1,6 +1,6 @@ --- aliases: - - add-inbound-email/ + - inbound-email/ - /docs/oncall/latest/integrations/available-integrations/configure-inbound-email/ canonical: https://grafana.com/docs/oncall/latest/integrations/available-integrations/configure-inbound-email/ keywords: @@ -9,7 +9,7 @@ keywords: - Notifications - on-call - Email -title: Inbound Email integration for Grafana OnCall +title: Inbound Email weight: 500 --- @@ -28,7 +28,7 @@ You must have an Admin role to create integrations in Grafana OnCall. ## Grouping and auto-resolve Alert groups will be grouped by email subject and auto-resolved if the email message text equals "OK". - This behaviour can be modified via custom templates. + This behaviour can be modified via [custom templates]({{< relref "jinja2-templating" >}}). Alerts from Inbound Email integration have followng payload: diff --git a/docs/sources/integrations/available-integrations/configure-jira/index.md b/docs/sources/integrations/jira/index.md similarity index 95% rename from docs/sources/integrations/available-integrations/configure-jira/index.md rename to docs/sources/integrations/jira/index.md index 15f7025f..ad11b249 100644 --- a/docs/sources/integrations/available-integrations/configure-jira/index.md +++ b/docs/sources/integrations/jira/index.md @@ -1,6 +1,6 @@ --- aliases: - - add-jira/ + - jira/ - /docs/oncall/latest/integrations/available-integrations/configure-jira/ canonical: https://grafana.com/docs/oncall/latest/integrations/available-integrations/configure-jira/ keywords: @@ -9,7 +9,7 @@ keywords: - Notifications - on-call - Jira -title: Jira integration for Grafana OnCall +title: Jira weight: 500 --- diff --git a/docs/sources/integrations/manual/index.md b/docs/sources/integrations/manual/index.md new file mode 100644 index 00000000..a52e73af --- /dev/null +++ b/docs/sources/integrations/manual/index.md @@ -0,0 +1,35 @@ +--- +aliases: + - /docs/oncall/latest/integrations/manual/ +canonical: https://grafana.com/docs/oncall/latest/integrations/manual/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - Alertmanager + - Prometheus +title: Raising alerts manually +weight: 300 +--- + +# Raising alerts manually + +Sometimes you need to page a specific person (following their preferred notification policy), or need help from people +in some particular team. In that case you can trigger an alert group providing some context information as well as +defining who to notify about it, a user or the person on-call in a given team's schedule. + +You can create a manual alert group using the "+ Manual alert group" button (in the Alert Groups page), and set +its escalation options to page a specific person or group of people. + +> The same feature is also available as **/escalate** slack command. + +- You need to define a title for your alert, an optional description, and select the responders which could be a +specific user in your team, a particular schedule, or multiple instances of those. +- When selecting a user, a few checks will be performed before adding them to the list of responders: user should have +a notification policy set, and ideally be on-call. +- If the user is not on-call at the time, you will get alternative users to choose instead from the OnCall schedules +that user is part of. You can still page the original user if you confirm that is what you want. +- When selecting a schedule, the user(s) on-call when the alert is triggered will be notified. + +> **NOTE:** for each responder (user or schedule) you can choose the notification policy to use: default or important. diff --git a/docs/sources/integrations/available-integrations/configure-webhook/index.md b/docs/sources/integrations/webhook/index.md similarity index 71% rename from docs/sources/integrations/available-integrations/configure-webhook/index.md rename to docs/sources/integrations/webhook/index.md index d3cf8632..3052e5cb 100644 --- a/docs/sources/integrations/available-integrations/configure-webhook/index.md +++ b/docs/sources/integrations/webhook/index.md @@ -10,11 +10,11 @@ keywords: - on-call - Alertmanager - Prometheus -title: Webhook integration for Grafana OnCall +title: Inbound Webhook weight: 700 --- -# Webhook integrations for Grafana OnCall +# Inbound 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. @@ -46,19 +46,19 @@ To configure a webhook integration: For example: - ```json - curl -X POST \ - https://a-prod-us-central-0.grafana.net/integrations/v1/formatted_webhook/m12xmIjOcgwH74UF8CN4dk0Dh/ \ - -H 'Content-Type: Application/json' \ - -d '{ - "alert_uid": "08d6891a-835c-e661-39fa-96b6a9e26552", - "title": "The whole system is down", - "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ee/Grumpy_Cat_by_Gage_Skidmore.jpg", - "state": "alerting", - "link_to_upstream_details": "https://en.wikipedia.org/wiki/Downtime", - "message": "Smth happened. Oh no!" - }' - ``` +```bash +curl -X POST \ +https://a-prod-us-central-0.grafana.net/integrations/v1/formatted_webhook/m12xmIjOcgwH74UF8CN4dk0Dh/ \ +-H 'Content-Type: Application/json' \ +-d '{ + "alert_uid": "08d6891a-835c-e661-39fa-96b6a9e26552", + "title": "The whole system is down", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ee/Grumpy_Cat_by_Gage_Skidmore.jpg", + "state": "alerting", + "link_to_upstream_details": "https://en.wikipedia.org/wiki/Downtime", + "message": "Smth happened. Oh no!" +}' +``` To learn how to use custom alert templates for formatted webhooks, see -[Configure alerts templates]({{< relref "../../../alert-behavior/alert-templates/" >}}). +[Configure alerts templates]({{< relref "jinja2-templating" >}}). diff --git a/docs/sources/integrations/available-integrations/configure-zabbix/index.md b/docs/sources/integrations/zabbix/index.md similarity index 99% rename from docs/sources/integrations/available-integrations/configure-zabbix/index.md rename to docs/sources/integrations/zabbix/index.md index f237abae..a5359743 100644 --- a/docs/sources/integrations/available-integrations/configure-zabbix/index.md +++ b/docs/sources/integrations/zabbix/index.md @@ -9,7 +9,7 @@ keywords: - Notifications - on-call - Zabbix -title: Zabbix integration for Grafana OnCall +title: Zabbix weight: 500 --- diff --git a/docs/sources/integrations/available-integrations/configure-zendesk/index.md b/docs/sources/integrations/zendesk/index.md similarity index 96% rename from docs/sources/integrations/available-integrations/configure-zendesk/index.md rename to docs/sources/integrations/zendesk/index.md index 7ea5fa80..43321f6e 100644 --- a/docs/sources/integrations/available-integrations/configure-zendesk/index.md +++ b/docs/sources/integrations/zendesk/index.md @@ -9,7 +9,7 @@ keywords: - Notifications - on-call - Zendesk -title: Zendesk integration for Grafana OnCall +title: Zendesk weight: 500 --- diff --git a/docs/sources/alert-behavior/alert-templates/index.md b/docs/sources/jinja2-templating/_index.md similarity index 83% rename from docs/sources/alert-behavior/alert-templates/index.md rename to docs/sources/jinja2-templating/_index.md index 3cbfbf38..f710f101 100644 --- a/docs/sources/alert-behavior/alert-templates/index.md +++ b/docs/sources/jinja2-templating/_index.md @@ -1,40 +1,26 @@ --- aliases: - - ../integrations/create-custom-templates/ - - /docs/oncall/latest/alert-behavior/alert-templates/ -canonical: https://grafana.com/docs/oncall/latest/alert-behavior/alert-templates/ -keywords: - - Grafana Cloud - - Alerts - - Notifications - - on-call - - Jinja -title: Configure alert templates -weight: 300 + - /docs/oncall/latest/jinja2-templating/ +canonical: https://grafana.com/docs/oncall/latest/jinja2-templating/ +title: Jinja2 templating +weight: 1000 --- -# Configure alert templates +## Jinja2 templating 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 +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. - -## 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: +an alert received by Grafana OnCall initiated by Grafana Alerting: ```json { @@ -177,3 +163,5 @@ Built-in functions: - `datetimeformat` - converts time from datetime to the given format (`%H:%M / %d-%m-%Y` by default) - `regex_replace` - performs a regex find and replace - `regex_match` - performs a regex match, returns `True` or `False`. Usage example: `{{ payload.ruleName | regex_match(".*") }}` + +{{< section >}} diff --git a/docs/sources/migration-from-other-tools/_index.md b/docs/sources/migration-from-other-tools/_index.md new file mode 100644 index 00000000..faeed7c8 --- /dev/null +++ b/docs/sources/migration-from-other-tools/_index.md @@ -0,0 +1,18 @@ +--- +title: Migration from other tools +aliases: + - /docs/oncall/latest/migration-from-other-tools/ +keywords: + - Mobile App + - oncall + - notification + - push notification +weight: 1400 +--- + +# Migration from other tools + +## Migration from PagerDuty to Grafana OnCall + +Migration from PagerDuty to Grafana OnCall could be performed in automated way using +[OSS Migrator](https://github.com/grafana/oncall/tree/dev/tools/pagerduty-migrator). diff --git a/docs/sources/mobile-app/_index.md b/docs/sources/mobile-app/_index.md index c9549f6e..dea6546a 100644 --- a/docs/sources/mobile-app/_index.md +++ b/docs/sources/mobile-app/_index.md @@ -1,5 +1,5 @@ --- -title: Grafana OnCall mobile app +title: Mobile App aliases: - /docs/oncall/latest/mobile-app/ keywords: @@ -7,7 +7,7 @@ keywords: - oncall - notification - push notification -weight: 1200 +weight: 1100 --- # Grafana OnCall Mobile App @@ -99,5 +99,3 @@ To receive push notifications from the Grafana OnCall mobile app, you must add t 1. From Grafana OnCall, navigate to the **Users** tab and click **View my profile** 1. In your **User Info** tab, update your Default and Important notification policies to include Mobile push notifications. - -For more information about Notification Policies, refer to [Manage users and teams for Grafana OnCall]({{< relref "../configure-user-settings" >}}) diff --git a/docs/sources/notify/_index.md b/docs/sources/notify/_index.md new file mode 100644 index 00000000..0e45fb00 --- /dev/null +++ b/docs/sources/notify/_index.md @@ -0,0 +1,51 @@ +--- +aliases: + - ../notify/ + - /docs/oncall/latest/notify/ +canonical: https://grafana.com/docs/oncall/latest/notify/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - slack +title: Notify people +weight: 800 +--- + +# Notify people + +Grafana OnCall directly supports the export of alert notifications to some popular messaging applications like Slack and +Telegram. You can use [outgoing webhooks]({{< relref "outgoing-webhooks" >}}) for applications that aren't directly +supported. + +To configure supported messaging apps, see the following topics: + +{{< section >}} + +## Configure user notification policies + +Notification policies are a configurable set of notification steps that determine how you're notified of alert in OnCall. Users with the Admin or Editor role are +able to receive notifications. +Users can verify phone numbers and email addresses in the **Users** tab of Grafana OnCall. + +- **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. + +> **NOTE**: You cannot add users or manage permissions in Grafana OnCall. User settings are found on the +> organizational level of your Grafana instance in **Configuration > Users**. + +To configure a users notification policy: + +1. Navigate to the **Users** tab of Grafana OnCall and search for or select a user. + +1. Click **Edit** to the right of a user to open the **User Info** window. + +1. Verify that there is a valid and verified phone number, along with ChatOps accounts in order to receive notifications via those methods. + +1. Click **Add notification step** and use the dropdowns to specify the notification method and frequency. Notification steps will be followed in the order they +are listed. diff --git a/docs/sources/notify/mattermost/index.md b/docs/sources/notify/mattermost/index.md new file mode 100644 index 00000000..e2938be4 --- /dev/null +++ b/docs/sources/notify/mattermost/index.md @@ -0,0 +1,23 @@ +--- +aliases: + - ../../notify/mattermost + - /docs/oncall/latest/notify/mattermost/ +canonical: https://grafana.com/docs/oncall/latest/notify/mattermost/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - slack +title: Mattermost +weight: 100 +--- + +# Mattermost + +Mattermost support is not implemented yet. + +Please join [GitHub Issue](https://github.com/grafana/oncall/issues/96) or +check [PR](https://github.com/grafana/oncall/pull/606). diff --git a/docs/sources/integrations/chatops-integrations/configure-teams/index.md b/docs/sources/notify/ms-teams/index.md similarity index 98% rename from docs/sources/integrations/chatops-integrations/configure-teams/index.md rename to docs/sources/notify/ms-teams/index.md index cc765fb1..226705f7 100644 --- a/docs/sources/integrations/chatops-integrations/configure-teams/index.md +++ b/docs/sources/notify/ms-teams/index.md @@ -12,7 +12,7 @@ keywords: - oncall - MS Team - Microsoft -title: Microsoft Teams integration for Grafana OnCall +title: Microsoft Teams weight: 500 --- diff --git a/docs/sources/notify/phone-calls-sms/index.md b/docs/sources/notify/phone-calls-sms/index.md new file mode 100644 index 00000000..2e14868f --- /dev/null +++ b/docs/sources/notify/phone-calls-sms/index.md @@ -0,0 +1,32 @@ +--- +aliases: + - ../../notify/phone-sms + - /docs/oncall/latest/notify/phone-sms/ +canonical: https://grafana.com/docs/oncall/latest/notify/phone-sms/ +keywords: + - Grafana Cloud + - Alerts + - Notifications + - on-call + - amixr + - oncall + - slack +title: Phone calls and SMS +weight: 100 +--- + +# Phone Calls and SMS notifications + +Grafana OnCall Cloud includes SMS and Phone notifications, OSS users [could leverage]({{< relref "open-source" >}}) Grafana Cloud as a relay or +configure other providers like Twilio. + +## Is there a list of pre-defined phone numbers? + +In order to learn the phone number used by OnCall, make a test call at the "Phone Verification" tab. + +## Phone calls or SMS does not work for me + +There are cases when OnCall is not able to make phone calls or send SMS to certain regions or specific phone numbers. +We're working hard to fix such cases, but kindly asking to test your personal notification chain to make sure OnCall +is able to notify you. Also we suggest to back up Phone Calls and SMS with other notification methods such as +[Mobile App]({{< relref "mobile-app" >}}). diff --git a/docs/sources/integrations/chatops-integrations/configure-slack/index.md b/docs/sources/notify/slack/index.md similarity index 97% rename from docs/sources/integrations/chatops-integrations/configure-slack/index.md rename to docs/sources/notify/slack/index.md index 7e00d3db..925b2209 100644 --- a/docs/sources/integrations/chatops-integrations/configure-slack/index.md +++ b/docs/sources/notify/slack/index.md @@ -11,7 +11,7 @@ keywords: - amixr - oncall - slack -title: Slack integration for Grafana OnCall +title: Slack weight: 100 --- @@ -30,7 +30,7 @@ To install the Slack integration, you must have Admin permissions in your Grafan that you’d like to integrate with. For Open Source Grafana OnCall Slack installation guidance, refer to -[Open Source Grafana OnCall]({{< relref "../../../open-source/" >}}). +[Open Source Grafana OnCall]({{< relref "open-source" >}}). ## Install Slack integration for Grafana OnCall diff --git a/docs/sources/integrations/chatops-integrations/configure-telegram/index.md b/docs/sources/notify/telegram/index.md similarity index 98% rename from docs/sources/integrations/chatops-integrations/configure-telegram/index.md rename to docs/sources/notify/telegram/index.md index e24d87e7..17080b2c 100644 --- a/docs/sources/integrations/chatops-integrations/configure-telegram/index.md +++ b/docs/sources/notify/telegram/index.md @@ -11,7 +11,7 @@ keywords: - amixr - oncall - telegram -title: Telegram integration for Grafana OnCall +title: Telegram weight: 300 --- diff --git a/docs/sources/on-call-schedules/_index.md b/docs/sources/on-call-schedules/_index.md new file mode 100644 index 00000000..65850392 --- /dev/null +++ b/docs/sources/on-call-schedules/_index.md @@ -0,0 +1,46 @@ +--- +title: On-call schedules +aliases: + - /docs/oncall/latest/on-call-schedules/ +canonical: https://grafana.com/docs/oncall/latest/on-call-schedules/ +description: "Learn more about on-call schedules" +keywords: + - Grafana + - oncall + - on-call + - schedule + - calendar +weight: 700 +--- + +## Before you begin + +- Users with Admin or Editor roles can create, edit and delete schedules. +- Users with Viewer role cannot receive alert notifications, therefore, cannot be on-call. + +For more information about permissions, refer to +[Manage users and teams for Grafana OnCall]({{< relref "user-and-team-management" >}}) + +### Web-based schedule + +Configure and manage on-call schedules directly in the Grafana OnCall plugin. Easily configure and preview rotations, +see teammates' time zones, and add overrides. + +Learn more about [Web-based schedules]({{< relref "web-schedule" >}}) + +### iCal import + +Use any calendar service that uses the iCal format to manage and customize on-call schedules - Import rotations and +shifts from your calendar app to Grafana OnCall for widely accessible scheduling. iCal imports appear in Grafana +OnCall as read-only schedules but can be leveraged similarly to a web-based schedule. + +Learn more about [iCal import schedules]({{< relref "ical-schedules" >}}) + +### Terraform + +Use the Grafana OnCall Terraform provider to manage schedules within your “as-code” workflow. Rotations configured +via Terraform are automatically added to your schedules in Grafana OnCall. Similar to the iCal import, these schedules +read-only and cannot be edited from the UI. + +To learn more, read our [Get started with Grafana OnCall and Terraform]( +) blog post. diff --git a/docs/sources/on-call-schedules/api-terraform-schedule/_index.md b/docs/sources/on-call-schedules/api-terraform-schedule/_index.md new file mode 100644 index 00000000..e008838e --- /dev/null +++ b/docs/sources/on-call-schedules/api-terraform-schedule/_index.md @@ -0,0 +1,21 @@ +--- +title: API & Terraform schedules +aliases: + - /docs/oncall/latest/on-call-schedules/api-terraform-schedules/ +canonical: https://grafana.com/docs/oncall/latest/on-call-schedules/api-terraform-schedules/ +keywords: + - Grafana + - oncall + - schedule + - calendar +weight: 100 +--- + +# API & Terraform schedules + +If your schedules became comprehensive, or you would like to distribute the same scheduling patterns through multiple +teams in the org, we suggest considering storing schedules as code. + +- [Get started with Grafana OnCall and Terraform (blogpost)](https://grafana.com/blog/2022/08/29/get-started-with-grafana-oncall-and-terraform/) +- [Grafana Terraform provider reference (OnCall resources are managed using this provider)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_schedule) +- [OnCall API]({{< relref "oncall-api-reference" >}}) diff --git a/docs/sources/calendar-schedules/ical-schedules/index.md b/docs/sources/on-call-schedules/ical-schedules/index.md similarity index 90% rename from docs/sources/calendar-schedules/ical-schedules/index.md rename to docs/sources/on-call-schedules/ical-schedules/index.md index cf4c3aeb..79b9dd75 100644 --- a/docs/sources/calendar-schedules/ical-schedules/index.md +++ b/docs/sources/on-call-schedules/ical-schedules/index.md @@ -1,8 +1,8 @@ --- -title: Import on-call schedules +title: iCal on-call schedules aliases: - - /docs/oncall/latest/calendar-schedules/ical-schedules/ -canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/ical-schedules/ + - /docs/oncall/latest/on-call-schedules/ical-schedules/ +canonical: https://grafana.com/docs/oncall/latest/on-call-schedules/ical-schedules/ description: "Learn how to manage on-call schedules with iCal import" keywords: - Grafana @@ -18,6 +18,11 @@ Use your existing calendar app with iCal format to manage and customize on-call from your calendar app to Grafana OnCall for widely accessible scheduling. iCal imported schedules appear in Grafana OnCall as read-only schedules but can be leveraged similarly to a web-based schedule. +> Unfortunately there is a known limitation with Google Calendar import and export. +> Google may take up to 24h to import OnCall's calendar (OnCall -> Google) and sometimes our customers report delay in +> exporting (Google Calendar -> OnCall). If actual calendar is critical for you, we suggest checking +> [web-based scheduling]({{< relref "web-schedule" >}}). + ## Before you begin - Verify that your calendar app supports iCal format diff --git a/docs/sources/calendar-schedules/web-schedule/_index.md b/docs/sources/on-call-schedules/web-schedule/_index.md similarity index 87% rename from docs/sources/calendar-schedules/web-schedule/_index.md rename to docs/sources/on-call-schedules/web-schedule/_index.md index 0f5500e3..582e1579 100644 --- a/docs/sources/calendar-schedules/web-schedule/_index.md +++ b/docs/sources/on-call-schedules/web-schedule/_index.md @@ -1,8 +1,8 @@ --- -title: Web-based schedules +title: Web-based on-call schedules aliases: - - /docs/oncall/latest/calendar-schedules/web-schedule/ -canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/web-schedule/ + - /docs/oncall/latest/on-call-schedules/web-schedule/ +canonical: https://grafana.com/docs/oncall/latest/on-call-schedules/web-schedule/ description: "Learn more about Grafana OnCalls built in schedule tool" keywords: - Grafana @@ -12,19 +12,18 @@ keywords: weight: 100 --- -# About web-based schedules +# Web-based on-call schedules Grafana OnCall allows you to map out recurring on-call coverage and automate the escalation of alert notifications to on-call users. Configure and manage on-call schedules directly in the Grafana OnCall plugin to easily customize rotations with a live schedule preview, reference teammates' time zones, and add overrides. + + This topic provides an overview of key components and features. -For information on how to create a schedule in Grafana OnCall, refer to -[Create an on-call schedule]({{< relref "create-schedule" >}}) - ->**Note**: User permissions determine which components of Grafana OnCall are available to you. - ## Schedule settings Schedule settings are initially configured when a new schedule is created and can be updated at any time by clicking @@ -86,6 +85,4 @@ A perfectly balanced schedule is considered ideal, so reducing this number will ## Schedule export Export on-call schedules from Grafana OnCall to your preferred calendar app with a one-time secret iCal URL. The -schedule export allows you to view on-call shifts alongside the rest of your schedule. - -For more information, refer to [Export on-call schedules]({{< relref "calendar-export" >}}) +schedule export allows you to view on-call shifts alongside the rest of your schedule. diff --git a/docs/sources/oncall-api-reference/integrations.md b/docs/sources/oncall-api-reference/integrations.md index 507841db..a4af73b8 100644 --- a/docs/sources/oncall-api-reference/integrations.md +++ b/docs/sources/oncall-api-reference/integrations.md @@ -75,7 +75,7 @@ The above command returns JSON structured in the following way: 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/available-integrations/configure-alertmanager/" >}}). +[Alertmanager]({{< relref "../integrations/alertmanager" >}}). **HTTP request** diff --git a/docs/sources/open-source/_index.md b/docs/sources/open-source/_index.md index 9059b9f1..1674e9be 100644 --- a/docs/sources/open-source/_index.md +++ b/docs/sources/open-source/_index.md @@ -4,7 +4,7 @@ aliases: keywords: - Open Source title: Open Source -weight: 300 +weight: 400 --- # Grafana OnCall open source guide @@ -227,7 +227,7 @@ After enabling the email integration, it will be possible to use the `Notify by ## Inbound Email Setup Grafana OnCall is capable of creating alert groups from -[Inbound Email integration]({{< relref "../integrations/available-integrations/configure-inbound-email" >}}). +[Inbound Email integration]({{< relref "../integrations/inbound-email" >}}). To configure Inbound Email integration for Grafana OnCall OSS populate env variables with your Email Service Provider data: diff --git a/docs/sources/alert-behavior/outgoing-webhooks/index.md b/docs/sources/outgoing-webhooks/_index.md similarity index 89% rename from docs/sources/alert-behavior/outgoing-webhooks/index.md rename to docs/sources/outgoing-webhooks/_index.md index 74237bbf..7b80a8da 100644 --- a/docs/sources/alert-behavior/outgoing-webhooks/index.md +++ b/docs/sources/outgoing-webhooks/_index.md @@ -1,8 +1,8 @@ --- aliases: - - ../integrations/configure-outgoing-webhooks/ - - /docs/oncall/latest/alert-behavior/outgoing-webhooks/ -canonical: https://grafana.com/docs/oncall/latest/alert-behavior/outgoing-webhooks/ + - ../outgoing-webhooks/ + - /docs/oncall/latest/outgoing-webhooks/ +canonical: https://grafana.com/docs/oncall/latest/outgoing-webhooks/ keywords: - Grafana Cloud - Alerts @@ -10,8 +10,8 @@ keywords: - on-call - amixr - webhooks -title: Configure outgoing webhooks for Grafana OnCall -weight: 500 +title: Outgoing Webhooks +weight: 900 --- # Configure outgoing webhooks for Grafana OnCall diff --git a/docs/sources/configure-user-settings/_index.md b/docs/sources/user-and-team-management/_index.md similarity index 66% rename from docs/sources/configure-user-settings/_index.md rename to docs/sources/user-and-team-management/_index.md index 4993db89..75682e86 100644 --- a/docs/sources/configure-user-settings/_index.md +++ b/docs/sources/user-and-team-management/_index.md @@ -1,15 +1,12 @@ --- +title: User and team management aliases: - - /docs/oncall/latest/configure-user-settings/ -canonical: https://grafana.com/docs/oncall/latest/configure-user-setting/ + - /docs/oncall/latest/user-and-team-management/ keywords: - - Grafana Cloud - - Permission - - Notifications - - RBAC - - amixr + - Mobile App - oncall -title: Manage users and teams for Grafana OnCall + - notification + - push notification weight: 1300 --- @@ -73,42 +70,3 @@ team, set up multiple routes for the integration, and utilize escalation chains and outgoing webhooks from other teams can also be included in the escalation chain. If a user only has access to the first team and not others, they will be unable to view the resource, which will display as `🔒 Private resource`. This feature enables the distribution of escalations across various teams. - -## Configure user notification policies - -Notification policies are a configurable set of notification steps that determine how you're notified of alert in OnCall. Users with the Admin or Editor role are -able to receive notifications. -Users can verify phone numbers and email addresses in the **Users** tab of Grafana OnCall. - -- **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. - -> **NOTE**: You cannot add users or manage permissions in Grafana OnCall. User settings are found on the -> organizational level of your Grafana instance in **Configuration > Users**. - -To configure a users notification policy: - -1. Navigate to the **Users** tab of Grafana OnCall and search for or select a user. - -1. Click **Edit** to the right of a user to open the **User Info** window. - -1. Verify that there is a valid and verified phone number, along with ChatOps accounts in order to receive notifications via those methods. - -1. Click **Add notification step** and use the dropdowns to specify the notification method and frequency. Notification steps will be followed in the order they -are listed. - -## Configure Telegram user settings in OnCall - -1. In your profile, navigate to Telegram setting and click **Connect**. -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. - -To connect manually, you can click the URL provided and then **SEND MESSAGE**. In your Telegram account, -click **Start**. - -## 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.