From c08eeb72a3e743da68c29e797331913d7ddb4da5 Mon Sep 17 00:00:00 2001 From: Joey Orlando Date: Thu, 1 Dec 2022 14:26:54 +0100 Subject: [PATCH] add precommit rules for markdown/json files (#915) * add markdownlint precommit steps + fix existing errors * prettier json linting --- .github/issue_and_pr_commands.json | 16 +- .github/pull_request_template.md | 9 +- .markdownlint.json | 12 + .pre-commit-config.yaml | 18 +- CHANGELOG.md | 36 ++- CODE_OF_CONDUCT.md | 25 +- GOVERNANCE.md | 117 ++++++--- LICENSING.md | 4 +- MAINTAINERS.md | 3 + README.md | 46 ++-- SECURITY.md | 20 +- dev/README.md | 117 ++++++--- docs/.markdownlint.json | 5 + docs/README.md | 6 +- docs/sources/_index.md | 25 +- docs/sources/alert-behavior/_index.md | 13 +- .../alert-behavior/alert-templates/index.md | 37 ++- .../alert-behavior/outgoing-webhooks/index.md | 14 +- docs/sources/calendar-schedules/_index.md | 36 +-- .../sources/configure-user-settings/_index.md | 26 +- docs/sources/escalation-policies/_index.md | 3 +- .../configure-escalation-chains/index.md | 12 +- .../configure-routes/index.md | 34 ++- docs/sources/get-started/_index.md | 75 ++++-- docs/sources/integrations/_index.md | 23 +- .../available-integrations/_index.md | 10 +- .../configure-alertmanager/index.md | 34 +-- .../configure-grafana-alerting/index.md | 48 ++-- .../configure-webhook/index.md | 12 +- .../configure-zabbix/index.md | 17 +- .../chatops-integrations/_index.md | 4 +- .../configure-slack/index.md | 46 ++-- .../configure-teams/index.md | 43 ++- .../configure-telegram/index.md | 15 +- docs/sources/oncall-api-reference/_index.md | 6 +- .../oncall-api-reference/alertgroups.md | 7 +- .../escalation_policies.md | 4 + .../oncall-api-reference/integrations.md | 6 +- .../oncall-api-reference/on_call_shifts.md | 8 +- .../personal_notification_rules.md | 4 + docs/sources/oncall-api-reference/routes.md | 6 +- .../sources/oncall-api-reference/schedules.md | 4 + .../oncall-api-reference/user_groups.md | 4 + docs/sources/open-source/_index.md | 245 ++++++++++-------- engine/config_integrations/README.md | 30 ++- grafana-plugin/babel.config.json | 2 +- helm/README.md | 13 +- helm/oncall/README.md | 29 ++- tools/pagerduty-migrator/README.md | 51 ++-- tools/pagerduty-migrator/scripts/README.md | 6 +- 50 files changed, 894 insertions(+), 492 deletions(-) create mode 100644 .markdownlint.json create mode 100644 docs/.markdownlint.json diff --git a/.github/issue_and_pr_commands.json b/.github/issue_and_pr_commands.json index a1f4ec21..7b11337b 100644 --- a/.github/issue_and_pr_commands.json +++ b/.github/issue_and_pr_commands.json @@ -1,10 +1,10 @@ -[ - { - "type": "label", - "name": "type/docs", - "action": "addToProject", - "addToProject": { - "url": "https://github.com/orgs/grafana/projects/69" - } +[ + { + "type": "label", + "name": "type/docs", + "action": "addToProject", + "addToProject": { + "url": "https://github.com/orgs/grafana/projects/69" } + } ] diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d70b0e4f..0fab1e81 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,8 +1,9 @@ -**What this PR does**: +# What this PR does -**Which issue(s) this PR fixes**: +## Which issue(s) this PR fixes + +## Checklist -**Checklist** - [ ] Tests updated - [ ] Documentation added -- [ ] `CHANGELOG.md` updated \ No newline at end of file +- [ ] `CHANGELOG.md` updated diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..62ff374f --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,12 @@ +{ + "default": true, + "MD013": { + "line_length": "120" + }, + "MD024": { + "siblings_only": true + }, + "MD033": { + "allowed_elements": ["img"] + } +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f61d3a85..9bc86f5a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -39,10 +39,16 @@ repos: rev: "v2.7.1" hooks: - id: prettier - types_or: [css, javascript, jsx, ts, tsx, json] + name: prettier + types_or: [css, javascript, jsx, ts, tsx] files: ^grafana-plugin/src additional_dependencies: - prettier@^2.7.1 + - id: prettier + name: prettier - json + types_or: [json] + additional_dependencies: + - prettier@^2.7.1 - repo: https://github.com/thibaudcolas/pre-commit-stylelint rev: v13.13.1 @@ -56,3 +62,13 @@ repos: - stylelint-prettier@^2.0.0 - stylelint-config-standard@^22.0.0 - stylelint-config-prettier@^9.0.3 + + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.32.2 + hooks: + - id: markdownlint + name: markdownlint + entry: markdownlint --ignore grafana-plugin/node_modules --ignore grafana-plugin/dist --ignore docs **/*.md + - id: markdownlint + name: markdownlint - docs + entry: markdownlint --ignore grafana-plugin/node_modules --ignore grafana-plugin/dist -c ./docs/.markdownlint.json ./docs/**/*.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 45a11160..8c2a6195 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,16 +19,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- When editing templates for alert group presentation or outgoing webhooks, errors and warnings are now displayed in the UI as notification popups or displayed in the preview. -- Errors and warnings that occur when rendering templates during notification or webhooks will now render and display the error/warning as the result. +- When editing templates for alert group presentation or outgoing webhooks, errors and warnings are now displayed in + the UI as notification popups or displayed in the preview. +- Errors and warnings that occur when rendering templates during notification or webhooks will now render + and display the error/warning as the result. ## v1.1.5 (2022-11-24) ### Added -- Added a QR code in the "Mobile App Verification" tab on the user settings modal to connect the mobile application to your OnCall instance - -## v1.1.5 (2022-11-24) +- Added a QR code in the "Mobile App Verification" tab on the user settings modal to connect the mobile + application to your OnCall instance ### Fixed @@ -48,13 +49,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- For OSS installations of OnCall, initial configuration is now simplified. When running for local development, you no longer need to configure the plugin via the UI. This is achieved through passing one environment variable to both the backend & frontend containers, both of which have been preconfigured for you in `docker-compose-developer.yml`. - - The Grafana API URL **must be** passed as an environment variable, `GRAFANA_API_URL`, to the OnCall backend (and can be configured by updating this env var in your `./dev/.env.dev` file) - - The OnCall API URL can optionally be passed as an environment variable, `ONCALL_API_URL`, to the OnCall UI. If the environment variable is found, the plugin will "auto-configure", otherwise you will be shown a simple configuration form to provide this info. -- For Helm installations, if you are running Grafana externally (eg. `grafana.enabled` is set to `false` in your `values.yaml`), you will now be required to specify `externalGrafana.url` in `values.yaml`. -- `make start` will now idempotently check to see if a "127.0.0.1 grafana" record exists in `/etc/hosts` (using a tool called [`hostess`](https://github.com/cbednarski/hostess)). This is to support using `http://grafana:3000` as the `Organization.grafana_url` in two scenarios: +- For OSS installations of OnCall, initial configuration is now simplified. When running for local development, you no + longer need to configure the plugin via the UI. This is achieved through passing one environment variable to both the + backend & frontend containers, both of which have been preconfigured for you in `docker-compose-developer.yml`. + - The Grafana API URL **must be** passed as an environment variable, `GRAFANA_API_URL`, to the OnCall backend + (and can be configured by updating this env var in your `./dev/.env.dev` file) + - The OnCall API URL can optionally be passed as an environment variable, `ONCALL_API_URL`, to the OnCall UI. + If the environment variable is found, the plugin will "auto-configure", otherwise you will be shown a simple + configuration form to provide this info. +- For Helm installations, if you are running Grafana externally (eg. `grafana.enabled` is set to `false` + in your `values.yaml`), you will now be required to specify `externalGrafana.url` in `values.yaml`. +- `make start` will now idempotently check to see if a "127.0.0.1 grafana" record exists in `/etc/hosts` + (using a tool called [`hostess`](https://github.com/cbednarski/hostess)). This is to support using `http://grafana:3000` + as the `Organization.grafana_url` in two scenarios: - `oncall_engine`/`oncall_celery` -> `grafana` Docker container communication - - public URL generation. There are some instances where `Organization.grafana_url` is referenced to generate public URLs to a Grafana plugin page. Without the `/etc/hosts` record, navigating to `http://grafana:3000/some_page` in your browser, you would obviously get an error from your browser. + - public URL generation. There are some instances where `Organization.grafana_url` is referenced to generate public + URLs to a Grafana plugin page. Without the `/etc/hosts` record, navigating to `http://grafana:3000/some_page` in + your browser, you would obviously get an error from your browser. ## v1.1.2 (2022-11-18) @@ -282,7 +293,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## 1.0.2 (2022-06-17) - Fix Grafana Alerting integration to handle API changes in Grafana 9 -- Improve public api endpoint for outgoing webhooks (/actions) by adding ability to create, update and delete outgoing webhook instance +- Improve public api endpoint for outgoing webhooks (/actions) by adding ability to create, update and delete + outgoing webhook instance ## 1.0.0 (2022-06-14) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 3d4caa4f..b3672f83 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,7 +2,10 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make +participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, +disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, +religion, or sexual identity and orientation. ## Our Standards @@ -24,19 +27,29 @@ Examples of unacceptable behavior by participants include: ## Our Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take +appropriate and fair corrective action in response to any instances of unacceptable behavior. -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, +issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the +project or its community. Examples of representing a project or community include using an official project e-mail address, +posting via an official social media account, or acting as an appointed representative at an online or offline event. +Representation of a project may be further defined and clarified by project maintainers. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at conduct@grafana.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at +conduct@grafana.com. The project team will review and investigate all complaints, and will respond in a way that it deems +appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter +of an incident. Further details of specific enforcement policies may be posted separately. -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent +repercussions as determined by other members of the project's leadership. ## Attribution diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 9a63fb65..78186fd3 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,38 +1,46 @@ ---- -title: Governance ---- - # Governance -This document describes the rules and governance of the project. It is meant to be followed by all the developers of the project and the OnCall community. Common terminology used in this governance document are listed below: +This document describes the rules and governance of the project. It is meant to be followed by all the developers +of the project and the OnCall community. Common terminology used in this governance document are listed below: - **Team members**: Any members of the private [team mailing list][team]. - - **Maintainers**: Maintainers lead an individual project or parts thereof ([`MAINTAINERS.md`][maintainers]). - - **Projects**: A single repository in the Grafana GitHub organization and listed below is referred to as a project: - oncall -- **The OnCall project**: The sum of all activities performed under this governance, concerning one or more repositories or the community. +- **The OnCall project**: The sum of all activities performed under this governance, concerning one or more + repositories or the community. ## Values -The OnCall developers and community are expected to follow the values defined in the [Code of Conduct][coc]. Furthermore, the OnCall community strives for kindness, giving feedback effectively, and building a welcoming environment. The OnCall developers generally decide by consensus and only resort to conflict resolution by a majority vote if consensus cannot be reached. +The OnCall developers and community are expected to follow the values defined in the [Code of Conduct][coc]. Furthermore, +the OnCall community strives for kindness, giving feedback effectively, and building a welcoming environment. The OnCall +developers generally decide by consensus and only resort to conflict resolution by a majority vote if +consensus cannot be reached. ## Projects -Each project must have a [`MAINTAINERS.md`][maintainers] file with at least one maintainer. Where a project has a release process, access and documentation should be such that more than one person can perform a release. Releases should be announced on the [announcements][announce] category at the GitHub Discussions. Any new projects should be first proposed on the [team mailing list][team] following the voting procedures listed below. +Each project must have a [`MAINTAINERS.md`][maintainers] file with at least one maintainer. Where a project has a release +process, access and documentation should be such that more than one person can perform a release. Releases should be +announced on the [announcements][announce] category at the GitHub Discussions. Any new projects should be first proposed +on the [team mailing list][team] following the voting procedures listed below. ## Decision making ### Team members -Team member status may be given to those who have made ongoing contributions to the OnCall project for at least 3 months. This is usually in the form of code improvements and/or notable work on documentation, but organizing events or user support could also be taken into account. +Team member status may be given to those who have made ongoing contributions to the OnCall project for at least 3 months. +This is usually in the form of code improvements and/or notable work on documentation, but organizing events or +user support could also be taken into account. -New members may be proposed by any existing member by email to the [team mailing list][team]. It is highly desirable to reach consensus about acceptance of a new member. However, the proposal is ultimately voted on by a formal [supermajority vote](#supermajority-vote). +New members may be proposed by any existing member by email to the [team mailing list][team]. It is highly desirable +to reach consensus about acceptance of a new member. However, the proposal is ultimately voted on by a +formal [supermajority vote](#supermajority-vote). -If the new member proposal is accepted, the proposed team member should be contacted privately via email to confirm or deny their acceptance of team membership. This email will also be CC'd to the [team mailing list][team] for record-keeping purposes. +If the new member proposal is accepted, the proposed team member should be contacted privately via email to confirm +or deny their acceptance of team membership. This email will also be CC'd to the [team mailing list][team] for +record-keeping purposes. If they choose to accept, the [onboarding](#onboarding) procedure is followed. @@ -57,6 +65,7 @@ The current team members are: - Yulia Shanyrova — [@Ukochka](https://github.com/Ukochka) ([Grafana Labs](https://grafana.com/)) - Maxim Mordasov — [@maskin25](https://github.com/maskin25) ([Grafana Labs](https://grafana.com/)) - Julia Artyukhina — [@Ferril](https://github.com/Ferril) ([Grafana Labs](https://grafana.com/)) +- Joey Orlando - [@joeyorlando](https://github.com/joeyorlando) ([Grafana Labs](https://grafana.com/)) Previous team members: @@ -64,21 +73,31 @@ Previous team members: ### Maintainers -Maintainers lead one or more project(s) or parts thereof and serve as a point of conflict resolution amongst the contributors to this project. Ideally, maintainers are also team members, but exceptions are possible for suitable maintainers that, for whatever reason, are not yet team members. +Maintainers lead one or more project(s) or parts thereof and serve as a point of conflict resolution amongst the +contributors to this project. Ideally, maintainers are also team members, but exceptions are possible for suitable +maintainers that, for whatever reason, are not yet team members. -Changes in maintainership have to be announced on the [announcemount][announce] category at the GitHub Discussions. They are decided by [rough consensus](#consensus) and formalized by changing the [`MAINTAINERS.md`][maintainers] file of the respective repository. +Changes in maintainership have to be announced on the [announcemount][announce] category at the GitHub Discussions. +They are decided by [rough consensus](#consensus) and formalized by changing the [`MAINTAINERS.md`][maintainers] +file of the respective repository. Maintainers are granted commit rights to all projects covered by this governance. -A maintainer or committer may resign by notifying the [team mailing list][team]. A maintainer with no project activity for a year is considered to have resigned. Maintainers that wish to resign are encouraged to propose another team member to take over the project. +A maintainer or committer may resign by notifying the [team mailing list][team]. A maintainer with no project activity +for a year is considered to have resigned. Maintainers that wish to resign are encouraged to propose another team +member to take over the project. -A project may have multiple maintainers, as long as the responsibilities are clearly agreed upon between them. This includes coordinating who handles which issues and pull requests. +A project may have multiple maintainers, as long as the responsibilities are clearly agreed upon between them. This +includes coordinating who handles which issues and pull requests. ### Technical decisions -Technical decisions that only affect a single project are made informally by the maintainer of this project, and [rough consensus](#consensus) is assumed. Technical decisions that span multiple parts of the project should be discussed and made on the the [GitHub Discussions][discussions]. +Technical decisions that only affect a single project are made informally by the maintainer of this project, and +[rough consensus](#consensus) is assumed. Technical decisions that span multiple parts of the project should be +discussed and made on the the [GitHub Discussions][discussions]. -Decisions are usually made by [rough consensus](#consensus). If no consensus can be reached, the matter may be resolved by [majority vote](#majority-vote). +Decisions are usually made by [rough consensus](#consensus). If no consensus can be reached, the matter may be resolved +by [majority vote](#majority-vote). ### Governance changes @@ -86,7 +105,9 @@ Changes to this document are made by Grafana Labs. ### Other matters -Any matter that needs a decision may be called to a vote by any member if they deem it necessary. For private or personnel matters, discussion and voting takes place on the [team mailing list][team], otherwise on the [GitHub Discussions][discussions]. +Any matter that needs a decision may be called to a vote by any member if they deem it necessary. For private or +personnel matters, discussion and voting takes place on the [team mailing list][team], otherwise +on the [GitHub Discussions][discussions]. ## Voting @@ -94,45 +115,67 @@ The OnCall project usually runs by informal consensus, however sometimes a forma Depending on the subject matter, as laid out [above](#decision-making), different methods of voting are used. -For all votes, voting must be open for at least one week. The end date should be clearly stated in the call to vote. A vote may be called and closed early if enough votes have come in one way so that further votes cannot change the final decision. +For all votes, voting must be open for at least one week. The end date should be clearly stated in the call to vote. +A vote may be called and closed early if enough votes have come in one way so that further votes cannot +change the final decision. -In all cases, all and only [team members](#team-members) are eligible to vote, with the sole exception of the forced removal of a team member, in which said member is not eligible to vote. +In all cases, all and only [team members](#team-members) are eligible to vote, with the sole exception of the forced +removal of a team member, in which said member is not eligible to vote. -Discussion and votes on personnel matters (including but not limited to team membership and maintainership) are held in private on the [team mailing list][team]. All other discussion and votes are held in public on the [GitHub Discussions][discussions]. +Discussion and votes on personnel matters (including but not limited to team membership and maintainership) are held in +private on the [team mailing list][team]. All other discussion and votes are held in public +on the [GitHub Discussions][discussions]. -For public discussions, anyone interested is encouraged to participate. Formal power to object or vote is limited to [team members](#team-members). +For public discussions, anyone interested is encouraged to participate. Formal power to object or vote is limited to +[team members](#team-members). ### Consensus -The default decision making mechanism for the OnCall project is [rough][rough] consensus. This means that any decision on technical issues is considered supported by the [team][team] as long as nobody objects or the objection has been considered but not necessarily accommodated. +The default decision making mechanism for the OnCall project is [rough][rough] consensus. This means that any decision +on technical issues is considered supported by the [team][team] as long as nobody objects or the objection has been +considered but not necessarily accommodated. -Silence on any consensus decision is implicit agreement and equivalent to explicit agreement. Explicit agreement may be stated at will. Decisions may, but do not need to be called out and put up for decision on the [GitHub Discussions][discussions] at any time and by anyone. +Silence on any consensus decision is implicit agreement and equivalent to explicit agreement. Explicit agreement may +be stated at will. Decisions may, but do not need to be called out and put up for decision on the +[GitHub Discussions][discussions] at any time and by anyone. Consensus decisions can never override or go against the spirit of an earlier explicit vote. -If any [team member](#team-members) raises objections, the team members work together towards a solution that all involved can accept. This solution is again subject to rough consensus. +If any [team member](#team-members) raises objections, the team members work together towards a solution that all +involved can accept. This solution is again subject to rough consensus. -In case no consensus can be found, but a decision one way or the other must be made, any [team member](#team-members) may call a formal [majority vote](#majority-vote). +In case no consensus can be found, but a decision one way or the other must be made, any [team member](#team-members) +may call a formal [majority vote](#majority-vote). ### Majority vote -Majority votes must be called explicitly in a separate thread on the appropriate mailing list. The subject must be prefixed with `[VOTE]`. In the body, the call to vote must state the proposal being voted on. It should reference any discussion leading up to this point. +Majority votes must be called explicitly in a separate thread on the appropriate mailing list. +The subject must be prefixed with `[VOTE]`. In the body, the call to vote must state the proposal being voted on. +It should reference any discussion leading up to this point. Votes may take the form of a single proposal, with the option to vote yes or no, or the form of multiple alternatives. A vote on a single proposal is considered successful if more vote in favor than against. -If there are multiple alternatives, members may vote for one or more alternatives, or vote “no” to object to all alternatives. It is not possible to cast an “abstain” vote. A vote on multiple alternatives is considered decided in favor of one alternative if it has received the most votes in favor, and a vote from more than half of those voting. Should no alternative reach this quorum, another vote on a reduced number of options may be called separately. +If there are multiple alternatives, members may vote for one or more alternatives, or vote “no” to object to all +alternatives. It is not possible to cast an “abstain” vote. A vote on multiple alternatives is considered decided in +favor of one alternative if it has received the most votes in favor, and a vote from more than half of those voting. +Should no alternative reach this quorum, another vote on a reduced number of options may be called separately. ### Supermajority vote -Supermajority votes must be called explicitly in a separate thread on the appropriate mailing list. The subject must be prefixed with `[VOTE]`. In the body, the call to vote must state the proposal being voted on. It should reference any discussion leading up to this point. +Supermajority votes must be called explicitly in a separate thread on the appropriate mailing list. +The subject must be prefixed with `[VOTE]`. In the body, the call to vote must state the proposal being voted on. +It should reference any discussion leading up to this point. Votes may take the form of a single proposal, with the option to vote yes or no, or the form of multiple alternatives. A vote on a single proposal is considered successful if at least two thirds of those eligible to vote vote in favor. -If there are multiple alternatives, members may vote for one or more alternatives, or vote “no” to object to all alternatives. A vote on multiple alternatives is considered decided in favor of one alternative if it has received the most votes in favor, and a vote from at least two thirds of those eligible to vote. Should no alternative reach this quorum, another vote on a reduced number of options may be called separately. +If there are multiple alternatives, members may vote for one or more alternatives, or vote “no” to object to +all alternatives. A vote on multiple alternatives is considered decided in favor of one alternative if it has received +the most votes in favor, and a vote from at least two thirds of those eligible to vote. Should no alternative reach +this quorum, another vote on a reduced number of options may be called separately. ## On- / Offboarding @@ -141,7 +184,8 @@ If there are multiple alternatives, members may vote for one or more alternative The new member is - added to the list of [team members](#team-members). Ideally by sending a PR of their own, at least approving said PR. -- announced on the [GitHub Discussions][discussions] by an existing team member. Ideally, the new member replies in this thread, acknowledging team membership. +- announced on the [GitHub Discussions][discussions] by an existing team member. Ideally, the new member + replies in this thread, acknowledging team membership. - added to the projects with commit rights. - added to the [team mailing list][team]. @@ -149,15 +193,16 @@ The new member is The ex-member is -- removed from the list of [team members](#team-members). Ideally by sending a PR of their own, at least approving said PR. In case of forced removal, no approval is needed. -- removed from the projects. Optionally, they can retain maintainership of one or more repositories if the [team](#team-members) agrees. +- removed from the list of [team members](#team-members). Ideally by sending a PR of their own, at least approving said PR. + In case of forced removal, no approval is needed. +- removed from the projects. Optionally, they can retain maintainership of one or more repositories + if the [team](#team-members) agrees. - removed from the team mailing list and demoted to a normal member of the other mailing lists. - not allowed to call themselves an active team member any more, nor allowed to imply this to be the case. - added to a list of previous members if they so choose. If needed, we reserve the right to publicly announce removal. - [announce]: https://github.com/grafana/oncall/discussions/categories/announcements [coc]: https://github.com/grafana/oncall/blob/dev/CODE_OF_CONDUCT.md [maintainers]: https://github.com/grafana/oncall/blob/dev/MAINTAINERS.md diff --git a/LICENSING.md b/LICENSING.md index 34951583..6a4ef47e 100644 --- a/LICENSING.md +++ b/LICENSING.md @@ -8,12 +8,12 @@ The default license for this project is [AGPL-3.0-only](LICENSE). The following directories and their subdirectories are licensed under Apache-2.0: -``` +```text n/a ``` The following directories and their subdirectories are licensed under their original upstream licenses: -``` +```text n/a ``` diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 8447090b..adc819b4 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,3 +1,5 @@ +# Maintainers + The following are the main/default maintainers: - Ildar Iskhakov — [@iskhakov](https://github.com/iskhakov) ([Grafana Labs](https://grafana.com/)) @@ -6,6 +8,7 @@ The following are the main/default maintainers: Some parts of the codebase have other maintainers, the package paths also include all sub-packages: Some parts of the codebase have other maintainers: + - `docs`: - Eve Meelan - [@Eve832](https://github.com/Eve832) ([Grafana Labs](https://grafana.com/)) - Alyssa Wada - [@alyssawada](https://github.com/alyssawada) ([Grafana Labs](https://grafana.com/)) diff --git a/README.md b/README.md index b0ce2702..8cfcac52 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Grafana OnCall + [![Latest Release](https://img.shields.io/github/v/release/grafana/oncall?display_name=tag&sort=semver)](https://github.com/grafana/oncall/releases) @@ -26,31 +28,34 @@ We prepared multiple environments: 1. Download [`docker-compose.yml`](docker-compose.yml): -```bash -curl -fsSL https://raw.githubusercontent.com/grafana/oncall/dev/docker-compose.yml -o docker-compose.yml -``` + ```bash + curl -fsSL https://raw.githubusercontent.com/grafana/oncall/dev/docker-compose.yml -o docker-compose.yml + ``` 2. Set variables: -```bash -echo "DOMAIN=http://localhost:8080 -COMPOSE_PROFILES=with_grafana # Remove this line if you want to use existing grafana -SECRET_KEY=my_random_secret_must_be_more_than_32_characters_long" > .env -``` + ```bash + echo "DOMAIN=http://localhost:8080 + COMPOSE_PROFILES=with_grafana # Remove this line if you want to use existing grafana + SECRET_KEY=my_random_secret_must_be_more_than_32_characters_long" > .env + ``` 3. Launch services: -```bash -docker-compose up -d -``` + ```bash + docker-compose up -d + ``` -4. Go to [OnCall Plugin Configuration](http://localhost:3000/plugins/grafana-oncall-app), using log in credentials as defined above: `admin`/`admin` (or find OnCall plugin in configuration->plugins) and connect OnCall _plugin_ with OnCall _backend_: +4. Go to [OnCall Plugin Configuration](http://localhost:3000/plugins/grafana-oncall-app), using log in credentials + as defined above: `admin`/`admin` (or find OnCall plugin in configuration->plugins) and connect OnCall _plugin_ + with OnCall _backend_: -``` -OnCall backend URL: http://engine:8080 -``` + ```text + OnCall backend URL: http://engine:8080 + ``` -5. Enjoy! Check our [OSS docs](https://grafana.com/docs/grafana-cloud/oncall/open-source/) if you want to set up Slack, Telegram, Twilio or SMS/calls through Grafana Cloud. +5. Enjoy! Check our [OSS docs](https://grafana.com/docs/grafana-cloud/oncall/open-source/) if you want to set up + Slack, Telegram, Twilio or SMS/calls through Grafana Cloud. ## Update version @@ -65,13 +70,14 @@ docker-compose up -d ``` After updating the engine, you'll also need to click the "Update" button on the [plugin version page](http://localhost:3000/plugins/grafana-oncall-app?page=version-history). -See [Grafana docs](https://grafana.com/docs/grafana/latest/administration/plugin-management/#update-a-plugin) for more info on updating Grafana plugins. +See [Grafana docs](https://grafana.com/docs/grafana/latest/administration/plugin-management/#update-a-plugin) for more +info on updating Grafana plugins. ## Join community - - - +[](https://github.com/grafana/oncall/discussions/categories/community-calls) +[](https://github.com/grafana/oncall/discussions) +[](https://slack.grafana.com/) ## Stargazers over time diff --git a/SECURITY.md b/SECURITY.md index b8697c16..349dbe51 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,9 @@ # Reporting security issues -If you think you have found a security vulnerability, please send a report to [security@grafana.com](mailto:security@grafana.com). This address can be used for all of Grafana Labs's open source and commercial products (including but not limited to Grafana, Grafana Cloud, Grafana Enterprise, and grafana.com). We can accept only vulnerability reports at this address. +If you think you have found a security vulnerability, please send a report to +[security@grafana.com](mailto:security@grafana.com). This address can be used for all of Grafana Labs's open source and +commercial products (including but not limited to Grafana, Grafana Cloud, Grafana Enterprise, and grafana.com). +We can accept only vulnerability reports at this address. Please encrypt your message to us; please use our PGP key. The key fingerprint is: @@ -8,13 +11,18 @@ F988 7BEA 027A 049F AE8E 5CAA D125 8932 BE24 C5CA The key is available from [keyserver.ubuntu.com](https://keyserver.ubuntu.com/pks/lookup?search=0xF9887BEA027A049FAE8E5CAAD1258932BE24C5CA&fingerprint=on&op=index). -Grafana Labs will send you a response indicating the next steps in handling your report. After the initial reply to your report, the security team will keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance. +Grafana Labs will send you a response indicating the next steps in handling your report. After the initial reply +to your report, the security team will keep you informed of the progress towards a fix and full announcement, +and may ask for additional information or guidance. -**Important:** We ask you to not disclose the vulnerability before it have been fixed and announced, unless you received a response from the Grafana Labs security team that you can do so. +**Important:** We ask you to not disclose the vulnerability before it have been fixed and announced, unless you +received a response from the Grafana Labs security team that you can do so. ## Security announcements -We maintain a category on the community site called [Security Announcements](https://community.grafana.com/c/support/security-announcements), -where we will post a summary, remediation, and mitigation details for any patch containing security fixes. +We maintain a category on the community site called +[Security Announcements](https://community.grafana.com/c/support/security-announcements), where we will post a summary, +remediation, and mitigation details for any patch containing security fixes. -You can also subscribe to email updates to this category if you have a grafana.com account and sign on to the community site or track updates via an [RSS feed](https://community.grafana.com/c/support/security-announcements.rss). +You can also subscribe to email updates to this category if you have a grafana.com account and sign on to the +community site or track updates via an [RSS feed](https://community.grafana.com/c/support/security-announcements.rss). diff --git a/dev/README.md b/dev/README.md index 3ca86a66..5fd5dbea 100644 --- a/dev/README.md +++ b/dev/README.md @@ -11,37 +11,49 @@ - [Troubleshooting](#troubleshooting) - [ld: library not found for -lssl](#ld-library-not-found-for--lssl) - [Could not build wheels for cryptography which use PEP 517 and cannot be installed directly](#could-not-build-wheels-for-cryptography-which-use-pep-517-and-cannot-be-installed-directly) - - [django.db.utils.OperationalError: (1366, "Incorrect string value ...")](#djangodbutilsoperationalerror-1366-incorrect-string-value) + - [django.db.utils.OperationalError: (1366, "Incorrect string value")](#djangodbutilsoperationalerror-1366-incorrect-string-value) - [/bin/sh: line 0: cd: grafana-plugin: No such file or directory](#binsh-line-0-cd-grafana-plugin-no-such-file-or-directory) - [IDE Specific Instructions](#ide-specific-instructions) - - [PyCharm](#pycharm-professional-edition) + - [PyCharm](#pycharm) Related: [How to develop integrations](/engine/config_integrations/README.md) ## Running the project -By default everything runs inside Docker. These options can be modified via the [`COMPOSE_PROFILES`](#compose_profiles) environment variable. +By default everything runs inside Docker. These options can be modified via the [`COMPOSE_PROFILES`](#compose_profiles) +environment variable. -1. Firstly, ensure that you have `docker` [installed](https://docs.docker.com/get-docker/) and running on your machine. **NOTE**: the `docker-compose-developer.yml` file uses some syntax/features that are only supported by Docker Compose v2. For instructions on how to enable this (if you haven't already done so), see [here](https://www.docker.com/blog/announcing-compose-v2-general-availability/). Ensure you have Docker Compose version 2.10 or above installed - update instructions are [here](https://docs.docker.com/compose/install/linux/). -2. Run `make init start`. By default this will run everything in Docker, using SQLite as the database and Redis as the message broker/cache. See [Running in Docker](#running-in-docker) below for more details on how to swap out/disable which components are run in Docker. +1. Firstly, ensure that you have `docker` [installed](https://docs.docker.com/get-docker/) and running on your machine. + **NOTE**: the `docker-compose-developer.yml` file uses some syntax/features that are only supported by Docker Compose + v2. For instructions on how to enable this (if you haven't already done so), + see [here](https://www.docker.com/blog/announcing-compose-v2-general-availability/). Ensure you have Docker Compose + version 2.10 or above installed - update instructions are [here](https://docs.docker.com/compose/install/linux/). +2. Run `make init start`. By default this will run everything in Docker, using SQLite as the database and Redis as the + message broker/cache. See [`COMPOSE_PROFILES`](#compose_profiles) below for more details on how to swap + out/disable which components are run in Docker. 3. Open Grafana in a browser [here](http://localhost:3000/plugins/grafana-oncall-app) (login: `oncall`, password: `oncall`). 4. You should now see the OnCall plugin configuration page. Fill out the configuration options as follows: -- OnCall backend URL: http://host.docker.internal:8080 (this is the URL that is running the OnCall API; it should be accessible from Grafana) -- Grafana URL: http://grafana:3000 (this is the URL OnCall will use to talk to the Grafana Instance) + - OnCall backend URL: (this is the URL that is running the OnCall API; it should be + accessible from Grafana) + - Grafana URL: (this is the URL OnCall will use to talk to the Grafana Instance) -5. Enjoy! Check our [OSS docs](https://grafana.com/docs/grafana-cloud/oncall/open-source/) if you want to set up Slack, Telegram, Twilio or SMS/calls through Grafana Cloud. +5. Enjoy! Check our [OSS docs](https://grafana.com/docs/grafana-cloud/oncall/open-source/) if you want to set up Slack, + Telegram, Twilio or SMS/calls through Grafana Cloud. 6. (Optional) Install `pre-commit` hooks by running `make install-precommit-hook` -**Note**: on subsequent startups you can simply run `make start`, this is a bit faster because it skips the frontend build step. +**Note**: on subsequent startups you can simply run `make start`, this is a bit faster because it skips the frontend +build step. ### `COMPOSE_PROFILES` -This configuration option represents a comma-separated list of [`docker-compose` profiles](https://docs.docker.com/compose/profiles/). It allows you to swap-out, or disable, certain components in Docker. +This configuration option represents a comma-separated list of [`docker-compose` profiles](https://docs.docker.com/compose/profiles/). +It allows you to swap-out, or disable, certain components in Docker. This option can be configured in two ways: -1. Setting a `COMPOSE_PROFILES` environment variable in `dev/.env.dev`. This allows you to avoid having to set `COMPOSE_PROFILES` for each `make` command you execute afterwards. +1. Setting a `COMPOSE_PROFILES` environment variable in `dev/.env.dev`. This allows you to avoid having to set + `COMPOSE_PROFILES` for each `make` command you execute afterwards. 2. Passing in a `COMPOSE_PROFILES` argument when running `make` commands. For example: ```bash @@ -66,20 +78,29 @@ The default is `engine,oncall_ui,redis,grafana`. This runs: ### `GRAFANA_VERSION` -If you would like to change the version of Grafana being run, simply pass in a `GRAFANA_VERSION` environment variable to `make start` (or alternatively set it in your `.env.dev` file). The value of this environment variable should be a valid `grafana/grafana` published Docker [image tag](https://hub.docker.com/r/grafana/grafana/tags). +If you would like to change the version of Grafana being run, simply pass in a `GRAFANA_VERSION` environment variable +to `make start` (or alternatively set it in your `.env.dev` file). The value of this environment variable should be a +valid `grafana/grafana` published Docker [image tag](https://hub.docker.com/r/grafana/grafana/tags). ### Running backend services outside Docker -By default everything runs inside Docker. If you would like to run the backend services outside of Docker (for integrating w/ PyCharm for example), follow these instructions: +By default everything runs inside Docker. If you would like to run the backend services outside of Docker +(for integrating w/ PyCharm for example), follow these instructions: -1. Create a Python 3.9 virtual environment using a method of your choosing (ex. [venv](https://docs.python.org/3.9/library/venv.html) or [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)). Make sure the virtualenv is "activated". -2. `postgres` is a dependency on some of our Python dependencies (notably `psycopg2` ([docs](https://www.psycopg.org/docs/install.html#prerequisites))). Please visit [here](https://www.postgresql.org/download/) for installation instructions. +1. Create a Python 3.9 virtual environment using a method of your choosing (ex. + [venv](https://docs.python.org/3.9/library/venv.html) or [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)). + Make sure the virtualenv is "activated". +2. `postgres` is a dependency on some of our Python dependencies (notably `psycopg2` + ([docs](https://www.psycopg.org/docs/install.html#prerequisites))). Please visit + [here](https://www.postgresql.org/download/) for installation instructions. 3. `make backend-bootstrap` - installs all backend dependencies 4. Modify your `.env.dev` by copying the contents of one of `.env.mysql.dev`, `.env.postgres.dev`, - or `.env.sqlite.dev` into `.env.dev` (you should exclude the `GF_` prefixed environment variables). > In most cases where you are running stateful services via `docker-compose` - and backend services outside of docker you will simply need to change the database host to `localhost` - (or in the case of `sqlite` update the file-path to your `sqlite` database file). You will need to change - the broker host to `localhost` as well. + or `.env.sqlite.dev` into `.env.dev` (you should exclude the `GF_` prefixed environment variables). + + > In most cases where you are running stateful services via `docker-compose`, and backend services outside of + > docker, you will simply need to change the database host to `localhost` (or in the case of `sqlite` update + > the file-path to your `sqlite` database file). You will need to change the broker host to `localhost` as well. + 5. `make backend-migrate` - runs necessary database migrations 6. Open two separate shells and then run the following: @@ -122,11 +143,13 @@ make lint ## Setting environment variables -If you need to override any additional environment variables, you should set these in a root `.env.dev` file. This file is automatically picked up by the OnCall engine Docker containers. This file is ignored from source control and also overrides any defaults that are set in other `.env*` files +If you need to override any additional environment variables, you should set these in a root `.env.dev` file. +This file is automatically picked up by the OnCall engine Docker containers. This file is ignored from source control +and also overrides any defaults that are set in other `.env*` files ## Slack application setup -For Slack app configuration check our docs: https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup +For Slack app configuration check our docs: ## Update drone build @@ -151,7 +174,7 @@ drone sign --save grafana/oncall .drone.yml **Problem:** -``` +```bash make backend-bootstrap ... ld: library not found for -lssl @@ -162,7 +185,7 @@ make backend-bootstrap **Solution:** -``` +```bash export LDFLAGS=-L/usr/local/opt/openssl/lib make backend-bootstrap ``` @@ -173,30 +196,38 @@ Happens on Apple Silicon **Problem:** -``` - build/temp.macosx-12-arm64-3.9/_openssl.c:575:10: fatal error: 'openssl/opensslv.h' file not found - #include - ^~~~~~~~~~~~~~~~~~~~ - 1 error generated. - error: command '/usr/bin/clang' failed with exit code 1 - ---------------------------------------- - ERROR: Failed building wheel for cryptography +```bash +build/temp.macosx-12-arm64-3.9/_openssl.c:575:10: fatal error: 'openssl/opensslv.h' file not found +#include + ^~~~~~~~~~~~~~~~~~~~ +1 error generated. +error: command '/usr/bin/clang' failed with exit code 1 +---------------------------------------- +ERROR: Failed building wheel for cryptography ``` **Solution:** -``` + + +```bash LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" CFLAGS="-I$(brew --prefix openssl@1.1)/include" pip install `cat engine/requirements.txt | grep cryptography` ``` -### django.db.utils.OperationalError: (1366, "Incorrect string value ...") + + +### django.db.utils.OperationalError: (1366, "Incorrect string value") **Problem:** -``` + + +```bash django.db.utils.OperationalError: (1366, "Incorrect string value: '\\xF0\\x9F\\x98\\x8A\\xF0\\x9F...' for column 'cached_name' at row 1") ``` + + **Solution:** Recreate the database with the correct encoding. @@ -207,18 +238,19 @@ Recreate the database with the correct encoding. When running `make init`: -``` +```bash /bin/sh: line 0: cd: grafana-plugin: No such file or directory make: *** [init] Error 1 ``` -This arises when the environment variable `[CDPATH](https://www.theunixschool.com/2012/04/what-is-cdpath.html)` is set _and_ when the current path (`.`) is not explicitly part of `CDPATH`. +This arises when the environment variable `[CDPATH](https://www.theunixschool.com/2012/04/what-is-cdpath.html)` is +set _and_ when the current path (`.`) is not explicitly part of `CDPATH`. **Solution:** Either make `.` part of `CDPATH` in your .rc file setup, or temporarily override the variable when running `make` commands: -``` +```bash $ CDPATH="." make init # Setting CDPATH to empty seems to also work - only tested on zsh, YMMV $ CDPATH="" make init @@ -228,15 +260,19 @@ $ CDPATH="" make init When running `make init start`: -``` + + +```bash Error response from daemon: open /var/lib/docker/overlay2/ac57b871108ee1b98ff4455e36d2175eae90cbc7d4c9a54608c0b45cfb7c6da5/committed: is a directory make: *** [start] Error 1 ``` + + **Solution:** clear everything in docker by resetting or: -``` +```bash make cleanup ``` @@ -247,7 +283,8 @@ make cleanup 1. Follow the instructions listed in ["Running backend services outside Docker"](#running-backend-services-outside-docker). 2. Open the project in PyCharm 3. Settings → Project OnCall - - In Python Interpreter click the gear and create a new Virtualenv from existing environment selecting the venv created in Step 1. + - In Python Interpreter click the gear and create a new Virtualenv from existing environment selecting the + venv created in Step 1. - In Project Structure make sure the project root is the content root and add /engine to Sources 4. Under Settings → Languages & Frameworks → Django - Enable Django support diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json new file mode 100644 index 00000000..15faa1ca --- /dev/null +++ b/docs/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "extends": "../.markdownlint.json", + "MD025": false, + "MD036": false +} diff --git a/docs/README.md b/docs/README.md index 2a78a922..98e94162 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,10 @@ # Grafana Cloud Documentation -Source for documentation at https://grafana.com/docs/oncall/ +Source for documentation at ## Preview the website -Run `make docs`. This launches a preview of the website with the current grafana docs at `http://localhost:3002/docs/oncall/latest/` which will refresh automatically when changes are made to content in the `sources` directory. +Run `make docs`. This launches a preview of the website with the current grafana docs at +`http://localhost:3002/docs/oncall/latest/` which will refresh automatically when changes are made to +content in the `sources` directory. Make sure Docker is running. diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 7b70bfde..bb0c2a60 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -18,15 +18,22 @@ weight: 1000 +Grafana OnCall is an open source incident response management tool built to help teams improve their collaboration and +resolve incidents faster. Some of the core strengths of Grafana OnCall include: -Grafana OnCall is an open source incident response management tool built to help teams improve their collaboration and resolve incidents faster. Some of the core strengths of Grafana OnCall include: - -- **Support for a broad set of monitoring systems:** Grafana OnCall supports integrations with many monitoring systems, including Grafana, Prometheus, Alertmanager, Zabbix, and more. -- **Reduce alert noise:** Automatic alert grouping helps avoid alert storms and reduce noise during incidents. Auto-resolve settings can resolve without human intervention when the resolve conditions are met, enabling you to control alert noise and reduce alert fatigue. -- **Automatic escalation to on-call rotations:** Grafana OnCall’s flexible calendar integration allows you to define your on-call rotations while managing on-call schedules in your preferred calendar application with iCal format. Configurable alert escalation automatically escalates alerts to on-call team members, notifies slack channels, and more. -- **ChatOps focused:** Grafana OnCall integrates closely with your slack workspace to deliver alert notifications to individuals and groups, making daily alerts more visible and easier to manage. -- **Highly customizable**: With customizable alert grouping and routing, you can decide which alerts you want to be notified of and how, ensuring the right people are notified for the right issues. -- **Massive scalability:** Grafana OnCall is equipped with a full API and Terraform capabilities. Ready for GitOps and large organization configuration. - +- **Support for a broad set of monitoring systems:** Grafana OnCall supports integrations with many monitoring systems, + including Grafana, Prometheus, Alertmanager, Zabbix, and more. +- **Reduce alert noise:** Automatic alert grouping helps avoid alert storms and reduce noise during incidents. + Auto-resolve settings can resolve without human intervention when the resolve conditions are met, enabling you to + control alert noise and reduce alert fatigue. +- **Automatic escalation to on-call rotations:** Grafana OnCall’s flexible calendar integration allows you to define + your on-call rotations while managing on-call schedules in your preferred calendar application with iCal format. + Configurable alert escalation automatically escalates alerts to on-call team members, notifies slack channels, and more. +- **ChatOps focused:** Grafana OnCall integrates closely with your slack workspace to deliver alert notifications to + individuals and groups, making daily alerts more visible and easier to manage. +- **Highly customizable**: With customizable alert grouping and routing, you can decide which alerts you want to be + notified of and how, ensuring the right people are notified for the right issues. +- **Massive scalability:** Grafana OnCall is equipped with a full API and Terraform capabilities. Ready for GitOps + and large organization configuration. {{< section >}} diff --git a/docs/sources/alert-behavior/_index.md b/docs/sources/alert-behavior/_index.md index d1204cbf..2a2ffa82 100644 --- a/docs/sources/alert-behavior/_index.md +++ b/docs/sources/alert-behavior/_index.md @@ -8,16 +8,17 @@ 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. +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 +## 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. +- 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 >}} \ No newline at end of file +{{< section >}} diff --git a/docs/sources/alert-behavior/alert-templates/index.md b/docs/sources/alert-behavior/alert-templates/index.md index 5bc4321c..0269dfc8 100644 --- a/docs/sources/alert-behavior/alert-templates/index.md +++ b/docs/sources/alert-behavior/alert-templates/index.md @@ -15,7 +15,10 @@ weight: 300 # Configure alert templates -Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default pre configured alert template is applied to modify the alert payload to be more human readable. These alert templates are customizable for any integration. +Grafana OnCall can integrate with any monitoring systems that can send alerts using webhooks with JSON payloads. By +default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default +pre configured alert template is applied to modify the alert payload to be more human readable. These alert templates +are customizable for any integration. See Format alerts with alert templates in this document to learn more about how to customize alert templates. @@ -23,13 +26,15 @@ See Format alerts with alert templates in this document to learn more about how 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. +- Default or customized alert templates are applied to deliver the most useful alert fields with the most valuable information, + in a readable format. - Alerts are grouped based on your alert grouping configurations, combining similar or related alerts to reduce alert noise. - Alerts automatically resolve if an alert from the monitoring system matches the resolve condition for that alert. ## Alert payload -Alerts received by Grafana OnCall contain metadata as keys and values in a JSON object. The following is an example of an alert from Grafana OnCall: +Alerts 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: ```json { @@ -68,16 +73,21 @@ The JSON payload is converted. For example: - `{{ payload.message }}` -> Message - `{{ payload.imageUrl }}` -> Image Url -The result is that each field of the alert in OnCall is now mapped to the JSON payload keys. This also true for the alert behavior: +The result is that each field of the alert in OnCall is now mapped to the JSON payload keys. This also true for the +alert behavior: - `{{ payload.ruleId }}` -> Grouping Id - `{{ 1 if payload.state == 'OK' else 0 }}` -> Resolve Signal -Grafana OnCall provides a pre configured default Jinja template for supported integrations. If your monitoring system is not in the Grafana OnCall integrations list, you can create a generic `webhook` integration, send an alert, and configure your templates. +Grafana OnCall provides a pre configured default Jinja template for supported integrations. If your monitoring system is +not in the Grafana OnCall integrations list, you can create a generic `webhook` integration, send an alert, and configure +your templates. ## Customize alerts with alert templates -Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert templates for all the different ways you receive your alerts such as web, slack, SMS, and email. For more advanced customization, use Jinja templates. +Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert +templates for all the different ways you receive your alerts such as web, slack, SMS, and email. For more advanced +customization, use Jinja templates. As a best practice, add _Playbooks_, _Useful links_, or _Checklists_ to the alert message. @@ -97,23 +107,28 @@ To customize alert templates in Grafana OnCall: 4. Edit the alert behavior as needed: - `Grouping Id` - This output groups other alerts into a single alert group. - - `Acknowledge Condition` - The output should be `ok`, `true`, or `1` to auto-acknowledge the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. - - `Resolve Condition` - The output should be `ok`, `true` or `1` to auto-resolve the alert group. For example, `{{ 1 if payload.state == 'OK' else 0 }}`. + - `Acknowledge Condition` - The output should be `ok`, `true`, or `1` to auto-acknowledge the alert group. + For example, `{{ 1 if payload.state == 'OK' else 0 }}`. + - `Resolve Condition` - The output should be `ok`, `true` or `1` to auto-resolve the alert group. + For example, `{{ 1 if payload.state == 'OK' else 0 }}`. - `Source Link` - Used to customize the URL link to provide as the "source" of the alert. ## Advanced Jinja templates -Grafana OnCall uses [Jinja templating language](http://jinja.pocoo.org/docs/2.10/) to format alert groups for the Web, Slack, phone calls, SMS messages, and more because the JSON format is not easily readable by humans. As a result, you can decide what you want to see when an alert group is triggered as well as how it should be presented. +Grafana OnCall uses [Jinja templating language](http://jinja.pocoo.org/docs/2.10/) to format alert groups for the Web, +Slack, phone calls, SMS messages, and more because the JSON format is not easily readable by humans. As a result, you +can decide what you want to see when an alert group is triggered as well as how it should be presented. Jinja2 offers simple but multi-faceted functionality by using loops, conditions, functions, and more. > **NOTE:** Every alert from a monitoring system comes in the key/value format. - Grafana OnCall has rules about which of the keys match to: `__title`, `message`, `image`, `grouping`, and `auto-resolve__`. +Grafana OnCall has rules about which of the keys match to: `__title`, `message`, `image`, `grouping`, and `auto-resolve__`. ### Loops -Monitoring systems can send an array of values. In this example, you can use Jinja to iterate and format the alert using a Grafana example: +Monitoring systems can send an array of values. In this example, you can use Jinja to iterate and format the alert +using a Grafana example: ```.jinja2 *Values:* diff --git a/docs/sources/alert-behavior/outgoing-webhooks/index.md b/docs/sources/alert-behavior/outgoing-webhooks/index.md index a88ccbf9..7931f6ea 100644 --- a/docs/sources/alert-behavior/outgoing-webhooks/index.md +++ b/docs/sources/alert-behavior/outgoing-webhooks/index.md @@ -16,26 +16,25 @@ weight: 500 # Configure outgoing webhooks for Grafana OnCall -Outgoing webhooks allow you to send alert details to a specified URL from Grafana OnCall. Once an outgoing webhook is configured, you can use it as a notification method in escalation chains. +Outgoing webhooks allow you to send alert details to a specified URL from Grafana OnCall. Once an outgoing webhook is +configured, you can use it as a notification method in escalation chains. To automatically send alert data to a destination URL via outgoing webhook: 1. In Grafana OnCall, navigate to **Outgoing Webhooks** and click **+ Create**. This is also the place to edit and delete existing outgoing webhooks. - 2. Provide a name for your outgoing webhook and enter the destination URL. - 3. If the destination requires authentication, enter your credentials. You can enter a username and password (HTTP) or an authorization header formatted in JSON. - 4. Configure the webhook payload in the **Data** field. 5. Click **Create Webhook**. -The format you use to call the variables must match the structure of how the fields are nested in the alert payload. The **Data** field can use the following four variables to auto-populate the webhook payload with information about the first alert in the alert group: +The format you use to call the variables must match the structure of how the fields are nested in the alert payload. +The **Data** field can use the following four variables to auto-populate the webhook payload with information about +the first alert in the alert group: - `{{ alert_payload }}` - `{{ alert_group_id }}` -
`alert_payload` is always the first level of any variable you want to call. @@ -48,4 +47,5 @@ The following is an example of an entry in the **Data** field that might return } ``` -> **NOTE:** If you receive an error message and cannot create an outgoing webhook, verify that your JSON is formatted correctly. +> **NOTE:** If you receive an error message and cannot create an outgoing webhook, verify that your JSON is +> formatted correctly. diff --git a/docs/sources/calendar-schedules/_index.md b/docs/sources/calendar-schedules/_index.md index c4838c5d..991e409d 100644 --- a/docs/sources/calendar-schedules/_index.md +++ b/docs/sources/calendar-schedules/_index.md @@ -14,49 +14,55 @@ weight: 1100 # Configure and manage on-call schedules -Grafana OnCall allows you to use any calendar service that uses the iCal format to create customized on-call schedules for team members. Using Grafana OnCall, you can create a primary calendar that acts as a read-only schedule, and an override calendar that allows all team members to modify schedules as they change. +Grafana OnCall allows you to use any calendar service that uses the iCal format to create customized on-call schedules +for team members. Using Grafana OnCall, you can create a primary calendar that acts as a read-only schedule, and an +override calendar that allows all team members to modify schedules as they change. To learn more about creating on-call calendars, see the following topics: -# Configure and manage on-call schedules +## Configure and manage on-call schedules -You can use any calendar with an iCal address to schedule on-call times for users. During these times, notifications configured in escalation chains with the **Notify users from an on-call schedule** setting will be sent to the the person scheduled. You can also schedule multiple users for overlapping times, and assign prioritization labels for the user that you would like to notify. +You can use any calendar with an iCal address to schedule on-call times for users. During these times, notifications +configured in escalation chains with the **Notify users from an on-call schedule** setting will be sent to the the person +scheduled. You can also schedule multiple users for overlapping times, and assign prioritization labels for the user +that you would like to notify. -When you create a schedule, you will be able to select a Slack channel, associated with your OnCall account, that will notify users when there are errors or notifications regarding the assigned on-call shifts. +When you create a schedule, you will be able to select a Slack channel, associated with your OnCall account, that will +notify users when there are errors or notifications regarding the assigned on-call shifts. ## Create an on-call schedule calendar Create a primary calendar and an optional override calendar to schedule on-call shifts for team members. 1. In the **Scheduling** section of Grafana OnCall, click **+ Create schedule**. - 1. Give the schedule a name. - -1. Create a new calendar in your calendar service and locate the secret iCal URL. For example, in a Google calendar, this URL can be found in **Settings > Settings for my calendars > Integrate calendar**. - +1. Create a new calendar in your calendar service and locate the secret iCal URL. For example, in a Google calendar, + this URL can be found in **Settings > Settings for my calendars > Integrate calendar**. 1. Copy the secret iCal URL. In OnCall, paste it into the **Primary schedule for iCal URL** field. The permissions you set when you create the calendar determine who can modify the calendar. - 1. Click **Create Schedule**. - 1. Schedule on-call times for team members. - Use the Grafana username of team members as the event name to schedule their on-call times. You can take advantage of all of the features of your calendar service. + Use the Grafana username of team members as the event name to schedule their on-call times. You can take advantage + of all of the features of your calendar service. 1. Create overlapping schedules (optional). - When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during the overlapping time. You can prioritize up to and including a level 9 prioritization, or `[L9]`. + When you create schedules that overlap, you can prioritize a schedule by adding a level marker. For example, if users + AliceGrafana and BobGrafana have overlapping schedules, but BobGrafana is the primary contact, you would name his + event `[L1] BobGrafana`, AliceGrafana maintains the default `[L0]` status, and would not receive notifications during + the overlapping time. You can prioritize up to and including a level 9 prioritization, or `[L9]`. # Create an override calendar (optional) -You can use an override calendar to allow team members to schedule on-call duties that will override the primary schedule. An override option allows flexibility without modifying the primary schedule. Events scheduled on the override calendar will always override overlapping events on the primary calendar. +You can use an override calendar to allow team members to schedule on-call duties that will override the primary schedule. +An override option allows flexibility without modifying the primary schedule. Events scheduled on the override calendar +will always override overlapping events on the primary calendar. 1. Create a new calendar using the same calendar service you used to create the primary calendar. Be sure to set permissions that allow team members to edit the calendar. 1. In the scheduling section of Grafana OnCall, select the primary calendar you want to override. - 1. Click **Edit**. - 1. Enter the secret iCal URL in the **Overrides schedule iCal URL** field and click **Update**. diff --git a/docs/sources/configure-user-settings/_index.md b/docs/sources/configure-user-settings/_index.md index b37568f5..fcb79388 100644 --- a/docs/sources/configure-user-settings/_index.md +++ b/docs/sources/configure-user-settings/_index.md @@ -16,15 +16,20 @@ weight: 1300 # Manage users and teams for Grafana OnCall -Grafana OnCall is configured based on the teams you've created on the organization level of your Grafana instance, in **Configuration > Teams**. Administrators can create a different configuration for each team, and can navigate between team configurations in the **Select Team** dropdown menu in the **Incidents** section of Grafana OnCall. +Grafana OnCall is configured based on the teams you've created on the organization level of your Grafana instance, +in **Configuration > Teams**. Administrators can create a different configuration for each team, and can navigate +between team configurations in the **Select Team** dropdown menu in the **Incidents** section of Grafana OnCall. Users can edit their contact information, but user permissions are assigned at the Cloud portal level. ## Configure user notification policies -Administrators can configure how each user will receive notifications when they are are scheduled to receive them in escalation chains. Users can verify phone numbers and email addresses. Only users with the **Admin** or **Editor** role are allowed to get notifications. +Administrators can configure how each user will receive notifications when they are are scheduled to receive them in +escalation chains. Users can verify phone numbers and email addresses. Only users with the **Admin** or **Editor** role +are allowed to get notifications. -> **NOTE**: You cannot add users or manage permissions in Grafana OnCall. Most user settings are found on the organizational level of your Grafana instance in **Configuration > Users**. +> **NOTE**: You cannot add users or manage permissions in Grafana OnCall. Most user settings are found on the +> organizational level of your Grafana instance in **Configuration > Users**. 1. Find users. @@ -32,17 +37,21 @@ Administrators can configure how each user will receive notifications when they 1. Configure user settings. - Add and verify a phone number, a Slack username, and a Telegram account if you want to receive notifications using these mediums. + Add and verify a phone number, a Slack username, and a Telegram account if you want to receive notifications + using these mediums. - > **NOTE:** To edit a user's profile username, email, or role, you must do so in the **Users** tab in the **Configuration** menu of your Grafana instance. + > **NOTE:** To edit a user's profile username, email, or role, you must do so in the **Users** tab in + > the **Configuration** menu of your Grafana instance. 1. Configure notification settings. - Specify the notification medium and frequency for each user. Notification steps will be followed in the order they are listed. + Specify the notification medium and frequency for each user. Notification steps will be followed in the order + they are listed. The settings you specify in **Default Notifications** dictate how a user is notified for most escalation thresholds. - **Important Notifications** are labeled in escalation chains. If an escalation event is marked as an important notification, it will bypass **Default Notification** settings and notify the user by the method specified. + **Important Notifications** are labeled in escalation chains. If an escalation event is marked as an important notification, + it will bypass **Default Notification** settings and notify the user by the method specified. ## Configure Telegram user settings in OnCall @@ -50,7 +59,8 @@ Administrators can configure how each user will receive notifications when they 1. Click **Connect automatically** for the bot to message you and to bring up your telegram account. 1. Click **Start** when the OnCall bot messages you. -If you want to connect manually, you can click the URL provided and then **SEND MESSAGE**. In your Telegram account, click **Start**. +If you want 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 diff --git a/docs/sources/escalation-policies/_index.md b/docs/sources/escalation-policies/_index.md index ceb70476..02dc9d96 100644 --- a/docs/sources/escalation-policies/_index.md +++ b/docs/sources/escalation-policies/_index.md @@ -10,7 +10,8 @@ weight: 700 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. +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: diff --git a/docs/sources/escalation-policies/configure-escalation-chains/index.md b/docs/sources/escalation-policies/configure-escalation-chains/index.md index 9c19414b..a5cb85bf 100644 --- a/docs/sources/escalation-policies/configure-escalation-chains/index.md +++ b/docs/sources/escalation-policies/configure-escalation-chains/index.md @@ -16,7 +16,9 @@ weight: 100 # Configure and manage Escalation Chains -Escalation policies dictate how users and groups are notified when an alert notification is created. They can be very simple, or very complex. You can define as many escalation configurations for an integration as you need, and you can send notifications for certain alerts to a designated place when certain conditions are met, or not met. +Escalation policies dictate how users and groups are notified when an alert notification is created. They can be very +simple, or very complex. You can define as many escalation configurations for an integration as you need, and you can +send notifications for certain alerts to a designated place when certain conditions are met, or not met. Escalation policies have three main parts: @@ -26,8 +28,12 @@ Escalation policies have three main parts: ## 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. +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. +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/escalation-policies/configure-routes/index.md b/docs/sources/escalation-policies/configure-routes/index.md index 5de0a1a4..71946e07 100644 --- a/docs/sources/escalation-policies/configure-routes/index.md +++ b/docs/sources/escalation-policies/configure-routes/index.md @@ -20,35 +20,49 @@ Set up escalation chains and routes to configure escalation behavior for alert g ## Configure escalation chains -You can create and edit escalation chains in two places: within **Integrations**, by clicking on an integration tile, and in **Escalation Chains**. The following steps are for the **Integrations** workflow, but are generally applicable in both situations. +You can create and edit escalation chains in two places: within **Integrations**, by clicking on an integration tile, +and in **Escalation Chains**. The following steps are for the **Integrations** workflow, but are generally applicable +in both situations. -You can use **escalation chains** and **routes** to determine ordered escalation procedures. Escalation chains allow you to set up a series of alert group notification actions that trigger if certain conditions that you specify are met or not met. +You can use **escalation chains** and **routes** to determine ordered escalation procedures. Escalation chains allow +you to set up a series of alert group notification actions that trigger if certain conditions that you specify are +met or not met. 1. Click on the integration tile for which you want to define escalation policies. The **Escalations** section for the notification is in the pane to the right of the list of notifications. - You can click **Change alert template and grouping** to customize the look of the alert. You can also do this by clicking the **Settings** (gear) icon in the integration tile. + You can click **Change alert template and grouping** to customize the look of the alert. You can also do this by + clicking the **Settings** (gear) icon in the integration tile. 1. Create an escalation chain. - In the escalation pane, click **Escalate to** to choose from previously added escalation chains, or create a new one by clicking **Make a copy** or **Create a new chain**. This will be the name of the escalation policy you define. + In the escalation pane, click **Escalate to** to choose from previously added escalation chains, or create a new one + by clicking **Make a copy** or **Create a new chain**. This will be the name of the escalation policy you define. 1. Add escalation steps. - Click **Add escalation step** to choose from a set of actions and specify their triggering conditions. By default, the first step is to notify a slack channel or user. Specify users or channels or toggle the switch to turn this step off. + Click **Add escalation step** to choose from a set of actions and specify their triggering conditions. By default, the + first step is to notify a slack channel or user. Specify users or channels or toggle the switch to turn this step off. - To mark an escalation as **Important**, select the option from the step **Start** dropdown menu. User notification policies can be separately defined for **Important** and **Default** escalations. + To mark an escalation as **Important**, select the option from the step **Start** dropdown menu. User notification + policies can be separately defined for **Important** and **Default** escalations. ## Create a route To add a route, click **Add Route**. -You can set up a single route and specify notification escalation steps, or you can add multiple routes, each with its own configuration. +You can set up a single route and specify notification escalation steps, or you can add multiple routes, each with +its own configuration. -Each route added to an escalation policy follows an `IF`, `ELSE IF`, or `ELSE` path and depends on the type of alert you specify using a regular expression that matches content in the payload body of the alert. You can also specify where to send the notification for each route. +Each route added to an escalation policy follows an `IF`, `ELSE IF`, or `ELSE` path and depends on the type of alert you +specify using a regular expression that matches content in the payload body of the alert. You can also specify where +to send the notification for each route. -For example, you can send notifications for alerts with `\"severity\": \"critical\"` in the payload to an escalation chain called `Bob_OnCall`. You can create a different route for alerts with the payload `\"namespace\" *: *\"synthetic-monitoring-dev-.*\"` and select a escalation chain called `NotifySecurity`. +For example, you can send notifications for alerts with `\"severity\": \"critical\"` in the payload to an escalation +chain called `Bob_OnCall`. You can create a different route for alerts with the payload +`\"namespace\" *: *\"synthetic-monitoring-dev-.*\"` and select a escalation chain called `NotifySecurity`. You can set up escalation steps for each route in a chain. -> **NOTE:** When you modify an escalation chain or a route, it will modify that escalation chain across all integrations that use it. +> **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/get-started/_index.md b/docs/sources/get-started/_index.md index b7dc6e3e..0a4b8033 100644 --- a/docs/sources/get-started/_index.md +++ b/docs/sources/get-started/_index.md @@ -13,74 +13,92 @@ weight: 300 # Get started with Grafana OnCall -Grafana OnCall is an incident response tool built to help DevOps and SRE teams improve their collaboration and resolve incidents faster. +Grafana OnCall is an incident response tool built to help DevOps and SRE teams improve their collaboration and resolve +incidents faster. -With a centralized view of all your alerts, automated alert escalation and grouping, and on-call scheduling, Grafana OnCall helps ensure that alert notifications reach the right people, at the right time using the right notification method. +With a centralized view of all your alerts, automated alert escalation and grouping, and on-call scheduling, Grafana +OnCall helps ensure that alert notifications reach the right people, at the right time using the right notification method. 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. - +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. ## Before you begin -Grafana OnCall is available for Grafana Cloud as well as Grafana open source users. You must have a Grafana Cloud account or use [Open Source Grafana OnCall]({{< relref "../open-source" >}}) +Grafana OnCall is available for Grafana Cloud as well as Grafana open source users. You must have a Grafana Cloud account +or use [Open Source Grafana OnCall]({{< relref "../open-source" >}}) ## Install Open Source Grafana OnCall -For Open Source Grafana OnCall installation guidance, refer to [Open Source Grafana OnCall]({{< relref "../open-source" >}}) - ->**Note:** If you are using Grafana OnCall with your Grafana Cloud instance there are no install steps. Access Grafana OnCall from your Grafana Cloud account and skip ahead to “Get alerts into Grafana OnCall” +For Open Source Grafana OnCall installation guidance, refer to +[Open Source Grafana OnCall]({{< relref "../open-source" >}}) +> **Note:** If you are using Grafana OnCall with your Grafana Cloud instance there are no install steps. Access Grafana +> OnCall from your Grafana Cloud account and skip ahead to “Get alerts into Grafana OnCall” ## Get alerts into Grafana OnCall -Once you’ve installed Grafana OnCall or accessed it from your Grafana Cloud instance, you can begin integrating with monitoring systems, configuring escalation chains, and get alerts into Grafana OnCall. +Once you’ve installed Grafana OnCall or accessed it from your Grafana Cloud instance, you can begin integrating with +monitoring systems, configuring escalation chains, and get alerts into Grafana OnCall. ### Integrate with a monitoring system -Regardless of where your alerts originate, you can send them to Grafana OnCall via available integrations or customizable webhooks. To start receiving alerts in Grafana OnCall, use the following steps to configure your first integration and send a demo alert. +Regardless of where your alerts originate, you can send them to Grafana OnCall via available integrations or customizable +webhooks. To start receiving alerts in Grafana OnCall, use the following steps to configure your first integration and +send a demo alert. + +#### Configure your first integration -#### Configure your first integration: 1. In Grafana OnCall, navigate to the **Integrations** tab and click **+ New integration for receiving alerts**. 2. Select an integration from the provided options, if the integration you’re looking for isn’t listed, then select Webhook. 3. Follow the configuration steps on the integration settings page. 4. Complete any necessary configurations in your monitoring system to send alerts to Grafana OnCall. - #### Send a demo alert 1. In the integration tab, click **Send demo alert** then navigate to the **Alert Groups** tab to see your test alert firing. 2. Explore the alert by clicking on the title of the alert. 3. Acknowledge and resolve the test alert. -For more information on Grafana OnCall integrations and further configuration guidance, refer to, [Grafana OnCall integrations]({{< relref "../integrations" >}}) - +For more information on Grafana OnCall integrations and further configuration guidance, refer to +[Grafana OnCall integrations]({{< relref "../integrations" >}}) ### Configure Escalation Chains -Escalation Chains are customizable automated alert routing steps that enable you to specify who is notified for a certain alert. In addition to escalation chains, you can configure Routes to send alerts to different escalation chains depending on the alert details. +Escalation Chains are customizable automated alert routing steps that enable you to specify who is notified for a certain +alert. In addition to escalation chains, you can configure Routes to send alerts to different escalation chains depending +on the alert details. -Once your integration is configured, you can set up an escalation chain to determine how alerts from your integration are handled. Multi-step escalation chains help ensure thorough alert escalation to prevent alerts from being missed. +Once your integration is configured, you can set up an escalation chain to determine how alerts from your integration +are handled. Multi-step escalation chains help ensure thorough alert escalation to prevent alerts from being missed. To configure Escalation Chains: + 1. Navigate to the **Escalation Chains** tab and click **+ New Escalation Chain** 2. Give your Escalation Chain a useful name and click **Create** 3. Add a series of escalation steps from the available dropdown options. -4. To link your Escalation Chain to your integration, navigate back to the **Integrations tab**, Select your newly created Escalation Chain from the “**Escalate to**” dropdown. +4. To link your Escalation Chain to your integration, navigate back to the **Integrations tab**, Select your newly + created Escalation Chain from the “**Escalate to**” dropdown. 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" >}}) +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" >}}) ## Get notified of an alert -In order for Grafana OnCall to notify you of an alert, you must configure how you want to be notified. Personal notification policies, chatops integrations, and on-call schedules allow you to automate how users are notified of alerts. +In order for Grafana OnCall to notify you of an alert, you must configure how you want to be notified. Personal notification +policies, chatops integrations, and on-call schedules allow you to automate how users are notified of alerts. ### Configure personal notification policies -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" >}}) + +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" >}}) To configure users personal notification policies: @@ -88,10 +106,11 @@ To configure users personal notification policies: 2. Select a user from the user list and click **Edit** 3. Configure **Default Notifications** and **Important Notification** - ### Configure Slack for Grafana OnCall -Grafana OnCall integrates closely with your Slack workspace to deliver alert notifications to individuals, user groups, and channels. Slack notifications can be triggered by steps in an escalation chain or as a step in users personal notification policies. +Grafana OnCall integrates closely with your Slack workspace to deliver alert notifications to individuals, user groups, +and channels. Slack notifications can be triggered by steps in an escalation chain or as a step in users personal +notification policies. To configure Slack for Grafana OnCall: @@ -102,12 +121,13 @@ To configure Slack for Grafana OnCall: 5. Click Allow to allow Grafana OnCall to access Slack. 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/" >}}) - +For further instruction on connecting to your Slack workspace, refer to +[Slack integration for Grafana OnCall]({{< relref "../integrations/chatops-integrations/configure-slack/" >}}) ### Add your on-call schedule -Grafana OnCall allows you to manage your on-call schedule in your preferred calendar app such as Google Calendar or Microsoft Outlook. +Grafana OnCall allows you to manage your on-call schedule in your preferred calendar app such as Google Calendar or +Microsoft Outlook. To integrate your on-call calendar with Grafana OnCall: @@ -116,6 +136,5 @@ To integrate your on-call calendar with Grafana OnCall: 3. Copy the iCal URL associated with your on-call calendar from your calendar integration settings. 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" >}}) - - +For more information on on-call schedules, refer to +[Configure and manage on-call schedules]({{< relref "../calendar-schedules" >}}) diff --git a/docs/sources/integrations/_index.md b/docs/sources/integrations/_index.md index a49e7496..8d6247ac 100644 --- a/docs/sources/integrations/_index.md +++ b/docs/sources/integrations/_index.md @@ -16,13 +16,18 @@ weight: 500 # Grafana OnCall 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. +Integrations allow you to connect monitoring systems of your choice to send alerts to Grafana OnCall. Regardless of where +your alerts originate, you can configure alerts to be sent to Grafana OnCall for alert escalation and notification. +Grafana OnCall receives alerts in JSON format via a POST request, OnCall then parses alert data using preconfigured +alert templates to determine alert grouping, apply routes, and determine correct escalation. -There are many integrations that are directly supported by Grafana OnCall. Those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. +There are many integrations that are directly supported by Grafana OnCall. Those that aren’t currently listed in the +Integrations menu can be connected using the webhook integration and configured alert templates. ## Configure and manage integrations -You can configure and manage your integrations from the **Integrations** tab in Grafana OnCall. The following sections describe how to configure and customize your integrations to ensure alerts are treated appropriately. +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 @@ -35,7 +40,8 @@ To configure an integration for Grafana OnCall: ### Manage Grafana OnCall integrations -To manage existing integrations, navigate to the **Integrations** tab in Grafana OnCall and select the integration you want to manage. +To manage existing integrations, navigate to the **Integrations** tab in Grafana OnCall and select the integration +you want to manage. #### Customize alert templates and grouping @@ -50,9 +56,11 @@ To customize alert grouping for an integration: 1. Click **Change alert template and grouping**. 2. Select **Alert Behavior** from the dropdown menu next to **Edit template for**. -3. Edit the **grouping id**, **acknowledge condition**, and **resolve condition** templates as needed to customize your alert behavior. +3. Edit the **grouping id**, **acknowledge condition**, and **resolve condition** templates as needed to customize + your alert behavior. -For more information on alert templates, see [Configure alerts templates]({{< relref "../alert-behavior/alert-templates" >}}) +For more information on alert templates, see +[Configure alerts templates]({{< relref "../alert-behavior/alert-templates" >}}) #### Add Routes @@ -62,7 +70,8 @@ To add a route to an integration using regular expression: 2. Click **+ Add Route**. 3. Use python style regex to match on your alert content. 4. Click **Create Route**. -5. Select an escalation chain for “**IF** alert payload matches regex” and “**ELSE**” to specify where to route each type of alert. +5. Select an escalation chain for “**IF** alert payload matches regex” and “**ELSE**” to specify where to route each + type of alert. #### Edit integration name diff --git a/docs/sources/integrations/available-integrations/_index.md b/docs/sources/integrations/available-integrations/_index.md index 3d02ba76..4babb8e2 100644 --- a/docs/sources/integrations/available-integrations/_index.md +++ b/docs/sources/integrations/available-integrations/_index.md @@ -15,11 +15,15 @@ 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. +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. +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. +> **Note:** Some integrations are available for Grafana Cloud instances only. See individual integration +> guides for more information. The following integrations are currently available for Grafana OnCall and have documentation: diff --git a/docs/sources/integrations/available-integrations/configure-alertmanager/index.md b/docs/sources/integrations/available-integrations/configure-alertmanager/index.md index e2569ed0..a56cc498 100644 --- a/docs/sources/integrations/available-integrations/configure-alertmanager/index.md +++ b/docs/sources/integrations/available-integrations/configure-alertmanager/index.md @@ -18,16 +18,15 @@ weight: 300 The Alertmanager integration for Grafana OnCall handles alerts sent by client applications such as the Prometheus server. -Grafana OnCall provides grouping abilities when processing alerts from Alertmanager, including initial deduplicating, grouping, and routing the alerts to Grafana OnCall. +Grafana OnCall provides grouping abilities when processing +alerts from Alertmanager, including initial deduplicating, grouping, and routing the alerts to Grafana OnCall. ## Configure Alertmanager integration for Grafana OnCall You must have an Admin role to create integrations in Grafana OnCall. 1. In the **Integrations** tab, click **+ New integration for receiving alerts**. - 2. Select **Alertmanager** from the list of available integrations. - 3. Follow the instructions in the **How to connect** window to get your unique integration URL and identify next steps. @@ -36,16 +35,16 @@ You must have an Admin role to create integrations in Grafana OnCall. Update the `receivers` section of your Alertmanager configuration to use a unique integration URL: -``` +```yaml route: - receiver: 'oncall' + receiver: "oncall" group_by: [alertname, datacenter, app] receivers: -- name: 'oncall' - webhook_configs: - - url: - send_resolved: true + - name: "oncall" + webhook_configs: + - url: + send_resolved: true ``` ## Configure grouping with Alertmanager and Grafana OnCall @@ -55,14 +54,19 @@ You can use the alert grouping mechanics of Alertmanager and Grafana OnCall to c Alertmanager offers three alert grouping options: - `group_by` provides two options, `instance` or `job`. -- `group_wait` sets the length of time to initially wait before sending a notification for a particular group of alerts. For example, `group_wait` can be set to 45s. +- `group_wait` sets the length of time to initially wait before sending a notification for a particular group of alerts. + For example, `group_wait` can be set to 45s. - Setting a high value for `group_wait` reduces alert noise and minimizes interruption, but it may introduce delays in receiving alert notifications. To set an appropriate wait time, consider whether the group of alerts will be the same as those previously sent. + Setting a high value for `group_wait` reduces alert noise and minimizes interruption, but it may introduce delays in + receiving alert notifications. To set an appropriate wait time, consider whether the group of alerts will be the same + as those previously sent. -- `group_interval` sets the length of time to wait before sending notifications about new alerts that have been added to a group of alerts that have been previously alerted on. This setting is usually set to five minutes or more. +- `group_interval` sets the length of time to wait before sending notifications about new alerts that have been added to + a group of alerts that have been previously alerted on. This setting is usually set to five minutes or more. - During high alert volume periods, Alertmanager will send alerts at each `group_interval`, which can mean a lot of distraction. Grafana OnCall grouping will help manage this in the following ways: + During high alert volume periods, Alertmanager will send alerts at each `group_interval`, which can mean a lot of + distraction. Grafana OnCall grouping will help manage this in the following ways: - Grafana OnCall groups alerts based on the first label of each alert. - - - Grafana OnCall marks an incident as resolved only when the amount of grouped alerts with state `resolved` equals the amount of alerts with state `firing`. + - Grafana OnCall marks an incident as resolved only when the amount of grouped alerts with state `resolved` equals + the amount of alerts with state `firing`. diff --git a/docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md b/docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md index c3197649..5bd8ae9c 100644 --- a/docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md +++ b/docs/sources/integrations/available-integrations/configure-grafana-alerting/index.md @@ -18,53 +18,53 @@ weight: 100 Grafana Alerting for Grafana OnCall can be set up using two methods: - Grafana Alerting: Grafana OnCall is connected to the same Grafana instance being used to manage Grafana OnCall. - -- Grafana (Other Grafana): Grafana OnCall is connected to one or more Grafana instances separate from the one being used to manage Grafana OnCall. +- Grafana (Other Grafana): Grafana OnCall is connected to one or more Grafana instances separate from the one being + used to manage Grafana OnCall. ## Configure Grafana Alerting for Grafana OnCall You must have an Admin role to create integrations in Grafana OnCall. 1. In the **Integrations** tab, click **+ New integration for receiving alerts**. - -2. Select **Grafana Alerting** by clicking the **Quick connect** button or select **Grafana (Other Grafana)** from the integrations list. - -3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL and complete any necessary configurations. +2. Select **Grafana Alerting** by clicking the **Quick connect** button or select **Grafana (Other Grafana)** from + the integrations list. +3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL + and complete any necessary configurations. ### Configure Grafana Cloud Alerting -Use the following method if you are connecting Grafana OnCall with alerts coming from the same Grafana instance from which Grafana OnCall is being managed. +Use the following method if you are connecting Grafana OnCall with alerts coming from the same Grafana instance from +which Grafana OnCall is being managed. 1. In Grafana OnCall, navigate to the **Integrations** tab and select **New Integration for receiving alerts**. +1. Click **Quick connect** in the **Grafana Alerting** tile. This will automatically create the integration in Grafana + OnCall as well as the required contact point in Alerting. -1. Click **Quick connect** in the **Grafana Alerting** tile. This will automatically create the integration in Grafana OnCall as well as the required contact point in Alerting. - - > **Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/) - -1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new escalation chain. - -1. In Grafana Cloud Alerting, navigate to **Alerting > Contact Points** and find a contact point with a name matching the integration you created in Grafana OnCall. + > **Note:** You must connect the contact point with a notification policy. For more information, see + > [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/) +1. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new + escalation chain. +1. In Grafana Cloud Alerting, navigate to **Alerting > Contact Points** and find a contact point with a name matching + the integration you created in Grafana OnCall. 1. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. ### Configure Grafana (Other Grafana) -Connect Grafana OnCall with alerts coming from a Grafana instance that is different from the instance that Grafana OnCall is being managed: +Connect Grafana OnCall with alerts coming from a Grafana instance that is different from the instance that Grafana +OnCall is being managed: 1. In Grafana OnCall, navigate to the **Integrations** tab and select **New Integration for receiving alerts**. - 2. Select the **Grafana (Other Grafana)** tile. - -3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL and complete any necessary configurations. - -4. Determine the escalation chain for the new integration by either selecting an existing one or by creating a new escalation chain. - +3. Follow the configuration steps that display in the **How to connect** window to retrieve your unique integration URL + and complete any necessary configurations. +4. Determine the escalation chain for the new integration by either selecting an existing one or by creating a + new escalation chain. 5. Go to the other Grafana instance to connect to Grafana OnCall and navigate to **Alerting > Contact Points**. - 6. Select **New Contact Point**. - 7. Choose the contact point type `webhook`, then paste the URL generated in step 3 into the URL field. - > **Note:** You must connect the contact point with a notification policy. For more information, see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/). + > **Note:** You must connect the contact point with a notification policy. For more information, + > see [Contact points in Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/unified-alerting/contact-points/). 8. Click the **Edit** (pencil) icon, then click **Test**. This will send a test alert to Grafana OnCall. diff --git a/docs/sources/integrations/available-integrations/configure-webhook/index.md b/docs/sources/integrations/available-integrations/configure-webhook/index.md index a762f006..5319cdc6 100644 --- a/docs/sources/integrations/available-integrations/configure-webhook/index.md +++ b/docs/sources/integrations/available-integrations/configure-webhook/index.md @@ -16,14 +16,16 @@ weight: 700 # Webhook integrations for Grafana OnCall -Grafana OnCall directly supports many integrations, those that aren’t currently listed in the Integrations menu can be connected using the webhook integration and configured alert templates. +Grafana OnCall directly supports many integrations, those that aren’t currently listed in the Integrations menu can be +connected using the webhook integration and configured alert templates. With the webhook integration, you can connect to any alert source that isn't listed in the **Create Integration** page. There are two available formats, **Webhook** and **Formatted Webhook**. - **Webhook** will pull all of the raw JSON payload and display it in the manner that it's received. -- **Formatted Webhook** can be used if the alert payload sent by your monitoring service is formatted in a way that OnCall recognizes. +- **Formatted Webhook** can be used if the alert payload sent by your monitoring service is formatted in a way that + OnCall recognizes. The following fields are recognized, but none are required: @@ -39,7 +41,8 @@ To configure a webhook integration: 1. In the **Integrations** tab, click **+ New integration for receiving alerts**. 2. Select either **Webhook** or **Formatted Webhook** integration. 3. Follow the configuration steps in the **How to connect** section of the integration settings. -4. Use the unique webhook URL to complete any configuration in your monitoring service to send POST requests. Use any http client, e.g. curl to send POST requests with any payload. +4. Use the unique webhook URL to complete any configuration in your monitoring service to send POST requests. Use any + http client, e.g. curl to send POST requests with any payload. For example: @@ -57,4 +60,5 @@ For example: }' ``` -To learn how to use custom alert templates for formatted webhooks, see [Configure alerts templates]({{< relref "../../../alert-behavior/alert-templates/" >}}). +To learn how to use custom alert templates for formatted webhooks, see +[Configure alerts templates]({{< relref "../../../alert-behavior/alert-templates/" >}}). diff --git a/docs/sources/integrations/available-integrations/configure-zabbix/index.md b/docs/sources/integrations/available-integrations/configure-zabbix/index.md index 7fc0bb8e..86d4f8a7 100644 --- a/docs/sources/integrations/available-integrations/configure-zabbix/index.md +++ b/docs/sources/integrations/available-integrations/configure-zabbix/index.md @@ -15,7 +15,9 @@ weight: 500 # Zabbix integration for Grafana OnCall -Zabbix is an open-source monitoring software tool for diverse IT components, including networks, servers, virtual machines, and cloud services. Zabbix provides monitoring for metrics such as network utilization, CPU load, and disk space consumption. +Zabbix is an open-source monitoring software tool for diverse IT components, including networks, servers, virtual +machines, and cloud services. Zabbix provides monitoring for metrics such as network utilization, CPU load, and disk +space consumption. ## Configure Zabbix integration for Grafana OnCall @@ -44,13 +46,15 @@ This integration is available for Grafana Cloud OnCall. You must have an Admin r docker exec -it zabbix-appliance bash ``` -1. Place the [grafana_oncall.sh](#grafana_oncallsh-script) script in the `AlertScriptsPath` directory specified within the Zabbix server configuration file (zabbix_server.conf). +1. Place the [grafana_oncall.sh](#grafana_oncallsh-script) script in the `AlertScriptsPath` directory specified within + the Zabbix server configuration file (zabbix_server.conf). ```bash grep AlertScriptsPath /etc/zabbix/zabbix_server.conf ``` - > **Note:** The script must be executable by the user running the zabbix_server binary (usually "zabbix") on the Zabbix server. For example, `chmod +x grafana_oncall.sh` + > **Note:** The script must be executable by the user running the zabbix_server binary (usually "zabbix") on the + > Zabbix server. For example, `chmod +x grafana_oncall.sh` ```bash ls -lh /usr/lib/zabbix/alertscripts/grafana_oncall.sh @@ -92,6 +96,7 @@ To send alerts to Grafana OnCall, the {ALERT.SEND_TO} value must be set in the [ 1. Specify **Send to** OnCall using the unique integration URL from the above step in the testing window that opens. Create a test message with a body and optional subject and click **Test**. @@ -103,9 +108,11 @@ Use the following procedure to configure grouping and auto-resolve. 1. Provide a parameter as an identifier for group differentiation to Grafana OnCall. 1. Append that variable to the subject of the action as `ONCALL_GROUP: ID`, where `ID` is any of the Zabbix [macros](https://www.zabbix.com/documentation/4.2/manual/appendix/macros/supported_by_location). - For example, `{EVENT.ID}`. The Grafana OnCall script [grafana_oncall.sh](#grafana_oncallsh-script) extracts this event and passes the `alert_uid` to Grafana OnCall. + For example, `{EVENT.ID}`. The Grafana OnCall script [grafana_oncall.sh](#grafana_oncallsh-script) extracts this event + and passes the `alert_uid` to Grafana OnCall. -1. To enable auto-resolve within Grafana Oncall, the "Resolved" keyword is required in the **Default subject** field in **Recovered operations**. +1. To enable auto-resolve within Grafana Oncall, the "Resolved" keyword is required in the **Default subject** field + in **Recovered operations**. diff --git a/docs/sources/integrations/chatops-integrations/_index.md b/docs/sources/integrations/chatops-integrations/_index.md index c96e8d6e..038042aa 100644 --- a/docs/sources/integrations/chatops-integrations/_index.md +++ b/docs/sources/integrations/chatops-integrations/_index.md @@ -17,7 +17,9 @@ 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/" >}}). +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: diff --git a/docs/sources/integrations/chatops-integrations/configure-slack/index.md b/docs/sources/integrations/chatops-integrations/configure-slack/index.md index 33d29016..75aff6d9 100644 --- a/docs/sources/integrations/chatops-integrations/configure-slack/index.md +++ b/docs/sources/integrations/chatops-integrations/configure-slack/index.md @@ -17,16 +17,20 @@ weight: 100 # Slack integration for Grafana OnCall -The Slack integration for Grafana OnCall incorporates your Slack workspace directly into your incident response workflow to help your team focus on alert resolution with less friction. - -Integrating your Slack workspace with Grafana OnCall allows users and teams to be notified of alerts directly in Slack with automated alert escalation steps and user notification preferences. There are a number of alert actions that users can take directly from Slack, including acknowledge, resolve, add resolution notes, and more. +The Slack integration for Grafana OnCall incorporates your Slack workspace directly into your incident response workflow +to help your team focus on alert resolution with less friction. +Integrating your Slack workspace with Grafana OnCall allows users and teams to be notified of alerts directly in Slack +with automated alert escalation steps and user notification preferences. There are a number of alert actions that users +can take directly from Slack, including acknowledge, resolve, add resolution notes, and more. ## Before you begin -To install the Slack integration, you must have Admin permissions in your Grafana instance as well as the Slack workspace that you’d like to integrate with. +To install the Slack integration, you must have Admin permissions in your Grafana instance as well as the Slack workspace +that you’d like to integrate with. -For Open Source Grafana OnCall Slack installation guidance, refer to [Open Source Grafana OnCall]({{< relref "../../../open-source/" >}}). +For Open Source Grafana OnCall Slack installation guidance, refer to +[Open Source Grafana OnCall]({{< relref "../../../open-source/" >}}). ## Install Slack integration for Grafana OnCall @@ -36,34 +40,44 @@ For Open Source Grafana OnCall Slack installation guidance, refer to [Open Sourc 4. Provide your Slack workspace URL and sign with your Slack credentials. 5. Click **Allow** to give Grafana OnCall permission to access your Slack workspace. - ## Post-install configuration for Slack integration -Configure the following additional settings to ensure Grafana OnCall alerts are routed to the intended Slack channels and users: +Configure the following additional settings to ensure Grafana OnCall alerts are routed to the intended Slack channels +and users: -1. From your **Slack integration** settings, select a default slack channel in the first dropdown menu. This is where alerts will be sent unless otherwise specified in escalation chains. -2. In **Additional Settings**, configure alert reminders for alerts to retrigger after being acknowledged for some amount of time. +1. From your **Slack integration** settings, select a default slack channel in the first dropdown menu. This is where + alerts will be sent unless otherwise specified in escalation chains. +2. In **Additional Settings**, configure alert reminders for alerts to retrigger after being acknowledged for some + amount of time. 3. Ensure all users verify their slack account in their Grafana OnCall **users info**. ### Configure Escalation Chains with Slack notifications -Once your Slack integration is configured you can configure Escalation Chains to notify via Slack messages for alerts in Grafana OnCall. -There are two Slack notification options that you can configure into escalation chains, notify whole Slack channel and notify Slack user group: +Once your Slack integration is configured you can configure Escalation Chains to notify via Slack messages for alerts +in Grafana OnCall. -1. In Grafana OnCall, navigate to the **Escalation Chains** tab then select an existing escalation chain or click **+ New escalation chain**. +There are two Slack notification options that you can configure into escalation chains, notify whole Slack channel and +notify Slack user group: + +1. In Grafana OnCall, navigate to the **Escalation Chains** tab then select an existing escalation chain or + click **+ New escalation chain**. 2. Click the dropdown for **Add escalation step**. 3. Configure your escalation chain with automated Slack notifications. ### Configure user notifications with Slack mentions + To be notified of alerts in Grafana OnCall via Slack mentions: 1. Navigate to the **Users** tab in Grafana OnCall, click **Edit** next to a user. 2. In the **User Info** tab, edit or configure notification steps by clicking + Add Notification step -3. select **Notify by** in the first dropdown and select **Slack mentions** in the second dropdown to receive alert notifications via Slack mentions. +3. select **Notify by** in the first dropdown and select **Slack mentions** in the second dropdown to receive alert + notifications via Slack mentions. ### Configure on-call notifications in Slack -The Slack integration for Grafana Oncall supports automated Slack on-call notifications that notify individuals and teams of their on-call shifts. Admins can configure shift notification behavior in Notification preferences: -1. When an on-call shift notification is sent to a person or channel, click the gear icon to access **Notifications preferences**. +The Slack integration for Grafana Oncall supports automated Slack on-call notifications that notify individuals and +teams of their on-call shifts. Admins can configure shift notification behavior in Notification preferences: + +1. When an on-call shift notification is sent to a person or channel, click the gear icon to + access **Notifications preferences**. 2. Configure on-call notifications for future shift notifications. - diff --git a/docs/sources/integrations/chatops-integrations/configure-teams/index.md b/docs/sources/integrations/chatops-integrations/configure-teams/index.md index b4f42450..6946ead1 100644 --- a/docs/sources/integrations/chatops-integrations/configure-teams/index.md +++ b/docs/sources/integrations/chatops-integrations/configure-teams/index.md @@ -18,48 +18,63 @@ weight: 500 # Microsoft Teams integration for Grafana OnCall -The Microsoft Teams integration for Grafana OnCall embeds your MS Teams channels directly into your incident response workflow to help your team focus on alert resolution. +The Microsoft Teams integration for Grafana OnCall embeds your MS Teams channels directly into your incident response +workflow to help your team focus on alert resolution. -Integrating MS Teams with Grafana OnCall allows users to be notified of alerts directly in MS Teams with automated escalation steps and user notification preferences. Users can also take action on alerts directly from MS Teams, including acknowledge, unacknowledge, resolve, and silence. +Integrating MS Teams with Grafana OnCall allows users to be notified of alerts directly in MS Teams with automated escalation +steps and user notification preferences. Users can also take action on alerts directly from MS Teams, including +acknowledge, unacknowledge, resolve, and silence. ## Before you begin ->NOTE: **This integration is available to Grafana Cloud instances of Grafana OnCall only.** + +> NOTE: **This integration is available to Grafana Cloud instances of Grafana OnCall only.** The following is required to connect to Microsoft Teams to Grafana OnCall: + - You must have Admin permissions in your Grafana Cloud instance. - You must have Owner permissions in Microsoft Teams. - Install the Grafana OnCall app from the [Microsoft Marketplace](https://appsource.microsoft.com/en-us/product/office/WA200004307). ## Install Microsoft Teams integration for Grafana OnCall + 1. From the **ChatOps** tab in Grafana OnCall, select **Microsoft Teams** in the side menu. 1. Click **+Connect Microsoft Teams channel**. -2. Follow the steps provided to connect to your Teams channels, then click **Done**. -3. To add additional teams and channels click **+Connect Microsoft Teams channel** again and repeat step 3 as needed. - +1. Follow the steps provided to connect to your Teams channels, then click **Done**. +1. To add additional teams and channels click **+Connect Microsoft Teams channel** again and repeat step 3 as needed. ## Post-install configuration for Microsoft Teams integration + Configure the following settings to ensure Grafana OnCall alerts are routed to the intended Teams channels and users: -- Set a default channel from the list of connected MS Teams channels. This is where alerts will be sent unless otherwise specified in escalation chains. +- Set a default channel from the list of connected MS Teams channels. This is where alerts will be sent unless otherwise + specified in escalation chains. - Ensure all users verify their MS Teams account in their Grafana OnCall user profile. ### Connect Microsoft Teams user to Grafana OnCall + 1. From the **Users** tab in Grafana OnCall, click **View my profile**. 1. Navigate to **Microsoft Teams username**, click **Connect**. -2. Follow the steps provided to connect your Teams user. -3. Navigate back to your Grafana OnCall profile and verify that your Microsoft Teams account is linked to your Grafana OnCall user. +1. Follow the steps provided to connect your Teams user. +1. Navigate back to your Grafana OnCall profile and verify that your Microsoft Teams account is linked to your Grafana + OnCall user. ### Configure user notifications with Microsoft Teams + To be notified of Grafana OnCall alerts via MS Teams: + 1. Navigate to the **Users** tab in Grafana OnCall, click **Edit** next to a user. 1. In the **User Info** tab, edit or configure notification steps by clicking **+Add Notification step** -1. Select **Notify by** in the first dropdown and select **Microsoft Teams** in the second dropdown to receive alert notifications in Teams. +1. Select **Notify by** in the first dropdown and select **Microsoft Teams** in the second dropdown to receive alert + notifications in Teams. ### Configure escalation chains to post to Microsoft Teams channels -Once your MS Teams integration is configured you can add an escalation step at the integration level to automatically send alerts from a specific integration to a channel in MS Teams. - + +Once your MS Teams integration is configured you can add an escalation step at the integration level to automatically +send alerts from a specific integration to a channel in MS Teams. + To automatically send alerts from an integration to MS Teams channels: -1. Navigate to the **Integrations** tab in Grafana OnCall, select an existing integration or click **+New integration for receiving alerts**. +1. Navigate to the **Integrations** tab in Grafana OnCall, select an existing integration or + click **+New integration for receiving alerts**. 1. From the integrations settings, navigate to the escalation chain panel. -1. Enable **Post to Microsoft Teams channel** by selecting a channel to connect from the dropdown. \ No newline at end of file +1. Enable **Post to Microsoft Teams channel** by selecting a channel to connect from the dropdown. diff --git a/docs/sources/integrations/chatops-integrations/configure-telegram/index.md b/docs/sources/integrations/chatops-integrations/configure-telegram/index.md index fd510340..e24d87e7 100644 --- a/docs/sources/integrations/chatops-integrations/configure-telegram/index.md +++ b/docs/sources/integrations/chatops-integrations/configure-telegram/index.md @@ -21,14 +21,16 @@ You can manage alerts either directly in your personal Telegram DMs or in a dedi ## Configure Telegram user settings in Grafana OnCall -To receive alert group contents, escalation logs and to be able to perform actions (acknowledge, resolve, silence) in Telegram DMs, please refer to the following steps: +To receive alert group contents, escalation logs and to be able to perform actions (acknowledge, resolve, silence) in +Telegram DMs, please refer to the following steps: 1. In your profile, find the 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 and wait for the connection confirmation. 1. Done! Now you can receive alerts directly to your Telegram DMs. -If you want to connect manually, you can click the URL provided and then **SEND MESSAGE**. In your Telegram account, click **Start**. +If you want to connect manually, you can click the URL provided and then **SEND MESSAGE**. In your Telegram account, +click **Start**. ## (Optional) Connect to a Telegram channel @@ -37,7 +39,8 @@ In case you want to manage alerts in a dedicated Telegram channel, please use th > **NOTE:** Only Grafana users with the administrator role can configure OnCall settings. 1. In OnCall, click on the **ChatOps** tab and select Telegram in the side menu. -1. Click **Connect Telegram channel** and follow the instructions, mirrored here for reference. A unique verification code will be generated that you must use to activate the channel. +1. Click **Connect Telegram channel** and follow the instructions, mirrored here for reference. A unique verification + code will be generated that you must use to activate the channel. 1. In your team Telegram account, create a new channel, and set it to **Private**. 1. In **Manage Channel**, make sure **Sign messages** is enabled. 1. Create a new discussion group. @@ -50,5 +53,7 @@ In case you want to manage alerts in a dedicated Telegram channel, please use th 1. In OnCall, send the provided verification code to the channel. 1. Make sure users connect to Telegram in their OnCall user profile. -Each alert group is assigned a dedicated discussion. Users can perform actions (acknowledge, resolve, silence), and discuss alerts in the comments section of the discussions. -In case an integration route is not configured to use a Telegram channel, users will receive messages with alert group contents, logs and actions in their DMs. +Each alert group is assigned a dedicated discussion. Users can perform actions (acknowledge, resolve, silence), and +discuss alerts in the comments section of the discussions. +In case an integration route is not configured to use a Telegram channel, users will receive messages with alert group +contents, logs and actions in their DMs. diff --git a/docs/sources/oncall-api-reference/_index.md b/docs/sources/oncall-api-reference/_index.md index cc453fec..12ae513a 100644 --- a/docs/sources/oncall-api-reference/_index.md +++ b/docs/sources/oncall-api-reference/_index.md @@ -27,7 +27,8 @@ curl "api_endpoint_here" --header "Authorization: "api_key_here"" Grafana OnCall uses API keys to allow access to the API. You can request a new OnCall API key in OnCall -> Settings page. -An API key is specific to a user and a Grafana stack. If you want to switch to a different stack configuration, request a different API key. +An API key is specific to a user and a Grafana stack. If you want to switch to a different stack configuration, +request a different API key. ## Pagination @@ -44,7 +45,8 @@ The OnCall API returns them in pages. Note that the page size may vary. ## Rate Limits -Grafana OnCall provides rate limits to ensure alert group notifications will be delivered to your Slack workspace even when some integrations produce a large number of alerts. +Grafana OnCall provides rate limits to ensure alert group notifications will be delivered to your Slack workspace even +when some integrations produce a large number of alerts. ### Monitoring integrations Rate Limits diff --git a/docs/sources/oncall-api-reference/alertgroups.md b/docs/sources/oncall-api-reference/alertgroups.md index e578644d..abd4e294 100644 --- a/docs/sources/oncall-api-reference/alertgroups.md +++ b/docs/sources/oncall-api-reference/alertgroups.md @@ -63,11 +63,16 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \ }' ``` + + | Parameter | Required | Description | | --------- | :------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | No | Default setting is `wipe`. `wipe` will remove the payload of all Grafana OnCall group alerts. This is useful if you sent sensitive data to OnCall. All metadata will remain. `DELETE` will trigger the removal of alert groups, alerts, and all related metadata. It will also remove alert group notifications in Slack and other destinations. | -> **NOTE:** `DELETE` can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs such as Slack. Please check objects using `GET` to be sure the data is removed. + + +> **NOTE:** `DELETE` can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs +> such as Slack. Please check objects using `GET` to be sure the data is removed. **HTTP request** diff --git a/docs/sources/oncall-api-reference/escalation_policies.md b/docs/sources/oncall-api-reference/escalation_policies.md index 26c8a470..0cca0501 100644 --- a/docs/sources/oncall-api-reference/escalation_policies.md +++ b/docs/sources/oncall-api-reference/escalation_policies.md @@ -32,6 +32,8 @@ The above command returns JSON structured in the following way: } ``` + + | Parameter | Required | Description | | ---------------------------------- | :--------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `escalation_chain_id` | Yes | Each escalation policy is assigned to a specific escalation chain. | @@ -47,6 +49,8 @@ The above command returns JSON structured in the following way: | `notify_if_time_from` | If type = `notify_if_time_from_to` | UTC time represents the beginning of the time period, for example `09:00:00Z`. | | `notify_if_time_to` | If type = `notify_if_time_from_to` | UTC time represents the end of the time period, for example `18:00:00Z`. | + + **HTTP request** `POST {{API_URL}}/api/v1/escalation_policies/` diff --git a/docs/sources/oncall-api-reference/integrations.md b/docs/sources/oncall-api-reference/integrations.md index 282e39df..b792e459 100644 --- a/docs/sources/oncall-api-reference/integrations.md +++ b/docs/sources/oncall-api-reference/integrations.md @@ -67,7 +67,8 @@ 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/" >}}). +For example, to learn how to integrate Grafana OnCall with Alertmanager see +[Alertmanager]({{< relref "../integrations/available-integrations/configure-alertmanager/" >}}). **HTTP request** @@ -278,7 +279,8 @@ The above command returns JSON structured in the following way: # Delete integration -Deleted integrations will stop recording new alerts from monitoring. Integration removal won't trigger removal of related alert groups or alerts. +Deleted integrations will stop recording new alerts from monitoring. Integration removal won't trigger removal of +related alert groups or alerts. ```shell curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \ diff --git a/docs/sources/oncall-api-reference/on_call_shifts.md b/docs/sources/oncall-api-reference/on_call_shifts.md index f06a8d12..dd108676 100644 --- a/docs/sources/oncall-api-reference/on_call_shifts.md +++ b/docs/sources/oncall-api-reference/on_call_shifts.md @@ -43,6 +43,8 @@ The above command returns JSON structured in the following way: } ``` + + | Parameter | Unique | Required | Description | | -------------------------------- | :----: | :--------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | Yes | On-call shift name. | @@ -52,9 +54,9 @@ The above command returns JSON structured in the following way: | `level` | No | Optional | Priority level. The higher the value, the higher the priority. If two events overlap in one schedule, Grafana OnCall will choose the event with higher level. For example: Alex is on-call from 8AM till 11AM with level 1, Bob is on-call from 9AM till 11AM with level 2. At 10AM Grafana OnCall will notify Bob. At 8AM OnCall will notify Alex. | | `start` | No | Yes | Start time of the on-call shift. This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example "2020-09-05T08:00:00"). | | `duration` | No | Yes | Duration of the event. | -| `frequency` | No | If type = `recurrent_event` or `rolling_users` | One of: `hourly`, `daily`, `weekly`, `monthly`. | +| `frequency` | No | If type = `recurrent_event` or `rolling_users` | One of: `hourly`, `daily`, `weekly`, `monthly`. | | `interval` | No | Optional | This parameter takes a positive integer that represents the intervals that the recurrence rule repeats. | -| `until` | No | Optional | When the recurrence rule ends (endless if None). This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example "2020-09-05T08:00:00"). | +| `until` | No | Optional | When the recurrence rule ends (endless if None). This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example "2020-09-05T08:00:00"). | | `week_start` | No | Optional | Start day of the week in iCal format. One of: `SU` (Sunday), `MO` (Monday), `TU` (Tuesday), `WE` (Wednesday), `TH` (Thursday), `FR` (Friday), `SA` (Saturday). Default: `SU`. | | `by_day` | No | Optional | List of days in iCal format. Valid values are: `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA`. | | `by_month` | No | Optional | List of months. Valid values are `1` to `12`. | @@ -63,6 +65,8 @@ The above command returns JSON structured in the following way: | `rolling_users` | No | Optional | List of lists with on-call users (for `rolling_users` event type). Grafana OnCall will iterate over lists of users for every time frame specified in `frequency`. For example: there are two lists of users in `rolling_users` : [[Alex, Bob], [Alice]] and `frequency` = `daily` . This means that the first day Alex and Bob will be notified. The next day: Alice. The day after: Alex and Bob again and so on. | | `start_rotation_from_user_index` | No | Optional | Index of the list of users in `rolling_users`, from which on-call rotation starts. By default, the start index is `0` | + + Please see [RFC 5545](https://tools.ietf.org/html/rfc5545#section-3.3.10) for more information about recurrence rules. **HTTP request** diff --git a/docs/sources/oncall-api-reference/personal_notification_rules.md b/docs/sources/oncall-api-reference/personal_notification_rules.md index fdf92646..cff10373 100644 --- a/docs/sources/oncall-api-reference/personal_notification_rules.md +++ b/docs/sources/oncall-api-reference/personal_notification_rules.md @@ -31,6 +31,8 @@ The above command returns JSON structured in the following way: } ``` + + | Parameter | Required | Description | | ----------- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Yes | User ID | @@ -39,6 +41,8 @@ The above command returns JSON structured in the following way: | `duration` | Optional | A time in secs when type `wait` is chosen for `type`. | | `important` | Optional | Boolean value indicates if a rule is "important". Default is `false`. | + + **HTTP request** `POST {{API_URL}}/api/v1/personal_notification_rules/` diff --git a/docs/sources/oncall-api-reference/routes.md b/docs/sources/oncall-api-reference/routes.md index 5f92e79a..a51209ab 100644 --- a/docs/sources/oncall-api-reference/routes.md +++ b/docs/sources/oncall-api-reference/routes.md @@ -46,14 +46,18 @@ Routes allow you to direct different alerts to different messenger channels and - Alerts for different engineering groups - Snoozing spam & debugging alerts + + | Parameter | Unique | Required | Description | | --------------------- | :----: | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `integration_id` | No | Yes | Each route is assigned to a specific integration. | | `escalation_chain_id` | No | Yes | Each route is assigned a specific escalation chain. | -| `routing_regex` | Yes | Yes | Python Regex query (use https://regex101.com/ for debugging). OnCall chooses the route for an alert in case there is a match inside the whole alert payload. | +| `routing_regex` | Yes | Yes | Python Regex query (use for debugging). OnCall chooses the route for an alert in case there is a match inside the whole alert payload. | | `position` | Yes | Optional | Route matching is performed one after another starting from position=`0`. Position=`-1` will put the route to the end of the list before `is_the_last_route`. A new route created with a position of an existing route will move the old route (and all following routes) down in the list. | | `slack` | Yes | Optional | Dictionary with Slack-specific settings for a route. | + + **HTTP request** `POST {{API_URL}}/api/v1/routes/` diff --git a/docs/sources/oncall-api-reference/schedules.md b/docs/sources/oncall-api-reference/schedules.md index 53b19f81..4be429b7 100644 --- a/docs/sources/oncall-api-reference/schedules.md +++ b/docs/sources/oncall-api-reference/schedules.md @@ -41,6 +41,8 @@ The above command returns JSON structured in the following way: } ``` + + | Parameter | Unique | Required | Description | | -------------------- | :----: | :--------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | Yes | Schedule name. | @@ -52,6 +54,8 @@ The above command returns JSON structured in the following way: | `slack` | No | Optional | Dictionary with Slack-specific settings for a schedule. Includes `channel_id` and `user_group_id` fields, that take a channel ID and a user group ID from Slack. | | `shifts` | No | Optional | List of shifts. Used for manually added on-call shifts in Schedules with type `calendar`. | + + **HTTP request** `POST {{API_URL}}/api/v1/schedules/` diff --git a/docs/sources/oncall-api-reference/user_groups.md b/docs/sources/oncall-api-reference/user_groups.md index c078eb13..2c5966a0 100644 --- a/docs/sources/oncall-api-reference/user_groups.md +++ b/docs/sources/oncall-api-reference/user_groups.md @@ -38,12 +38,16 @@ The above command returns JSON structured in the following way: } ``` + + | Parameter | Unique | Description | | --------- | :----: | :---------------------------------------------------------------------------------------------------- | | `id` | Yes | User Group ID | | `type` | No | [Slack-defined user groups](https://slack.com/intl/en-ru/help/articles/212906697-Create-a-user-group) | | `slack` | No | Metadata retrieved from Slack. | + + **HTTP request** `GET {{API_URL}}/api/v1/user_groups/` diff --git a/docs/sources/open-source/_index.md b/docs/sources/open-source/_index.md index d92eeec5..fbce4292 100644 --- a/docs/sources/open-source/_index.md +++ b/docs/sources/open-source/_index.md @@ -9,7 +9,9 @@ weight: 300 # 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. +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. @@ -22,27 +24,33 @@ There are three Grafana OnCall OSS environments available: - **Production** environment for reliable cloud installation using Helm: [Production Environment](#production-environment) ## Production Environment -We suggest using our official helm chart for the reliable production deployment of Grafana OnCall. It will deploy Grafana OnCall engine and celery workers, along with RabbitMQ cluster, Redis Cluster, and the database. ->**Note:** The Grafana OnCall engine currently supports one instance of the Grafana OnCall plugin at a time. +We suggest using our official helm chart for the reliable production deployment of Grafana OnCall. It will deploy +Grafana OnCall engine and celery workers, along with RabbitMQ cluster, Redis Cluster, and the database. -Check the [helm chart](https://github.com/grafana/oncall/tree/dev/helm/oncall) for more details. +> **Note:** The Grafana OnCall engine currently supports one instance of the Grafana OnCall plugin at a time. -We'll always be happy to provide assistance with production deployment in [our communities](https://github.com/grafana/oncall#join-community)! +Check the [helm chart](https://github.com/grafana/oncall/tree/dev/helm/oncall) for more details. + +We'll always be happy to provide assistance with production deployment in [our communities](https://github.com/grafana/oncall#join-community)! ## Update Grafana OnCall OSS + To update an OSS installation of Grafana OnCall, please see the update docs: + - **Hobby** playground environment: [README.md](https://github.com/grafana/oncall#update-version) - **Production** Helm environment: [Helm update](https://github.com/grafana/oncall/tree/dev/helm/oncall#update) ## Slack Setup -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: +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: 1. Ensure your Grafana OnCall environment is up and running. -1. Grafana OnCall must be accessible through HTTPS. For development purposes, use [localtunnel](https://github.com/localtunnel/localtunnel). For production purposes, consider establishing a proper web server with HTTPS termination. -For localtunnel, refer to the following configuration: +1. Grafana OnCall must be accessible through HTTPS. For development purposes, use [localtunnel](https://github.com/localtunnel/localtunnel). + For production purposes, consider establishing a proper web server with HTTPS termination. + For localtunnel, refer to the following configuration: ```bash # Choose the unique prefix instead of pretty-turkey-83 @@ -55,107 +63,109 @@ lt --port 8080 -s pretty-turkey-83 --print-requests 1. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. -1. Go to https://api.slack.com/apps and click **Create an App** . +1. Go to and click **Create an App** . 1. Select `From an app manifest` option and select your workspace. -1. Replace the text with the following YAML code block . Be sure to replace `` and `` fields with the appropriate information. +1. Replace the text with the following YAML code block . Be sure to replace `` and `` + fields with the appropriate information. - ```yaml - _metadata: - major_version: 1 - minor_version: 1 - display_information: - name: - features: - app_home: - home_tab_enabled: true - messages_tab_enabled: true - messages_tab_read_only_enabled: false - bot_user: - display_name: - always_online: true - shortcuts: - - name: Create a new incident - type: message - callback_id: incident_create - description: Creates a new OnCall incident - - name: Add to resolution note - type: message - callback_id: add_resolution_note - description: Add this message to resolution note - slash_commands: - - command: /oncall - url: /slack/interactive_api_endpoint/ - description: oncall - should_escape: false - oauth_config: - redirect_urls: - - /api/internal/v1/complete/slack-install-free/ - - /api/internal/v1/complete/slack-login/ - scopes: - user: - - channels:read - - chat:write - - identify - - users.profile:read - bot: - - app_mentions:read - - channels:history - - channels:read - - chat:write - - chat:write.customize - - chat:write.public - - commands - - files:write - - groups:history - - groups:read - - im:history - - im:read - - im:write - - mpim:history - - mpim:read - - mpim:write - - reactions:write - - team:read - - usergroups:read - - usergroups:write - - users.profile:read - - users:read - - users:read.email - - users:write - settings: - event_subscriptions: - request_url: /slack/event_api_endpoint/ - bot_events: - - app_home_opened - - app_mention - - channel_archive - - channel_created - - channel_deleted - - channel_rename - - channel_unarchive - - member_joined_channel - - message.channels - - message.im - - subteam_created - - subteam_members_changed - - subteam_updated - - user_change - interactivity: - is_enabled: true - request_url: /slack/interactive_api_endpoint/ - org_deploy_enabled: false - socket_mode_enabled: false - ``` +```yaml +_metadata: + major_version: 1 + minor_version: 1 +display_information: + name: +features: + app_home: + home_tab_enabled: true + messages_tab_enabled: true + messages_tab_read_only_enabled: false + bot_user: + display_name: + always_online: true + shortcuts: + - name: Create a new incident + type: message + callback_id: incident_create + description: Creates a new OnCall incident + - name: Add to resolution note + type: message + callback_id: add_resolution_note + description: Add this message to resolution note + slash_commands: + - command: /oncall + url: /slack/interactive_api_endpoint/ + description: oncall + should_escape: false +oauth_config: + redirect_urls: + - /api/internal/v1/complete/slack-install-free/ + - /api/internal/v1/complete/slack-login/ + scopes: + user: + - channels:read + - chat:write + - identify + - users.profile:read + bot: + - app_mentions:read + - channels:history + - channels:read + - chat:write + - chat:write.customize + - chat:write.public + - commands + - files:write + - groups:history + - groups:read + - im:history + - im:read + - im:write + - mpim:history + - mpim:read + - mpim:write + - reactions:write + - team:read + - usergroups:read + - usergroups:write + - users.profile:read + - users:read + - users:read.email + - users:write +settings: + event_subscriptions: + request_url: /slack/event_api_endpoint/ + bot_events: + - app_home_opened + - app_mention + - channel_archive + - channel_created + - channel_deleted + - channel_rename + - channel_unarchive + - member_joined_channel + - message.channels + - message.im + - subteam_created + - subteam_members_changed + - subteam_updated + - user_change + interactivity: + is_enabled: true + request_url: /slack/interactive_api_endpoint/ + org_deploy_enabled: false + socket_mode_enabled: false +``` 1. 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 >> - ``` + + ```text + 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 >> + ``` 1. In OnCall, navigate to **ChatOps**, select Slack and click **Install Slack integration**. @@ -163,17 +173,25 @@ lt --port 8080 -s pretty-turkey-83 --print-requests ## Telegram Setup -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: +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: -1. Ensure your Grafana OnCall environment is up and running. -2. Create a Telegram bot using [BotFather](https://t.me/BotFather) and save the token provided by BotFather. Please make sure to disable **Group Privacy** for the bot (Bot Settings -> Group Privacy -> Turn off). -3. Paste the token provided by BotFather to the `TELEGRAM_TOKEN` variable on the **Env Variables** page of your Grafana OnCall instance. -4. Set the `TELEGRAM_WEBHOOK_HOST` variable to the external address of your Grafana OnCall instance. Please note that `TELEGRAM_WEBHOOK_HOST` must start with `https://` and be publicly available (meaning that it can be reached by Telegram servers). If your host is private or local, consider using a reverse proxy (e.g. [ngrok](https://ngrok.com)). -5. Now you can connect Telegram accounts on the **Users** page and receive alert groups to Telegram direct messages. Alternatively, in case you want to connect Telegram channels to your Grafana OnCall environment, navigate to the **ChatOps** tab. +1. Ensure your Grafana OnCall environment is up and running. +2. Create a Telegram bot using [BotFather](https://t.me/BotFather) and save the token provided by BotFather. Please make + sure to disable **Group Privacy** for the bot (Bot Settings -> Group Privacy -> Turn off). +3. Paste the token provided by BotFather to the `TELEGRAM_TOKEN` variable on the **Env Variables** page of your + Grafana OnCall instance. +4. Set the `TELEGRAM_WEBHOOK_HOST` variable to the external address of your Grafana OnCall instance. Please note + that `TELEGRAM_WEBHOOK_HOST` must start with `https://` and be publicly available (meaning that it can be reached by + Telegram servers). If your host is private or local, consider using a reverse proxy (e.g. [ngrok](https://ngrok.com)). +5. Now you can connect Telegram accounts on the **Users** page and receive alert groups to Telegram direct messages. + Alternatively, in case you want to connect Telegram channels to your Grafana OnCall environment, navigate + to the **ChatOps** tab. ## Grafana OSS-Cloud Setup The benefits of connecting to Grafana Cloud include: + - Cloud OnCall could monitor OSS OnCall uptime using heartbeat - SMS for user notifications - Phone calls for user notifications. @@ -182,13 +200,16 @@ To connect to Grafana Cloud, refer to the **Cloud** page in your OSS Grafana OnC ## Twilio Setup -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: +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: 1. Set `GRAFANA_CLOUD_NOTIFICATIONS_ENABLED` as **False** to ensure the Grafana OSS <-> Cloud connector is disabled. -1. From your **OnCall** environment, select **Env Variables** and configure all variables starting with `TWILIO_`. +1. From your **OnCall** environment, select **Env Variables** and configure all variables starting with `TWILIO_`. ## Email Setup -Grafana OnCall is capable of sending emails using SMTP as a user notification step. To setup email notifications, populate the following env variables with your SMTP server credentials: + +Grafana OnCall is capable of sending emails using SMTP as a user notification step. To setup email notifications, populate +the following env variables with your SMTP server credentials: - `EMAIL_HOST` - SMTP server host - `EMAIL_HOST_USER` - SMTP server user diff --git a/engine/config_integrations/README.md b/engine/config_integrations/README.md index 13c7189d..e4eaef6b 100644 --- a/engine/config_integrations/README.md +++ b/engine/config_integrations/README.md @@ -1,21 +1,33 @@ # Contribute the new Integration to OnCall -Related: [DEVELOPER.md](/DEVELOPER.md) +Related: [DEVELOPER.md](../../dev/README.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" 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/). +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. +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 -# 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. +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. +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? +## 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. +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/grafana-plugin/babel.config.json b/grafana-plugin/babel.config.json index 3776c289..2cba8024 100644 --- a/grafana-plugin/babel.config.json +++ b/grafana-plugin/babel.config.json @@ -10,6 +10,6 @@ "@babel/plugin-transform-runtime", "@babel/proposal-class-properties", "@babel/transform-regenerator", - "@babel/plugin-transform-template-literals", + "@babel/plugin-transform-template-literals" ] } diff --git a/helm/README.md b/helm/README.md index 05e8f471..065f411d 100644 --- a/helm/README.md +++ b/helm/README.md @@ -4,13 +4,13 @@ > Make sure ports 30001 and 30002 are free on your machine - ``` + ```bash kind create cluster --image kindest/node:v1.24.7 --config kind.yml ``` 2. Install the helm chart - ``` + ```bash helm install helm-testing \ ../oncall --wait --timeout 30m \ --wait-for-jobs \ @@ -20,13 +20,18 @@ 3. Get credentials - ``` + + + ```bash echo "\n\nOpen Grafana on localhost:30002 with credentials - user: admin, password: $(kubectl get secret --namespace default helm-testing-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo)" echo "Open Plugins -> Grafana OnCall -> fill form: backend url: localhost:30001, grafana url: localhost: 30001, token below" export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=oncall,app.kubernetes.io/instance=helm-testing,app.kubernetes.io/component=engine" -o jsonpath="{.items[0].metadata.name}") ``` + + 4. Clean up - ``` + + ```bash kind delete cluster ``` diff --git a/helm/oncall/README.md b/helm/oncall/README.md index 29a3da6b..172758fe 100644 --- a/helm/oncall/README.md +++ b/helm/oncall/README.md @@ -3,12 +3,18 @@ This Grafana OnCall Chart is the best way to operate Grafana OnCall on Kubernetes. It will deploy Grafana OnCall engine and celery workers, along with RabbitMQ cluster, Redis Cluster, and MySQL 5.7 database. It will also deploy cert manager and nginx ingress controller, as Grafana OnCall backend might need to be externally available -to receive alerts from other monitoring systems. Grafana OnCall engine acts as a backend and can be connected to the Grafana frontend plugin named Grafana OnCall. +to receive alerts from other monitoring systems. Grafana OnCall engine acts as a backend and can be connected to the +Grafana frontend plugin named Grafana OnCall. Architecture diagram can be found [here](https://raw.githubusercontent.com/grafana/oncall/dev/docs/img/architecture_diagram.png) ## Production usage -**Default helm chart configuration is not intended for production.** The helm chart includes all the services into a single release, which is not recommended for production usage. It is recommended to run stateful services such as MySQL and RabbitMQ separately from this release or use managed PaaS solutions. It will significantly reduce the overhead of managing them. Here are the instructions on how to set up your own [ingress](#set-up-external-access), [MySQL](#connect-external-mysql), [RabbitMQ](#connect-external-rabbitmq), [Redis](#connect-external-redis) +**Default helm chart configuration is not intended for production.** +The helm chart includes all the services into a single release, which is not recommended for production usage. +It is recommended to run stateful services such as MySQL and RabbitMQ separately from this release or use managed +PaaS solutions. It will significantly reduce the overhead of managing them. +Here are the instructions on how to set up your own [ingress](#set-up-external-access), [MySQL](#connect-external-mysql), +[RabbitMQ](#connect-external-rabbitmq), [Redis](#connect-external-redis) ### Cluster requirements @@ -39,6 +45,8 @@ helm install \ Follow the `helm install` output to finish setting up Grafana OnCall backend and Grafana OnCall frontend plugin e.g. + + ```bash 👋 Your Grafana OnCall instance has been successfully deployed @@ -66,6 +74,8 @@ Follow the `helm install` output to finish setting up Grafana OnCall backend and 🎉🎉🎉 Done! 🎉🎉🎉 ``` + + ## Configuration You can edit values.yml to make changes to the helm chart configuration and re-deploy the release with the following command: @@ -112,9 +122,12 @@ oncall: Grafana OnCall can be connected to the external monitoring systems or grafana deployed to the other cluster. Nginx Ingress Controller and Cert Manager charts are included in the helm chart with the default configuration. -If you set the DNS A Record pointing to the external IP address of the installation with the Hostname matching base_url parameter, https will be automatically set up. If grafana is enabled in the chart values, it will also be available on `https:///grafana/`. See the details in `helm install` output. +If you set the DNS A Record pointing to the external IP address of the installation with the Hostname matching +base_url parameter, https will be automatically set up. If grafana is enabled in the chart values, it will also be +available on `https:///grafana/`. See the details in `helm install` output. -To use a different ingress controller or tls certificate management system, set the following values to false and edit ingress settings +To use a different ingress controller or tls certificate management system, set the following values to +false and edit ingress settings ```yaml ingress-nginx: @@ -252,7 +265,9 @@ helm upgrade \ grafana/oncall ``` -After re-deploying, please also update the Grafana OnCall plugin on the plugin version page. See [Grafana docs](https://grafana.com/docs/grafana/latest/administration/plugin-management/#update-a-plugin) for more info on updating Grafana plugins. +After re-deploying, please also update the Grafana OnCall plugin on the plugin version page. +See [Grafana docs](https://grafana.com/docs/grafana/latest/administration/plugin-management/#update-a-plugin) for +more info on updating Grafana plugins. ## Uninstall @@ -280,4 +295,6 @@ kubectl delete secrets certificate-tls release-oncall-cert-manager-webhook-ca re ### Issues during initial configuration -In the event that you run into issues during initial configuration, it is possible that mismatching versions between your OnCall backend and UI is the culprit. Ensure that the versions match, and if not consider updating your `helm` deployment. +In the event that you run into issues during initial configuration, it is possible that mismatching versions between +your OnCall backend and UI is the culprit. Ensure that the versions match, and if not, +consider updating your `helm` deployment. diff --git a/tools/pagerduty-migrator/README.md b/tools/pagerduty-migrator/README.md index c3e2f4e9..b87a8127 100644 --- a/tools/pagerduty-migrator/README.md +++ b/tools/pagerduty-migrator/README.md @@ -3,26 +3,28 @@ This tool helps to migrate PagerDuty configuration to Grafana OnCall. Resources that can be migrated using this tool: -* User notification rules -* Escalation policies -* On-call schedules -* Integrations (services) +- User notification rules +- Escalation policies +- On-call schedules +- Integrations (services) ## Limitations -* Not all integration types are supported (e.g. inbound email is not supported) -* Migrated on-call schedules in Grafana OnCall will use ICalendar files from PagerDuty -* Delays between migrated notification/escalation rules could be slightly different from original. E.g. if you have a 4-minute delay between rules in PagerDuty, the resulting delay in Grafana OnCall will be 5 minutes +- Not all integration types are supported (e.g. inbound email is not supported) +- Migrated on-call schedules in Grafana OnCall will use ICalendar files from PagerDuty +- Delays between migrated notification/escalation rules could be slightly different from original. + E.g. if you have a 4-minute delay between rules in PagerDuty, the resulting delay in Grafana OnCall will be 5 minutes ## Prerequisites -1. Make sure you have `docker` installed +1. Make sure you have `docker` installed 2. Build the docker image: `docker build -t pd-oncall-migrator .` -3. Obtain a PagerDuty API user token: https://support.pagerduty.com/docs/api-access-keys#generate-a-user-token-rest-api-key +3. Obtain a PagerDuty API user token: 4. Obtain a Grafana OnCall API token and API URL on the "Settings" page of your Grafana OnCall instance ## Migration plan + Before starting the migration process, it's useful to see a migration plan by running the tool in `plan` mode: ```shell @@ -34,11 +36,13 @@ docker run --rm \ pd-oncall-migrator ``` -Please read the generated report carefully since depending on the content of the report, some PagerDuty resources could not be migrated and some existing Grafana OnCall resources could be deleted. - -Note that users are matched by email, so if there are users in the report with "no Grafana OnCall user found with this email" error, it's possible to fix it by adding these users to your Grafana organization. -If there is a large number of unmatched users, please also [see the script](scripts/README.md) that can automatically create missing Grafana users via Grafana HTTP API. +Please read the generated report carefully since depending on the content of the report, some PagerDuty resources +could not be migrated and some existing Grafana OnCall resources could be deleted. +Note that users are matched by email, so if there are users in the report with "no Grafana OnCall user found with +this email" error, it's possible to fix it by adding these users to your Grafana organization. +If there is a large number of unmatched users, please also [see the script](scripts/README.md) that can automatically +create missing Grafana users via Grafana HTTP API. ### Example migration plan @@ -46,7 +50,7 @@ If there is a large number of unmatched users, please also [see the script](scri User notification rules report: ✅ John Doe (john.doe@example.com) (existing notification rules will be deleted) ❌ Ben Thompson (ben@example.com) — no Grafana OnCall user found with this email - + Schedule report: ✅ Support (existing schedule with name 'Support' will be deleted) ✅ Support-shadow @@ -58,15 +62,18 @@ Escalation policy report: ❌ DevOps Escalation Policy — policy references unmatched users and schedules with unmatched users ❌ Ben Thompson (ben@example.com) — no Grafana OnCall user found with this email ❌ DevOps — schedule references unmatched users - + Integration report: ✅ Support - Prometheus (existing integration with name 'Support - Prometheus' will be deleted) - ❌ DevOps - Prometheus — escalation policy 'DevOps Escalation Policy' references unmatched users or schedules with unmatched users + ❌ DevOps - Prometheus — escalation policy 'DevOps Escalation Policy' references unmatched users or schedules + with unmatched users ❌ DevOps - Email — cannot find appropriate Grafana OnCall integration type ``` ## Migration + Once you are happy with the migration report, start the migration by setting the `MODE` environment variable to `migrate`: + ```shell docker run --rm \ -e PAGERDUTY_API_TOKEN="" \ @@ -77,11 +84,13 @@ docker run --rm \ pd-oncall-migrator ``` -It's possible to specify a default contact method type for user notification rules that cannot be migrated as-is by changing the `ONCALL_DEFAULT_CONTACT_METHOD` env variable. Options are: `email`, `sms`, `phone_call`, `slack`, `telegram` (default is `email`). +It's possible to specify a default contact method type for user notification rules that cannot be migrated as-is by +changing the `ONCALL_DEFAULT_CONTACT_METHOD` env variable. +Options are: `email`, `sms`, `phone_call`, `slack`, `telegram` (default is `email`). ### After migration -* Connect integrations (press the "How to connect" button on the integration page) -* Make sure users connect their phone numbers, Slack accounts, etc. in their user settings -* At some point you would probably want to recreate schedules using Google Calendar or Terraform to be able to modify migrated on-call schedules in Grafana OnCall - +- Connect integrations (press the "How to connect" button on the integration page) +- Make sure users connect their phone numbers, Slack accounts, etc. in their user settings +- At some point you would probably want to recreate schedules using Google Calendar or Terraform to be able to modify + migrated on-call schedules in Grafana OnCall diff --git a/tools/pagerduty-migrator/scripts/README.md b/tools/pagerduty-migrator/scripts/README.md index ddd50f87..7e376d05 100644 --- a/tools/pagerduty-migrator/scripts/README.md +++ b/tools/pagerduty-migrator/scripts/README.md @@ -1,8 +1,10 @@ # PagerDuty migrator scripts -When running the migrator in `plan` mode, it can potentially show that some users cannot be matched (meaning that there are no users in Grafana with the same email as in PagerDuty). +When running the migrator in `plan` mode, it can potentially show that some users cannot be matched +(meaning that there are no users in Grafana with the same email as in PagerDuty). -If there is a large number of unmatched users, it can be easier to use the following script that automatically creates missing Grafana users: +If there is a large number of unmatched users, it can be easier to use the following script that +automatically creates missing Grafana users: ```bash docker run --rm \