From 85d94d342e93f44068069112f1d3b8faddf9825d Mon Sep 17 00:00:00 2001 From: Matvey Kukuy Date: Wed, 2 Nov 2022 16:58:47 +0200 Subject: [PATCH] Readme about how to add Integrations and Zabbix Integration (#653) * Readme and zabbix * Typos * Linking --- DEVELOPER.md | 2 + README.md | 1 + engine/config_integrations/README.md | 21 ++++++++++ engine/config_integrations/zabbix.py | 62 ++++++++++++++++++++++++++++ engine/settings/base.py | 1 + 5 files changed, 87 insertions(+) create mode 100644 engine/config_integrations/README.md create mode 100644 engine/config_integrations/zabbix.py diff --git a/DEVELOPER.md b/DEVELOPER.md index e65f186a..f85cf648 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -20,6 +20,8 @@ ## Developer quickstart +Related: [How to develop integrations](/engine/config_integrations/README.md) + ### Code style - [isort](https://github.com/PyCQA/isort), [black](https://github.com/psf/black) and [flake8](https://github.com/PyCQA/flake8) are used to format backend code diff --git a/README.md b/README.md index 08019328..96455f6e 100644 --- a/README.md +++ b/README.md @@ -87,5 +87,6 @@ See [Grafana docs](https://grafana.com/docs/grafana/latest/administration/plugin - _Migration from the PagerDuty_ - [Migrator](https://github.com/grafana/oncall/tree/dev/tools/pagerduty-migrator) - _Documentation_ - [Grafana OnCall](https://grafana.com/docs/grafana-cloud/oncall/) +- _How To Add Integration_ - [How to Add Integration](https://github.com/grafana/oncall/tree/dev/engine/config_integrations/README.md) - _Blog Post_ - [Announcing Grafana OnCall, the easiest way to do on-call management](https://grafana.com/blog/2021/11/09/announcing-grafana-oncall/) - _Presentation_ - [Deep dive into the Grafana, Prometheus, and Alertmanager stack for alerting and on-call management](https://grafana.com/go/observabilitycon/2021/alerting/?pg=blog) diff --git a/engine/config_integrations/README.md b/engine/config_integrations/README.md new file mode 100644 index 00000000..13c7189d --- /dev/null +++ b/engine/config_integrations/README.md @@ -0,0 +1,21 @@ +# Contribute the new Integration to OnCall + +Related: [DEVELOPER.md](/DEVELOPER.md) + +"Integration" in OnCall is a pre-configured webhook for alert consumption from alert sources. Usually, alert sources are monitoring systems such as Grafana or Zabbix. + +Integration is a set of "templates" which are dumped from the integration config once the integration is created. Further changes to "templates" don't reflect on the integration config. Read more about templates [here](https://grafana.com/docs/oncall/latest/integrations/create-custom-templates/). + +This instruction is supposed to help you to build templates to integrate OnCall with a new source of alerts. If you don't want to contribute to OnCall and are looking for a help integrating with custom alert source as a user, refer to [this](https://grafana.com/docs/oncall/latest/integrations/create-custom-templates/) instruction. + +# Files related to Integrations +0. Refer to "Grafana" integration as the most complete example. +1. Each integration should have a `{{integration_name_in_snake_case}}.py` file in `/engine/config_integrations`. There you'll find Templates that will be copied to the Integration Templates once the integration is created by the user in the OnCall UI; Example Payload; and Tests which should match the result of the rendering of Example Payload as using Templates. The best way to build such a file is to create Webhook Integration, write & debug templates in the UI first and copy-paste them to the file after. +2. Each integration should be listed in the `/engine/settings/base.py` file, section `INSTALLED_ONCALL_INTEGRATIONS`. +3. Each integration should have "How to connect" instruction stored as `integration_{{integration_name_in_snake_case}}.html` in the `engine/apps/integrations/html` folder. `.py` file has a `slug` field that is used to locate `.html` file. + +# What do we expect from high-quality integration? + +1. User-friendly integration instruction. +2. Proper grouping following source's logics. If source generates multiple alerts per "detection" it would be nice to provide suitable grouping & resolving configuration in the templates. +3. Awesome rendering. We all love when alerts look good in Slack, SMS and all other rendering destinations. diff --git a/engine/config_integrations/zabbix.py b/engine/config_integrations/zabbix.py new file mode 100644 index 00000000..63b3e3b5 --- /dev/null +++ b/engine/config_integrations/zabbix.py @@ -0,0 +1,62 @@ +# Main +enabled = True +title = "Zabbix" +slug = "zabbix" +short_description = None +description = None +is_displayed_on_web = True +is_featured = False +is_able_to_autoresolve = True +is_demo_alert_enabled = True + +description = None + +# Default templates +slack_title = """\ +*<{{ grafana_oncall_link }}|#{{ grafana_oncall_incident_id }} {{ payload.get("title", "Title undefined (check Slack Title Template)") }}>* via {{ integration_name }} +{% if source_link %} + (*<{{ source_link }}|source>*) +{%- endif %}""" + +slack_message = '{{ payload.get("message", "") }}' + +slack_image_url = '{{ payload.get("image_url", "") }}' + +web_title = '{{ payload.get("title", "Title undefined (check Web Title Template)") }}' + +web_message = slack_message + +web_image_url = slack_image_url + +sms_title = web_title + +phone_call_title = sms_title + +email_title = web_title + +email_message = web_message + +telegram_title = sms_title + +telegram_message = slack_message + +telegram_image_url = slack_image_url + +source_link = "{{ payload.link_to_upstream_details }}" + +grouping_id = '{{ payload.get("alert_uid", "")}}' + +resolve_condition = '{{ payload.get("state", "").upper() == "OK" }}' + +acknowledge_condition = None + +group_verbose_name = web_title + +example_payload = { + "alert_uid": "08d6891a-835c-e661-39fa-96b6a9e26552", + "title": "TestAlert: 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": "This alert was sent by user for the demonstration purposes\nSmth happened. Oh no!", +} diff --git a/engine/settings/base.py b/engine/settings/base.py index e701ea24..b95a389c 100644 --- a/engine/settings/base.py +++ b/engine/settings/base.py @@ -586,6 +586,7 @@ INSTALLED_ONCALL_INTEGRATIONS = [ "config_integrations.maintenance", "config_integrations.manual", "config_integrations.slack_channel", + "config_integrations.zabbix", ] if OSS_INSTALLATION: