root
/
grafana
mirror of https://github.com/grafana/grafana.git
1
0
Fork 0
Code Issues Actions 266 Packages Projects Releases Wiki Activity

Alerting: improve provisioning docs (#50347) 

* Alerting: improve provisioning docs

* add new provisioning page

* add api docs

* fix formatting and add better descriptions

* fix typo
This commit is contained in:
Jean-Philippe Quéméner 2022-06-10 16:25:15 +02:00 committed by GitHub
parent 56a9994a13
commit 862f51216b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 1382 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/sources/developers/http_api/_index.md
View File

@ -22,8 +22,7 @@ dashboards, creating users, and updating data sources.
## HTTP APIs
- [Admin API]({{< relref "admin/" >}})
- [Alerting Notification Channels API]({{< relref "alerting_notification_channels/" >}})
- [Alerting API]({{< relref "alerting/" >}})
- [Alerting Provisioning API]({{< relref "alerting_provisioning/" >}})
- [Annotations API]({{< relref "annotations/" >}})
- [Authentication API]({{< relref "auth/" >}})
- [Dashboard API]({{< relref "dashboard/" >}})
@ -43,6 +42,11 @@ dashboards, creating users, and updating data sources.
- [Team API]({{< relref "team/" >}})
- [User API]({{< relref "user/" >}})
## Deprecated HTTP APIs
- [Alerting Notification Channels API]({{< relref "alerting_notification_channels/" >}})
- [Alerting API]({{< relref "alerting/" >}})
## Grafana Enterprise HTTP APIs
Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:

1050
docs/sources/developers/http_api/alerting_provisioning.md Normal file
View File

File diff suppressed because it is too large Load Diff

22
pkg/services/ngalert/api/tooling/definitions/provisioning_alert_rules.go
View File

@ -56,18 +56,40 @@ type AlertRulePayload struct {
type AlertRule struct {
ID int64 `json:"id"`
UID string `json:"uid"`
// required: true
OrgID int64 `json:"orgID"`
// required: true
// example: project_x
FolderUID string `json:"folderUID"`
// required: true
// minLength: 1
// maxLength: 190
// example: eval_group_1
RuleGroup string `json:"ruleGroup"`
// required: true
// minLength: 1
// maxLength: 190
// example: Always firing
Title string `json:"title"`
// required: true
// example: A
Condition string `json:"condition"`
// required: true
// example: [{"refId":"A","queryType":"","relativeTimeRange":{"from":0,"to":0},"datasourceUid":"-100","model":{"conditions":[{"evaluator":{"params":[0,0],"type":"gt"},"operator":{"type":"and"},"query":{"params":[]},"reducer":{"params":[],"type":"avg"},"type":"query"}],"datasource":{"type":"__expr__","uid":"__expr__"},"expression":"1 == 1","hide":false,"intervalMs":1000,"maxDataPoints":43200,"refId":"A","type":"math"}}]
Data []models.AlertQuery `json:"data"`
// readonly: true
Updated time.Time `json:"updated,omitempty"`
// required: true
NoDataState models.NoDataState `json:"noDataState"`
// required: true
ExecErrState models.ExecutionErrorState `json:"execErrState"`
// required: true
For time.Duration `json:"for"`
// example: {"runbook_url": "https://supercoolrunbook.com/page/13"}
Annotations map[string]string `json:"annotations,omitempty"`
// example: {"team": "sre-team-1"}
Labels map[string]string `json:"labels,omitempty"`
// readonly: true
Provenance models.Provenance `json:"provenance,omitempty"`
}

16
pkg/services/ngalert/api/tooling/definitions/provisioning_contactpoints.go
View File

@ -50,7 +50,7 @@ import (
// swagger:parameters RoutePutContactpoint RouteDeleteContactpoints
type ContactPointUIDReference struct {
// ContactPointUID should be the contact point UID identifier
// UID should be the contact point unique identifier
// in:path
UID string
}
@ -64,16 +64,24 @@ type ContactPointPayload struct {
// EmbeddedContactPoint is the contact point type that is used
// by grafanas embedded alertmanager implementation.
type EmbeddedContactPoint struct {
// UID is the unique identifier of the contact point. This will be
// automatically set be the Grafana.
// UID is the unique identifier of the contact point. The UID can be
// set by the user.
// example: my_external_reference
UID string `json:"uid"`
// Name is used as grouping key in the UI. Contact points with the
// same name will be grouped in the UI.
// example: webhook_1
Name string `json:"name" binding:"required"`
// required: true
// example: webhook
// enum: alertmanager, dingding, discord, email, googlechat, kafka, line, opsgenie, pagerduty, pushover, sensugo, slack, teams, telegram, threema, victorops, webhook, wecom
Type string `json:"type" binding:"required"`
// required: true
Settings *simplejson.Json `json:"settings" binding:"required"`
// example: false
DisableResolveMessage bool `json:"disableResolveMessage"`
Provenance string `json:"provenance"`
// readonly: true
Provenance string `json:"provenance,omitempty"`
}
const RedactedValue = "[REDACTED]"

149
pkg/services/ngalert/api/tooling/post.json
View File

@ -200,14 +200,63 @@
"additionalProperties": {
"type": "string"
},
"example": {
"runbook_url": "https://supercoolrunbook.com/page/13"
},
"type": "object",
"x-go-name": "Annotations"
},
"condition": {
"example": "A",
"type": "string",
"x-go-name": "Condition"
},
"data": {
"example": [
{
"datasourceUid": "-100",
"model": {
"conditions": [
{
"evaluator": {
"params": [
0,
0
],
"type": "gt"
},
"operator": {
"type": "and"
},
"query": {
"params": []
},
"reducer": {
"params": [],
"type": "avg"
},
"type": "query"
}
],
"datasource": {
"type": "__expr__",
"uid": "__expr__"
},
"expression": "1 == 1",
"hide": false,
"intervalMs": 1000,
"maxDataPoints": 43200,
"refId": "A",
"type": "math"
},
"queryType": "",
"refId": "A",
"relativeTimeRange": {
"from": 0,
"to": 0
}
}
],
"items": {
"$ref": "#/definitions/AlertQuery"
},
@ -215,9 +264,18 @@
"x-go-name": "Data"
},
"execErrState": {
"$ref": "#/definitions/ExecutionErrorState"
"description": "\nAlerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
"enum": [
"Alerting",
"Error",
"OK"
],
"type": "string",
"x-go-enum-desc": "Alerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
"x-go-name": "ExecErrState"
},
"folderUID": {
"example": "project_x",
"type": "string",
"x-go-name": "FolderUID"
},
@ -233,11 +291,22 @@
"additionalProperties": {
"type": "string"
},
"example": {
"team": "sre-team-1"
},
"type": "object",
"x-go-name": "Labels"
},
"noDataState": {
"$ref": "#/definitions/NoDataState"
"description": "\nAlerting Alerting\nNoData NoData\nOK OK",
"enum": [
"Alerting",
"NoData",
"OK"
],
"type": "string",
"x-go-enum-desc": "Alerting Alerting\nNoData NoData\nOK OK",
"x-go-name": "NoDataState"
},
"orgID": {
"format": "int64",
@ -248,10 +317,16 @@
"$ref": "#/definitions/Provenance"
},
"ruleGroup": {
"example": "eval_group_1",
"maxLength": 190,
"minLength": 1,
"type": "string",
"x-go-name": "RuleGroup"
},
"title": {
"example": "Always firing",
"maxLength": 190,
"minLength": 1,
"type": "string",
"x-go-name": "Title"
},
@ -261,10 +336,22 @@
},
"updated": {
"format": "date-time",
"readOnly": true,
"type": "string",
"x-go-name": "Updated"
}
},
"required": [
"orgID",
"folderUID",
"ruleGroup",
"title",
"condition",
"data",
"noDataState",
"execErrState",
"for"
],
"type": "object",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
},
@ -673,15 +760,18 @@
"description": "EmbeddedContactPoint is the contact point type that is used\nby grafanas embedded alertmanager implementation.",
"properties": {
"disableResolveMessage": {
"example": false,
"type": "boolean",
"x-go-name": "DisableResolveMessage"
},
"name": {
"description": "Name is used as grouping key in the UI. Contact points with the\nsame name will be grouped in the UI.",
"example": "webhook_1",
"type": "string",
"x-go-name": "Name"
},
"provenance": {
"readOnly": true,
"type": "string",
"x-go-name": "Provenance"
},
@ -689,15 +779,41 @@
"$ref": "#/definitions/Json"
},
"type": {
"enum": [
"alertmanager",
" dingding",
" discord",
" email",
" googlechat",
" kafka",
" line",
" opsgenie",
" pagerduty",
" pushover",
" sensugo",
" slack",
" teams",
" telegram",
" threema",
" victorops",
" webhook",
" wecom"
],
"example": "webhook",
"type": "string",
"x-go-name": "Type"
},
"uid": {
"description": "UID is the unique identifier of the contact point. This will be\nautomatically set be the Grafana.",
"description": "UID is the unique identifier of the contact point. The UID can be\nset by the user.",
"example": "my_external_reference",
"type": "string",
"x-go-name": "UID"
}
},
"required": [
"type",
"settings"
],
"type": "object",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
},
@ -748,10 +864,6 @@
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
},
"EvalQueriesResponse": {},
"ExecutionErrorState": {
"type": "string",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
},
"ExtendedReceiver": {
"properties": {
"email_configs": {
@ -1552,10 +1664,6 @@
"type": "object",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
},
"NoDataState": {
"type": "string",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
},
"NotFound": {
"type": "object",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@ -3255,7 +3363,6 @@
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
},
"alertGroup": {
"description": "AlertGroup alert group",
"properties": {
"alerts": {
"description": "alerts",
@ -3277,7 +3384,9 @@
"labels",
"receiver"
],
"type": "object"
"type": "object",
"x-go-name": "AlertGroup",
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
},
"alertGroups": {
"description": "AlertGroups alert groups",
@ -3530,12 +3639,11 @@
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
},
"gettableSilences": {
"description": "GettableSilences gettable silences",
"items": {
"$ref": "#/definitions/gettableSilence"
},
"type": "array",
"x-go-name": "GettableSilences",
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
"type": "array"
},
"labelSet": {
"additionalProperties": {
@ -3664,6 +3772,7 @@
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
},
"postableSilence": {
"description": "PostableSilence postable silence",
"properties": {
"comment": {
"description": "comment",
@ -3703,9 +3812,7 @@
"matchers",
"startsAt"
],
"type": "object",
"x-go-name": "PostableSilence",
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
"type": "object"
},
"receiver": {
"properties": {
@ -5676,7 +5783,7 @@
"operationId": "RouteDeleteContactpoints",
"parameters": [
{
"description": "ContactPointUID should be the contact point UID identifier",
"description": "UID should be the contact point unique identifier",
"in": "path",
"name": "UID",
"required": true,
@ -5709,7 +5816,7 @@
"operationId": "RoutePutContactpoint",
"parameters": [
{
"description": "ContactPointUID should be the contact point UID identifier",
"description": "UID should be the contact point unique identifier",
"in": "path",
"name": "UID",
"required": true,

169
pkg/services/ngalert/api/tooling/spec.json
View File

@ -1871,7 +1871,7 @@
"parameters": [
{
"type": "string",
"description": "ContactPointUID should be the contact point UID identifier",
"description": "UID should be the contact point unique identifier",
"name": "UID",
"in": "path",
"required": true
@ -1912,7 +1912,7 @@
"parameters": [
{
"type": "string",
"description": "ContactPointUID should be the contact point UID identifier",
"description": "UID should be the contact point unique identifier",
"name": "UID",
"in": "path",
"required": true
@ -2591,31 +2591,100 @@
},
"AlertRule": {
"type": "object",
"required": [
"orgID",
"folderUID",
"ruleGroup",
"title",
"condition",
"data",
"noDataState",
"execErrState",
"for"
],
"properties": {
"annotations": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"x-go-name": "Annotations"
"x-go-name": "Annotations",
"example": {
"runbook_url": "https://supercoolrunbook.com/page/13"
}
},
"condition": {
"type": "string",
"x-go-name": "Condition"
"x-go-name": "Condition",
"example": "A"
},
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/AlertQuery"
},
"x-go-name": "Data"
"x-go-name": "Data",
"example": [
{
"datasourceUid": "-100",
"model": {
"conditions": [
{
"evaluator": {
"params": [
0,
0
],
"type": "gt"
},
"operator": {
"type": "and"
},
"query": {
"params": []
},
"reducer": {
"params": [],
"type": "avg"
},
"type": "query"
}
],
"datasource": {
"type": "__expr__",
"uid": "__expr__"
},
"expression": "1 == 1",
"hide": false,
"intervalMs": 1000,
"maxDataPoints": 43200,
"refId": "A",
"type": "math"
},
"queryType": "",
"refId": "A",
"relativeTimeRange": {
"from": 0,
"to": 0
}
}
]
},
"execErrState": {
"$ref": "#/definitions/ExecutionErrorState"
"description": "\nAlerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
"type": "string",
"enum": [
"Alerting",
"Error",
"OK"
],
"x-go-enum-desc": "Alerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
"x-go-name": "ExecErrState"
},
"folderUID": {
"type": "string",
"x-go-name": "FolderUID"
"x-go-name": "FolderUID",
"example": "project_x"
},
"for": {
"$ref": "#/definitions/Duration"
@ -2630,10 +2699,21 @@
"additionalProperties": {
"type": "string"
},
"x-go-name": "Labels"
"x-go-name": "Labels",
"example": {
"team": "sre-team-1"
}
},
"noDataState": {
"$ref": "#/definitions/NoDataState"
"description": "\nAlerting Alerting\nNoData NoData\nOK OK",
"type": "string",
"enum": [
"Alerting",
"NoData",
"OK"
],
"x-go-enum-desc": "Alerting Alerting\nNoData NoData\nOK OK",
"x-go-name": "NoDataState"
},
"orgID": {
"type": "integer",
@ -2645,11 +2725,17 @@
},
"ruleGroup": {
"type": "string",
"x-go-name": "RuleGroup"
"maxLength": 190,
"minLength": 1,
"x-go-name": "RuleGroup",
"example": "eval_group_1"
},
"title": {
"type": "string",
"x-go-name": "Title"
"maxLength": 190,
"minLength": 1,
"x-go-name": "Title",
"example": "Always firing"
},
"uid": {
"type": "string",
@ -2658,7 +2744,8 @@
"updated": {
"type": "string",
"format": "date-time",
"x-go-name": "Updated"
"x-go-name": "Updated",
"readOnly": true
}
},
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@ -3068,31 +3155,60 @@
"EmbeddedContactPoint": {
"description": "EmbeddedContactPoint is the contact point type that is used\nby grafanas embedded alertmanager implementation.",
"type": "object",
"required": [
"type",
"settings"
],
"properties": {
"disableResolveMessage": {
"type": "boolean",
"x-go-name": "DisableResolveMessage"
"x-go-name": "DisableResolveMessage",
"example": false
},
"name": {
"description": "Name is used as grouping key in the UI. Contact points with the\nsame name will be grouped in the UI.",
"type": "string",
"x-go-name": "Name"
"x-go-name": "Name",
"example": "webhook_1"
},
"provenance": {
"type": "string",
"x-go-name": "Provenance"
"x-go-name": "Provenance",
"readOnly": true
},
"settings": {
"$ref": "#/definitions/Json"
},
"type": {
"type": "string",
"x-go-name": "Type"
"enum": [
"alertmanager",
" dingding",
" discord",
" email",
" googlechat",
" kafka",
" line",
" opsgenie",
" pagerduty",
" pushover",
" sensugo",
" slack",
" teams",
" telegram",
" threema",
" victorops",
" webhook",
" wecom"
],
"x-go-name": "Type",
"example": "webhook"
},
"uid": {
"description": "UID is the unique identifier of the contact point. This will be\nautomatically set be the Grafana.",
"description": "UID is the unique identifier of the contact point. The UID can be\nset by the user.",
"type": "string",
"x-go-name": "UID"
"x-go-name": "UID",
"example": "my_external_reference"
}
},
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@ -3146,10 +3262,6 @@
"EvalQueriesResponse": {
"$ref": "#/definitions/EvalQueriesResponse"
},
"ExecutionErrorState": {
"type": "string",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
},
"ExtendedReceiver": {
"type": "object",
"properties": {
@ -3951,10 +4063,6 @@
},
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
},
"NoDataState": {
"type": "string",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
},
"NotFound": {
"type": "object",
"x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@ -5654,7 +5762,6 @@
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
},
"alertGroup": {
"description": "AlertGroup alert group",
"type": "object",
"required": [
"alerts",
@ -5677,6 +5784,8 @@
"$ref": "#/definitions/receiver"
}
},
"x-go-name": "AlertGroup",
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
"$ref": "#/definitions/alertGroup"
},
"alertGroups": {
@ -5934,12 +6043,11 @@
"$ref": "#/definitions/gettableSilence"
},
"gettableSilences": {
"description": "GettableSilences gettable silences",
"type": "array",
"items": {
"$ref": "#/definitions/gettableSilence"
},
"x-go-name": "GettableSilences",
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
"$ref": "#/definitions/gettableSilences"
},
"labelSet": {
@ -6069,6 +6177,7 @@
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
},
"postableSilence": {
"description": "PostableSilence postable silence",
"type": "object",
"required": [
"comment",
@ -6109,8 +6218,6 @@
"x-go-name": "StartsAt"
}
},
"x-go-name": "PostableSilence",
"x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
"$ref": "#/definitions/postableSilence"
},
"receiver": {

2
pkg/services/ngalert/models/alert_rule.go
View File

@ -24,6 +24,7 @@ var (
ErrAlertRuleUniqueConstraintViolation = errors.New("a conflicting alert rule is found: rule title under the same organisation and folder should be unique")
)
// swagger:enum NoDataState
type NoDataState string
func (noDataState NoDataState) String() string {
@ -49,6 +50,7 @@ const (
OK NoDataState = "OK"
)
// swagger:enum ExecutionErrorState
type ExecutionErrorState string
func (executionErrorState ExecutionErrorState) String() string {

6
pkg/services/ngalert/provisioning/alert_rules.go
View File

@ -53,6 +53,9 @@ func (service *AlertRuleService) GetAlertRule(ctx context.Context, orgID int64,
return *query.Result, provenance, nil
}
// CreateAlertRule creates a new alert rule. This function will ignore any
// interval that is set in the rule struct and use the already existing group
// interval or the default one.
func (service *AlertRuleService) CreateAlertRule(ctx context.Context, rule models.AlertRule, provenance models.Provenance) (models.AlertRule, error) {
if rule.UID == "" {
rule.UID = util.GenerateShortUID()
@ -117,6 +120,9 @@ func (service *AlertRuleService) UpdateRuleGroup(ctx context.Context, orgID int6
})
}
// CreateAlertRule creates a new alert rule. This function will ignore any
// interval that is set in the rule struct and fetch the current group interval
// from database.
func (service *AlertRuleService) UpdateAlertRule(ctx context.Context, rule models.AlertRule, provenance models.Provenance) (models.AlertRule, error) {
storedRule, storedProvenance, err := service.GetAlertRule(ctx, rule.OrgID, rule.UID)
if err != nil {