diff --git a/docs/sources/calendar-schedules/_index.md b/docs/sources/calendar-schedules/_index.md index 991e409d..201aa5de 100644 --- a/docs/sources/calendar-schedules/_index.md +++ b/docs/sources/calendar-schedules/_index.md @@ -1,68 +1,51 @@ --- +title: On-call schedules aliases: - /docs/oncall/latest/calendar-schedules/ canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/ -description: "" +description: "Learn more about on-call schedules" keywords: - Grafana - oncall - - on-call + - schedule - calendar -title: Configure and manage on-call schedules weight: 1100 --- -# Configure and manage on-call schedules +# 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. +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 -To learn more about creating on-call calendars, see the following topics: +This section provides conceptual information about Grafana OnCall schedule options. -## Configure and manage on-call schedules +## About 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. +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. -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. +A fully configured on-call schedule consists of three main components: -## Create an on-call schedule calendar +- **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. -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. +## 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. - 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. +### 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. -1. Create overlapping schedules (optional). +Learn more about [Web-based schedules]({{< relref "web-schedule" >}}) - 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]`. +### 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. -# Create an override calendar (optional) +Learn more about [iCal import schedules]({{< relref "ical-schedules" >}}) -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. +### 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 are read-only and cannot be edited from the UI. -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**. +To learn more, read our [Get started with Grafana OnCall and Terraform](https://grafana.com/blog/2022/08/29/get-started-with-grafana-oncall-and-terraform/) blog post. \ No newline at end of file diff --git a/docs/sources/calendar-schedules/ical-schedules/index.md b/docs/sources/calendar-schedules/ical-schedules/index.md new file mode 100644 index 00000000..0950e51e --- /dev/null +++ b/docs/sources/calendar-schedules/ical-schedules/index.md @@ -0,0 +1,79 @@ +--- +title: Import on-call schedules +aliases: + - /docs/oncall/latest/calendar-schedules/ical-schedules/ +canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/ical-schedules/ +description: "Learn how to manage on-call schedules with iCal import" +keywords: + - Grafana + - oncall + - on-call + - calendar +weight: 300 +--- + +# Import on-call schedules + +Use your existing calendar app with 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 imported schedules appear in Grafana OnCall as read-only schedules but can be leveraged similarly to a web-based schedule. + +## Before you begin + +- Verify that your calendar app supports iCal format +- Ensure you have the proper permissions in Grafana OnCall + +## Configure an on-call schedule from iCal import + +There are three key parts to configuring on-call schedules using iCal import: +1. Create a primary on-call calendar and an optional override calendar in your calendar app. +1. Import the calendars into Grafana OnCall and configure additional schedule settings. +1. Link your schedule to corresponding escalation chains for alert notifications to be sent to the proper on-call user. + +### Create your on-call schedule calendar + +Create a dedicated calendar to map out your on-call coverage using calendar events. Be sure to take advantage of the features of your calendar app to configure event recurrence, duplicate events, etc. + +>**Note:** The exact steps in this section will vary based on your calendar. + +To create an on-call schedule calendar: + +1. Create a new calendar in your calendar app, then review and adjust default settings as needed. +1. In your new calendar, create events that represent on-call shifts. You must use Grafana usernames as the event title to associate users with each shift. +1. Once your on-call calendar is complete, go to your calendar settings to locate the secret iCal URL. For example, in a Google calendar, this URL can be found in **Settings** > **Settings for my calendars** > **Integrate calendar** > **Secret address in iCal format**. + +To learn more about how to configure your calendar events, refer to Calendar events. + +### Import calendar to Grafana On-Call + +Once you’ve configured on-call schedules in your calendar app, you can import them via iCal URL to your Grafana OnCall instance. + +>**Note:** Use the secret iCal URL to avoid making the calendar public. If you use the public iCal URL, the calendar and event details must be public for Grafana OnCall to read your calendar. + +To import an on-call schedule: + +1. In Grafana OnCall, navigate to the **Schedules** tab and click **+ New schedule**. +1. Navigate to **Import schedule from iCal URL** and click **+ Create**. +1. Copy the secret iCal URL from your calendar and paste it the **Primary schedule iCal URL** field. Repeat this step for the **Override schedule iCal URL** field if you have an override calendar. +1. Provide a name and review available schedule settings. +1. When you’re done, click **Create Schedule**. + + +### Create an override calendar (Optional) + +An override calendar allows for on-call flexibility without modifying the primary schedule. You can use an override calendar to enable users to schedule on-call shifts that will override 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. +1. Be sure to set permissions that allow team members to edit the calendar. +1. In the **Schedules** tab of Grafana OnCall, select the primary calendar you want to override.Click **Edit**. +1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. + +## Calendar events + +Whether your schedule is basic or complex, consider how your on-call coverage is structured before configuring your calendar events. To minimize the number of calendar events you need to create, try leveraging recurrence settings and event duplication. + +> **Note:** Each calendar event represents one on-call shift for a specific user. For Grafana OnCall to associate a calendar event with the intended on-call user, you must use their Grafana username as the event title. + +### Create overlapping schedules (optional) + +If you create schedules that overlap, you can prioritize a schedule by adding a level marker to the calendar event title. You can prioritize schedule overlaps using [L0] - [L9] prioritization. Overlapping calendar events that do not contain a level marker result in all overlapping users receiving notifications. + +For example, users AliceGrafana and BobGrafana have overlapping schedules but BobGrafana is the intended primary contact. The calendar events titles would be `[L1] BobGrafana` and `[L0] AliceGrafana` - In this case AliceGrafana maintains the default [L0] status, and would not receive notifications during the overlapping time with BobGrafana. diff --git a/docs/sources/calendar-schedules/web-schedule/_index.md b/docs/sources/calendar-schedules/web-schedule/_index.md new file mode 100644 index 00000000..aecf3b0a --- /dev/null +++ b/docs/sources/calendar-schedules/web-schedule/_index.md @@ -0,0 +1,53 @@ +--- +title: Web-based schedules +aliases: + - /docs/oncall/latest/calendar-schedules/web-schedule/ +canonical: https://grafana.com/docs/oncall/latest/calendar-schedules/web-schedule/ +description: "Learn more about Grafana OnCalls built in schedule tool" +keywords: + - Grafana + - oncall + - schedule + - calendar +weight: 100 +--- + +# About web-based 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 the gear icon next to an existing schedule. + +Available schedule settings: + +- **Slack channel:** Choose a primary Slack channel to send notifications about on-call shifts, such as unassigned on-call shifts. +- **Slack user group:** Choose a Slack user group to receive current on-call updates. +- **Notification frequency:** Specify whether or not to send shift notifications to scheduled team members. +- **Action for slot when no one is on-call:** Define how your team is notified when an empty shift causes a gap in on-call coverage. +- **Current shift notification settings:** Select how users are notified when their on-call shift begins. +- **Next shift notification settings:** Specify how users are notified of upcoming shifts. + +## Schedule view + +The schedule view is a detailed calendar representation of your on-call schedule. It contains three interactive weekly calendars and a 24-hour on-call status bar for visualizing who’s on-call and what time it is for your teammates. + +Understand your schedule view: + +- **Final schedule:** The final schedule provides a combined view of rotations and overrides +- **Rotations:** The rotations calendar represents all recurring on-call rotations for a given schedule. +- **Overrides:** The override calendar represents temporary adjustments to the recurring on-call schedule. Any events on this calendar will take precedence over the rotations calendar. + +## 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" >}}) diff --git a/docs/sources/calendar-schedules/web-schedule/calendar-export/index.md b/docs/sources/calendar-schedules/web-schedule/calendar-export/index.md new file mode 100644 index 00000000..dda4d0bd --- /dev/null +++ b/docs/sources/calendar-schedules/web-schedule/calendar-export/index.md @@ -0,0 +1,67 @@ +--- +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. + +[comment]: <> (>**Note**: Use caution when revoking an iCal link associated with shared on-call schedules. If you aren't the creator of the existing iCal link, check with your teammates before revoking it.) + +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 new file mode 100644 index 00000000..ebd52339 --- /dev/null +++ b/docs/sources/calendar-schedules/web-schedule/create-schedule/index.md @@ -0,0 +1,69 @@ +--- +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. + +## 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**. + + +[comment]: <> (For further instruction on rotation configuration, refer to Manage and configure rotations) + +### 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" >}}) \ No newline at end of file