apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Alerting: improve provisioning docs (#50347)

Browse Source 
* Alerting: improve provisioning docs

* add new provisioning page

* add api docs

* fix formatting and add better descriptions

* fix typo
pull/50624/head
Jean-Philippe Quéméner 4 years ago 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 all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 8
      docs/sources/developers/http_api/_index.md
  2. 1050
      docs/sources/developers/http_api/alerting_provisioning.md
  3. 50
      pkg/services/ngalert/api/tooling/definitions/provisioning_alert_rules.go
  4. 24
      pkg/services/ngalert/api/tooling/definitions/provisioning_contactpoints.go
  5. 149
      pkg/services/ngalert/api/tooling/post.json
  6. 169
      pkg/services/ngalert/api/tooling/spec.json
  7. 2
      pkg/services/ngalert/models/alert_rule.go
  8. 6
      pkg/services/ngalert/provisioning/alert_rules.go

8
docs/sources/developers/http_api/_index.md
Unescape 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
View File

File diff suppressed because it is too large Load Diff

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

@ -54,21 +54,43 @@ type AlertRulePayload struct {
}
type AlertRule struct {
ID int64 `json:"id"`
UID string `json:"uid"`
OrgID int64 `json:"orgID"`
FolderUID string `json:"folderUID"`
RuleGroup string `json:"ruleGroup"`
Title string `json:"title"`
Condition string `json:"condition"`
Data []models.AlertQuery `json:"data"`
Updated time.Time `json:"updated,omitempty"`
NoDataState models.NoDataState `json:"noDataState"`
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"`
For time.Duration `json:"for"`
Annotations map[string]string `json:"annotations,omitempty"`
Labels map[string]string `json:"labels,omitempty"`
Provenance models.Provenance `json:"provenance,omitempty"`
// 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"`
}
func (a *AlertRule) UpstreamModel() models.AlertRule {

24
pkg/services/ngalert/api/tooling/definitions/provisioning_contactpoints.go
Unescape 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.
Name string `json:"name" binding:"required"`
Type string `json:"type" binding:"required"`
Settings *simplejson.Json `json:"settings" binding:"required"`
DisableResolveMessage bool `json:"disableResolveMessage"`
Provenance string `json:"provenance"`
// 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"`
// readonly: true
Provenance string `json:"provenance,omitempty"`
}
const RedactedValue = "[REDACTED]"

149
pkg/services/ngalert/api/tooling/post.json
Unescape 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
Unescape 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
Unescape 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
Unescape 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 {

Write Preview
Loading…
Cancel
Save