Grafana OnCall open source guide
Grafana OnCall is a developer-friendly incident response tool that’s available to Grafana open source and Grafana Cloud users. The OSS version of Grafana OnCall provides the same reliable on-call management solution along with the flexibility of a self-managed environment.
This guide describes the necessary installation and configuration steps needed to configure OSS Grafana OnCall.
The intended audience for this guide includes:
- Grafana open source admins who are responsible for deploying and configuring Grafana OnCall.
- Grafana open source users who need to configure SMS and phone notifications using Grafana Cloud.
Install Grafana OnCall OSS
There are three Grafana OnCall OSS environments available:
- Hobby playground environment for local usage: README.md
- Development environment for contributors: DEVELOPER.md
- Production environment for reliable Cloud installation: Production Environment
For detailed installation instructions and additional resources, refer to the OSS Grafana OnCall README.md
For more information on production environment installation, refer to the following OSS Grafana OnCall production environment helm chart
Configure Slack for Grafana OnCall OSS
The Slack integration for Grafana OnCall leverages Slack API features to provide a customizable and useful integration. Refer to the following steps to configure the Slack integration:
-
Ensure your Grafana OnCall environment is up and running.
-
Grafana OnCall must be accessible through HTTPS. For development purposes, use localtunnel. For production purposes, consider establishing a proper web server with HTTPS termination. For localtunnel, refer to the following configuration:
# 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 <ONCALL_ENGINE_PUBLIC_URL> below
lt --port 8080 -s pretty-turkey-83 --print-requests
-
If using localtunnel, open your external URL and click Continue to allow requests to bypass the warning page.
-
Create a Slack Workspace for development, or use your company workspace.
-
Go to https://api.slack.com/apps and click Create an App .
-
Select
From an app manifest
option and select your workspace. -
Replace the text with the following YAML code block . Be sure to replace
<YOUR_BOT_NAME>
and<ONCALL_ENGINE_PUBLIC_URL>
fields with the appropriate information.
_metadata:
major_version: 1
minor_version: 1
display_information:
name: <YOUR_BOT_NAME>
features:
app_home:
home_tab_enabled: true
messages_tab_enabled: true
messages_tab_read_only_enabled: false
bot_user:
display_name: <YOUR_BOT_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: <ONCALL_ENGINE_PUBLIC_URL>/slack/interactive_api_endpoint/
description: oncall
should_escape: false
oauth_config:
redirect_urls:
- <ONCALL_ENGINE_PUBLIC_URL>/api/internal/v1/complete/slack-install-free/
- <ONCALL_ENGINE_PUBLIC_URL>/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: <ONCALL_ENGINE_PUBLIC_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: <ONCALL_ENGINE_PUBLIC_URL>/slack/interactive_api_endpoint/
org_deploy_enabled: false
socket_mode_enabled: false
-
Set environment variables by navigating to your Grafana OnCall, then click Env Variables and set the following:
SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret SLACK_SIGNING_SECRET = Basic Information -> App Credentials -> Signing Secret SLACK_INSTALL_RETURN_REDIRECT_HOST = << OnCall external URL >>
-
In OnCall, navigate to ChatOps, select Slack and click Install Slack integration.
-
Configure additional Slack settings.
Configure Telegram for Grafana OnCall OSS
The Telegram integration for Grafana OnCall is designed for collaborative team work and improved incident response. Refer to the following steps to configure the Telegram integration:
-
Ensure your OnCall environment is up and running.
-
Request BotFather for a key, then add your key in
TELEGRAM_TOKEN
in your Grafana OnCall Env Variables. -
Set
TELEGRAM_WEBHOOK_HOST
with your external URL for your Grafana OnCall. -
From the ChatOps tab in Grafana OnCall, click Telegram.
Connect Grafana Cloud to Grafana OnCall OSS
Open source Grafana OnCall can be connected to Grafana Cloud to configure a variety of notifications.
The benefits of connecting to Grafana Cloud include:
- Heartbeat notification
- SMS for user notifications
- Phone calls for user notifications.
To connect to Grafana Cloud, refer to the Cloud page in your OSS Grafana OnCall instance.
NOTE: As an alternative option to Grafana Cloud, phone call and SMS notifications can be configured using Twilio.
Connect Twilio for Grafana OnCall OSS
Grafana OnCall supports Twilio SMS and phone call notifications delivery. If you prefer to configure SMS and phone call notifications using Twilio, complete the following steps:
- Set
GRAFANA_CLOUD_NOTIFICATIONS_ENABLED
as False to ensure the Grafana OSS <-> Cloud connector is disabled. - From your OnCall environment, select Env Variables and configure all variables starting with
TWILIO_
.
Related Grafana Cloud resources
Intro to Prometheus and Grafana Cloud
Prometheus is taking over the monitoring world! In this webinar, we will start with a quick introduction to the open source project that’s the de facto standard for monitoring modern, cloud native systems.
How to set up and visualize synthetic monitoring at scale with Grafana Cloud
Learn how to use Kubernetes, Grafana Loki, and Grafana Cloud’s synthetic monitoring feature to set up your infrastructure's checks in this GrafanaCONline session.
Using Grafana Cloud to drive manufacturing plant efficiency
This GrafanaCONline session tells how Grafana helps a 75-year-old manufacturing company with product quality and equipment maintenance.