diff --git a/docs/sources/alerting/fundamentals/alertmanager.md b/docs/sources/alerting/fundamentals/alertmanager.md index 181e5abdfe5..033b9f9da7f 100644 --- a/docs/sources/alerting/fundamentals/alertmanager.md +++ b/docs/sources/alerting/fundamentals/alertmanager.md @@ -9,34 +9,30 @@ weight: 116 # Alertmanager -The Alertmanager helps both group and manage alert rules, adding a layer of orchestration on top of the alerting engines. To learn more, see [Prometheus Alertmanager documentation](https://prometheus.io/docs/alerting/latest/alertmanager/). +Alertmanager enables you to quickly and efficiently manage and respond to alerts. It receives alerts, handles silencing, inhibition, grouping, and routing by sending notifications out via your channel of choice, for example, email or Slack. -Grafana includes built-in support for Prometheus Alertmanager. By default, notifications for Grafana managed alerts are handled by the embedded Alertmanager that is part of core Grafana. You can configure the Alertmanager's contact points, notification policies, silences, and templates from the alerting UI by selecting the `Grafana` option from the Alertmanager drop-down. +In Grafana, you can use the Cloud Alertmanager, Grafana Alertmanager, or an external Alertmanager. You can also run multiple alertmanagers; your decision depends on your set up and where your alerts are being generated. -> **Note:** Before v8.2, the configuration of the embedded Alertmanager was shared across organizations. If you are on an older Grafana version, we recommend that you use Grafana alerts only if you have one organization. Otherwise, your contact points are visible to all organizations. +**Cloud Alertmanager** -Grafana Alerting added support for external Alertmanager configuration. When you add an [Alertmanager data source]({{< relref "../../datasources/alertmanager/" >}}), the Alertmanager drop-down shows a list of available external Alertmanager data sources. Select a data source to create and manage alerting for standalone Grafana Mimir or Loki data sources. +Cloud Alertmanager runs in Grafana Cloud and it can receive alerts from Grafana, Mimir, and Loki. -{{< figure max-width="40%" src="/static/img/docs/alerting/unified/contact-points-select-am-8-0.gif" max-width="250px" caption="Select Alertmanager" >}} +**Grafana Alertmanager** -You can configure one or several external Alertmanagers to receive alerts from Grafana. Once configured, both the embedded Alertmanager **and** any configured external Alertmanagers will receive _all_ alerts. +Grafana Alertmanager is an internal Alertmanager that is pre-configured and available for selection by default if you run Grafana on-premise or open-source. -You can do the setup in the "Admin" tab within the Grafana v8 Alerts UI. +The Grafana Alertmanager can receive alerts from Grafana, but it cannot receive alerts from outside Grafana, for example, from Mimir or Loki. -### Add a new external Alertmanager +**External Alertmanager** -1. In the Grafana menu, click the Alerting (bell) icon to open the Alerting page listing existing alerts. -2. Click **Admin** and then scroll down to the External Alertmanager section. -3. Click **Add Alertmanager** and a modal opens. -4. Add the URL and the port for the external Alertmanager. You do not need to specify the path suffix, for example, `/api/v(1|2)/alerts`. Grafana automatically adds this. +If you want to use a single alertmanager to receive all your Grafana, Loki, Mimir, and Prometheus alerts, you can set up Grafana to use an external Alertmanager. This external Alertmanager can be configured and administered from within Grafana itself. -The external URL is listed in the table with a pending status. Once Grafana verifies that the Alertmanager is discovered, the status changes to active. No requests are made to the external Alertmanager at this point; the verification signals that alerts are ready to be sent. +Here are two examples of when you may want to configure your own external alertmanager and send your alerts there instead of the Grafana Alertmanager: -### Edit an external Alertmanager +1. You may already have alertmanagers on-premise in your own Cloud infrastructure that you have set up and still want to use, because you have other alert generators, such as Prometheus. -1. Click the pen symbol to the right of the Alertmanager row in the table. -2. When the edit modal opens, you can view all the URLs that were added. +2. You want to use both Prometheus on-premise and hosted Grafana to send alerts to the same alertmanager that runs in your Cloud infrastructure. -The edited URL will be pending until Grafana verifies it again. +Alertmanagers are visible from the drop-down menu on the Alerting Contact Points, Notification Policies, and Silences pages. -{{< figure max-width="40%" src="/static/img/docs/alerting/unified/ext-alertmanager-active.png" max-width="650px" caption="External Alertmanagers" >}} +For more information on Alertmanager, refer to [Prometheus Alertmanager documentation](https://prometheus.io/docs/alerting/latest/alertmanager/). diff --git a/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md b/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md new file mode 100644 index 00000000000..8c05b9123a9 --- /dev/null +++ b/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md @@ -0,0 +1,700 @@ +--- +aliases: + - /docs/grafana/latest/alerting/provision-alerting-resources/file-provisioning + - /docs/grafana/latest/alerting/provision-alerting-resources/file-provisioning +description: Create and manage resources using file provisioning +keywords: + - grafana + - alerting + - alerting resources + - file provisioning + - provisioning +title: Create and manage alerting resources using file provisioning +weight: 100 +--- + +## Create and manage alerting resources using file provisioning + +Provision your alerting resources using files from disk. When you start Grafana, the data from these files is created in your Grafana system. Grafana adds any new resources you created, updates any that you changed, and deletes old ones. + +Arrange your files in a directory in a way that best suits your use case. For example, you can choose a team-based layout where every team has its own file, you can have one big file for all your teams; or you can have one file per resource type. + +Details on how to set up the files and which fields are required for each object are listed below depending on which resource you are provisioning. + +**Note:** + +Provisioning takes place during the initial set up of your Grafana system, but you can re-run it at any time using the [Grafana Alerting provisioning API](https://grafana.com/docs/grafana/latest/developers/http_api/admin/#reload-provisioning-configurations). + +### Provision alert rules + +Create or delete alert rules in your Grafana instance(s). + +1. Create an alert rule in Grafana. +1. Use the [Alerting provisioning API](https://grafana.com/docs/grafana/latest/developers/http_api/admin/#reload-provisioning-configurations) to extract the alert rule. +1. Copy the contents into a YAML or JSON configuration file in the default provisioning directory or in your configured directory. + + Example configuration files can be found below. + +1. Ensure that your files are in the right directory on the node running the Grafana server, so that they deploy alongside your Grafana instance(s). +1. Delete the alert rule in Grafana. + + **Note:** + + If you do not delete the alert rule, it will clash with the provisioned alert rule once uploaded. + +Here is an example of a configuration file for creating alert rules. + +```yaml +# config file version +apiVersion: 1 + +# List of rule groups to import or update +groups: + # organization ID, default = 1 + - orgId: 1 + # name of the rule group + name: my_rule_group + # name of the folder the rule group will be stored in + folder: my_first_folder + # interval that the rule group should evaluated at + interval: 60s + # list of rules that are part of the rule group + rules: + # unique identifier for the rule + - uid: my_id_1 + # title of the rule that will be displayed in the UI + title: my_first_rule + # which query should be used for the condition + condition: A + # list of query objects that should be executed on each + # evaluation - should be obtained trough the API + data: + - refId: A + datasourceUid: '-100' + model: + conditions: + - evaluator: + params: + - 3 + type: gt + operator: + type: and + query: + params: + - A + reducer: + type: last + type: query + datasource: + type: __expr__ + uid: '-100' + expression: 1==0 + intervalMs: 1000 + maxDataPoints: 43200 + refId: A + type: math + # UID of a dashboard that the alert rule should be linked to + dashboardUid: my_dashboard + # ID of the panel that the alert rule should be linked to + panelId: 123 + # the state the alert rule will have when no data is returned + # possible values: "NoData", "Alerting", "OK", default = NoData + noDataState: Alerting + # the state the alert rule will have when the query execution + # failed - possible values: "Error", "Alerting", "OK" + # default = Alerting + # for how long should the alert fire before alerting + for: 60s + # > a map of strings to pass around any data + annotations: + some_key: some_value + # a map of strings that can be used to filter and + # route alerts + labels: + team: sre_team_1 +``` + +Here is an example of a configuration file for deleting alert rules. + +```yaml +# config file version +apiVersion: 1 + +# List of alert rule UIDs that should be deleted +deleteRules: + # organization ID, default = 1 + - orgId: 1 + # unique identifier for the rule + uid: my_id_1 +``` + +### Provision contact points + +Create or delete contact points in your Grafana instance(s). + +1. Create a YAML or JSON configuration file. + + Example configuration files can be found below. + +1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). + +Here is an example of a configuration file for creating contact points. + +```yaml +# config file version +apiVersion: 1 + +# List of contact points to import or update +contactPoints: + # organization ID, default = 1 + - orgId: 1 + # name of the contact point + name: cp_1 + receivers: + # unique identifier for the receiver + - uid: first_uid + # type of the receiver + type: prometheus-alertmanager + # settings for the specific receiver type + settings: + url: http://test:9000 +``` + +Here is an example of a configuration file for deleting contact points. + +```yaml +# config file version +apiVersion: 1 + +# List of receivers that should be deleted +deleteContactPoints: + # organization ID, default = 1 + - orgId: 1 + # unique identifier for the receiver + uid: first_uid +``` + +#### Settings + +Here are some examples of settings you can use for the different +contact point types. + +##### Alertmanager + +```yaml +type: prometheus-alertmanager +settings: + # + url: http://localhost:9093 + # + basicAuthUser: abc + # + basicAuthPassword: abc123 +``` + +##### DingDing + +```yaml +type: dingding +settings: + # + url: https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxx + # options: link, actionCard + msgType: link + # + message: | + {{ template "default.message" . }} +``` + +##### Discord + +```yaml +type: discord +settings: + # + url: https://discord/webhook + # + avatar_url: https://my_avatar + # + use_discord_username: Grafana + # + message: | + {{ template "default.message" . }} +``` + +##### E-Mail + +```yaml +type: email +settings: + # + addresses: me@example.com;you@example.com + # + singleEmail: false + # + message: my optional message to include + # + subject: | + {{ template "default.title" . }} +``` + +##### Google Hangouts Chat + +```yaml +type: googlechat +settings: + # + url: https://google/webhook + # + message: | + {{ template "default.message" . }} +``` + +##### Kafka + +```yaml +type: kafka +settings: + # + kafkaRestProxy: http://localhost:8082 + # + kafkaTopic: topic1 +``` + +##### LINE + +```yaml +type: line +settings: + # + token: xxx +``` + +##### Microsoft Teams + +```yaml +type: teams +settings: + # + url: https://ms_teams_url + # + title: | + {{ template "default.title" . }} + # + sectiontitle: '' + # + message: | + {{ template "default.message" . }} +``` + +##### OpsGenie + +```yaml +type: opsgenie +settings: + # + apiKey: xxx + # + apiUrl: https://api.opsgenie.com/v2/alerts + # + message: | + {{ template "default.title" . }} + # + description: some descriptive description + # + autoClose: false + # + overridePriority: false + # options: tags, details, both + sendTagsAs: both +``` + +##### PagerDuty + +```yaml +type: pagerduty +settings: + # + integrationKey: XXX + # options: critical, error, warning, info + severity: critical + # + class: ping failure + # + component: Grafana + # + group: app-stack + # + summary: | + {{ template "default.message" . }} +``` + +##### Pushover + +```yaml +type: pushover +settings: + # + apiToken: XXX + # + userKey: user1,user2 + # + device: device1,device2 + # options (high to low): 2,1,0,-1,-2 + priority: '2' + # + retry: '30' + # + expire: '120' + # + sound: siren + # + okSound: magic + # + message: | + {{ template "default.message" . }} +``` + +##### Slack + +```yaml +type: slack +settings: + # + recipient: alerting-dev + # + token: xxx + # + username: grafana_bot + # + icon_emoji: heart + # + icon_url: https://icon_url + # + mentionUsers: user_1,user_2 + # + mentionGroups: group_1,group_2 + # options: here, channel + mentionChannel: here + # Optionally provide a Slack incoming webhook URL for sending messages, in this case the token isn't necessary + url: https://some_webhook_url + # + endpointUrl: https://custom_url/api/chat.postMessage + # + title: | + {{ template "slack.default.title" . }} + text: | + {{ template "slack.default.text" . }} +``` + +##### Sensu Go + +```yaml +type: sensugo +settings: + # + url: http://sensu-api.local:8080 + # + apikey: xxx + # + entity: default + # + check: default + # + handler: some_handler + # + namespace: default + # + message: | + {{ template "default.message" . }} +``` + +##### Telegram + +```yaml +type: telegram +settings: + # + bottoken: xxx + # + chatid: some_chat_id + # + message: | + {{ template "default.message" . }} +``` + +##### Threema Gateway + +```yaml +type: threema +settings: + # + api_secret: xxx + # + gateway_id: A5K94S9 + # + recipient_id: A9R4KL4S +``` + +##### VictorOps + +```yaml +type: victorops +settings: + # + url: XXX + # options: CRITICAL, WARNING + messageType: CRITICAL +``` + +##### Webhook + +```yaml +type: webhook +settings: + # + url: https://endpoint_url + # options: POST, PUT + httpMethod: POST + # + username: abc + # + password: abc123 + # + authorization_scheme: Bearer + # + authorization_credentials: abc123 + # + maxAlerts: '10' +``` + +##### WeCom + +```yaml +type: wecom +settings: + # + url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx + # + message: | + {{ template "default.message" . }} + # + title: | + {{ template "default.title" . }} +``` + +### Provision notification policies + +Create or reset notification policies in your Grafana instance(s). + +1. Create a YAML or JSON configuration file. + + Example configuration files can be found below. + +2. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). + +Here is an example of a configuration file for creating notification policiies. + +```yaml +# config file version +apiVersion: 1 + +# List of notification policies +policies: + # organization ID, default = 1 + - orgId: 1 + # name of the contact point that should be used for this route + receiver: grafana-default-email + # The labels by which incoming alerts are grouped together. For example, + # multiple alerts coming in for cluster=A and alertname=LatencyHigh would + # be batched into a single group. + # + # To aggregate by all possible labels use the special value '...' as + # the sole label name, for example: + # group_by: ['...'] + # This effectively disables aggregation entirely, passing through all + # alerts as-is. This is unlikely to be what you want, unless you have + # a very low alert volume or your upstream notification system performs + # its own grouping. + group_by: ['...'] + # a list of matchers that an alert has to fulfill to match the node + matchers: + - alertname = Watchdog + - severity =~ "warning|critical" + # Times when the route should be muted. These must match the name of a + # mute time interval. + # Additionally, the root node cannot have any mute times. + # When a route is muted it will not send any notifications, but + # otherwise acts normally (including ending the route-matching process + # if the `continue` option is not set) + mute_time_intervals: + - abc + # How long to initially wait to send a notification for a group + # of alerts. Allows to collect more initial alerts for the same group. + # (Usually ~0s to few minutes), default = 30s + group_wait: 30s + # How long to wait before sending a notification about new alerts that + # are added to a group of alerts for which an initial notification has + # already been sent. (Usually ~5m or more), default = 5m + group_internval: 5m + # How long to wait before sending a notification again if it has already + # been sent successfully for an alert. (Usually ~3h or more), default = 4h + repeat_interval: 4h + # Zero or more child routes + # routes: + # ... +``` + +Here is an example of a configuration file for resetting notification policies. + +```yaml +# config file version +apiVersion: 1 + +# List of orgIds that should be reset to the default policy +resetPolicies: + - 1 +``` + +### Provision templates + +Create or delete templates in your Grafana instance(s). + +1. Create a YAML or JSON configuration file. + + Example configuration files can be found below. + +2. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). + +Here is an example of a configuration file for creating templates. + +```yaml +# config file version +apiVersion: 1 + +# List of templates to import or update +templates: + # organization ID, default = 1 + - orgID: 1 + # name of the template, must be unique + name: my_first_template + # content of the the template + template: Alerting with a custom text template +``` + +Here is an example of a configuration file for deleting templates. + +```yaml +# config file version +apiVersion: 1 + +# List of alert rule UIDs that should be deleted +deleteTemplates: + # organization ID, default = 1 + - orgId: 1 + # name of the template, must be unique + name: my_first_template +``` + +### Provision mute timings + +Create or delete mute timings in your Grafana instance(s). + +1. Create a YAML or JSON configuration file. + + Example configuration files can be found below. + +1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). + +Here is an example of a configuration file for creating mute timings. + +```yaml +# config file version +apiVersion: 1 + +# List of mute time intervals to import or update +muteTimes: + # organization ID, default = 1 + - orgId: 1 + # name of the mute time interval, must be unique + name: mti_1 + # time intervals that should trigger the muting + # refer to https://prometheus.io/docs/alerting/latest/configuration/#time_interval-0 + time_intervals: + - times: + - start_time: '06:00' + end_time: '23:59' + weekdays: ['monday:wednesday', 'saturday', 'sunday'] + months: ['1:3', 'may:august', 'december'] + years: ['2020:2022', '2030'] + days_of_month: ['1:5', '-3:-1'] +``` + +Here is an example of a configuration file for deleting mute timings. + +```yaml +# config file version +apiVersion: 1 + +# List of mute time intervals that should be deleted +deleteMuteTimes: + # organization ID, default = 1 + - orgId: 1 + # name of the mute time interval, must be unique + name: mti_1 +``` + +### File provisioning using Kubernetes + +If you are a Kubernetes user, you can leverage file provisioning using Kubernetes configuration maps. + +1. Create one or more configuration maps as follows. + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: grafana-alerting +data: + provisioning.yaml: | + templates: + - name: my_first_template + template: the content for my template +``` + +2. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: grafana +spec: + replicas: 1 + selector: + matchLabels: + app: grafana + template: + metadata: + name: grafana + labels: + app: grafana + spec: + containers: + - name: grafana + image: grafana/grafana:latest + ports: + - name: grafana + containerPort: 3000 + volumeMounts: + - mountPath: /etc/grafana/provisioning/alerting + name: grafana-alerting + readOnly: false + volumes: + - name: grafana-alerting + configMap: + defaultMode: 420 + name: grafana-alerting +``` + +This eliminates the need for a persistent database to use Grafana Alerting in Kubernetes; all your provisioned resources appear after each restart or re-deployment. diff --git a/docs/sources/developers/http_api/alerting.md b/docs/sources/developers/http_api/alerting.md index 25aaa986687..3022d35fd90 100644 --- a/docs/sources/developers/http_api/alerting.md +++ b/docs/sources/developers/http_api/alerting.md @@ -15,7 +15,11 @@ title: 'Alerting HTTP API ' # Alerting API -> **Note:** This topic is relevant for the [legacy dashboard alerts](https://grafana.com/docs/grafana/v8.5/alerting/old-alerting/) only. +> **Note:** Starting with v9.0, the Alerting HTTP API is deprecated. It will be removed in a future release. + +This topic is relevant for the [legacy dashboard alerts](https://grafana.com/docs/grafana/v8.5/alerting/old-alerting/) only. + +If you are using Grafana Alerting, refer to [Alerting provisioning API](https://grafana.com/docs/grafana/latest/developers/http_api/alerting_provisioning/) You can find Grafana Alerting API specification details [here](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/pkg/services/ngalert/api/tooling/post.json). Also, refer to [Grafana Alerting alerts documentation]({{< relref "../../alerting/" >}}) for details on how to create and manage new alerts.