From 13cae80fc0203a7b151c0d64a4b1339763572948 Mon Sep 17 00:00:00 2001 From: GRodrigoSM Date: Mon, 25 Nov 2024 00:26:28 +0000 Subject: [PATCH] chore: update alerting swagger spec --- pkg/services/ngalert/api/tooling/api.json | 139 +++++++++++++++---- pkg/services/ngalert/api/tooling/post.json | 151 +++++++++++++++++---- pkg/services/ngalert/api/tooling/spec.json | 151 +++++++++++++++++---- 3 files changed, 360 insertions(+), 81 deletions(-) diff --git a/pkg/services/ngalert/api/tooling/api.json b/pkg/services/ngalert/api/tooling/api.json index 1ea96215152e2..b1dd17176138c 100644 --- a/pkg/services/ngalert/api/tooling/api.json +++ b/pkg/services/ngalert/api/tooling/api.json @@ -225,6 +225,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettingsExport" + }, "panelId": { "format": "int64", "type": "integer" @@ -294,6 +297,91 @@ }, "type": "object" }, + "AlertRuleNotificationSettings": { + "description": "swagger: model", + "properties": { + "group_by": { + "default": [ + "alertname", + "grafana_folder" + ], + "description": "Override the labels by which incoming alerts are grouped together. For example, multiple alerts coming in for\ncluster=A and alertname=LatencyHigh would be batched into a single group. To aggregate by all possible labels\nuse the special value '...' as the sole label name.\nThis effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what\nyou want, unless you have a very low alert volume or your upstream notification system performs its own grouping.\nMust include 'alertname' and 'grafana_folder' if not using '...'.", + "example": [ + "alertname", + "grafana_folder", + "cluster" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "group_interval": { + "description": "Override how long to wait before sending a notification about new alerts that are added to a group of alerts for\nwhich an initial notification has already been sent. (Usually ~5m or more.)", + "example": "5m", + "type": "string" + }, + "group_wait": { + "description": "Override how long to initially wait to send a notification for a group of alerts. Allows to wait for an\ninhibiting alert to arrive or collect more initial alerts for the same group. (Usually ~0s to few minutes.)", + "example": "30s", + "type": "string" + }, + "mute_time_intervals": { + "description": "Override the times when notifications should be muted. These must match the name of a mute time interval defined\nin the alertmanager configuration mute_time_intervals section. When muted it will not send any notifications, but\notherwise acts normally.", + "example": [ + "maintenance" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "receiver": { + "description": "Name of the receiver to send notifications to.", + "example": "grafana-default-email", + "type": "string" + }, + "repeat_interval": { + "description": "Override how long to wait before sending a notification again if it has already been sent successfully for an\nalert. (Usually ~3h or more).\nNote that this parameter is implicitly bound by Alertmanager's `--data.retention` configuration flag.\nNotifications will be resent after either repeat_interval or the data retention period have passed, whichever\noccurs first. `repeat_interval` should not be less than `group_interval`.", + "example": "4h", + "type": "string" + } + }, + "required": [ + "receiver" + ], + "type": "object" + }, + "AlertRuleNotificationSettingsExport": { + "properties": { + "group_by": { + "items": { + "type": "string" + }, + "type": "array" + }, + "group_interval": { + "type": "string" + }, + "group_wait": { + "type": "string" + }, + "mute_time_intervals": { + "items": { + "type": "string" + }, + "type": "array" + }, + "receiver": { + "type": "string" + }, + "repeat_interval": { + "type": "string" + } + }, + "title": "AlertRuleNotificationSettingsExport is the provisioned export of models.NotificationSettings.", + "type": "object" + }, "AlertRuleUpgrade": { "properties": { "sendsTo": { @@ -752,6 +840,9 @@ }, "webhook_url": { "$ref": "#/definitions/SecretURL" + }, + "webhook_url_file": { + "type": "string" } }, "title": "DiscordConfig configures notifications via Discord.", @@ -1560,6 +1651,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "orgId": { "format": "int64", "type": "integer" @@ -2028,6 +2122,9 @@ "send_resolved": { "type": "boolean" }, + "summary": { + "type": "string" + }, "text": { "type": "string" }, @@ -2036,6 +2133,9 @@ }, "webhook_url": { "$ref": "#/definitions/SecretURL" + }, + "webhook_url_file": { + "type": "string" } }, "type": "object" @@ -2531,24 +2631,6 @@ "PermissionDenied": { "type": "object" }, - "Point": { - "description": "If H is not nil, then this is a histogram point and only (T, H) is valid.\nIf H is nil, then only (T, V) is valid.", - "properties": { - "H": { - "$ref": "#/definitions/FloatHistogram" - }, - "T": { - "format": "int64", - "type": "integer" - }, - "V": { - "format": "double", - "type": "number" - } - }, - "title": "Point represents a single data point for a given timestamp.", - "type": "object" - }, "PostableApiAlertingConfig": { "properties": { "global": { @@ -2803,6 +2885,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "title": { "type": "string" }, @@ -2979,6 +3064,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "orgID": { "format": "int64", "type": "integer" @@ -3659,7 +3747,12 @@ "type": "object" }, "Sample": { + "description": "Sample is a single sample belonging to a metric. It represents either a float\nsample or a histogram sample. If H is nil, it is a float sample. Otherwise,\nit is a histogram sample.", "properties": { + "F": { + "format": "double", + "type": "number" + }, "H": { "$ref": "#/definitions/FloatHistogram" }, @@ -3669,13 +3762,8 @@ "T": { "format": "int64", "type": "integer" - }, - "V": { - "format": "double", - "type": "number" } }, - "title": "Sample is a single sample belonging to a metric.", "type": "object" }, "Secret": { @@ -4358,7 +4446,7 @@ "type": "array" }, "Vector": { - "description": "Vector is basically only an alias for model.Samples, but the\ncontract is that in a Vector, all Samples have the same timestamp.", + "description": "Vector is basically only an alias for []Sample, but the contract is that\nin a Vector, all Samples have the same timestamp.", "items": { "$ref": "#/definitions/Sample" }, @@ -4534,6 +4622,7 @@ "type": "object" }, "alertGroups": { + "description": "AlertGroups alert groups", "items": { "$ref": "#/definitions/alertGroup" }, @@ -4693,7 +4782,6 @@ "type": "object" }, "gettableAlerts": { - "description": "GettableAlerts gettable alerts", "items": { "$ref": "#/definitions/gettableAlert" }, @@ -4899,6 +4987,7 @@ "type": "array" }, "postableSilence": { + "description": "PostableSilence postable silence", "properties": { "comment": { "description": "comment", diff --git a/pkg/services/ngalert/api/tooling/post.json b/pkg/services/ngalert/api/tooling/post.json index 0f28aa4f8b50e..b292ac8fdfe60 100644 --- a/pkg/services/ngalert/api/tooling/post.json +++ b/pkg/services/ngalert/api/tooling/post.json @@ -225,6 +225,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettingsExport" + }, "panelId": { "format": "int64", "type": "integer" @@ -294,6 +297,91 @@ }, "type": "object" }, + "AlertRuleNotificationSettings": { + "description": "swagger: model", + "properties": { + "group_by": { + "default": [ + "alertname", + "grafana_folder" + ], + "description": "Override the labels by which incoming alerts are grouped together. For example, multiple alerts coming in for\ncluster=A and alertname=LatencyHigh would be batched into a single group. To aggregate by all possible labels\nuse the special value '...' as the sole label name.\nThis effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what\nyou want, unless you have a very low alert volume or your upstream notification system performs its own grouping.\nMust include 'alertname' and 'grafana_folder' if not using '...'.", + "example": [ + "alertname", + "grafana_folder", + "cluster" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "group_interval": { + "description": "Override how long to wait before sending a notification about new alerts that are added to a group of alerts for\nwhich an initial notification has already been sent. (Usually ~5m or more.)", + "example": "5m", + "type": "string" + }, + "group_wait": { + "description": "Override how long to initially wait to send a notification for a group of alerts. Allows to wait for an\ninhibiting alert to arrive or collect more initial alerts for the same group. (Usually ~0s to few minutes.)", + "example": "30s", + "type": "string" + }, + "mute_time_intervals": { + "description": "Override the times when notifications should be muted. These must match the name of a mute time interval defined\nin the alertmanager configuration mute_time_intervals section. When muted it will not send any notifications, but\notherwise acts normally.", + "example": [ + "maintenance" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "receiver": { + "description": "Name of the receiver to send notifications to.", + "example": "grafana-default-email", + "type": "string" + }, + "repeat_interval": { + "description": "Override how long to wait before sending a notification again if it has already been sent successfully for an\nalert. (Usually ~3h or more).\nNote that this parameter is implicitly bound by Alertmanager's `--data.retention` configuration flag.\nNotifications will be resent after either repeat_interval or the data retention period have passed, whichever\noccurs first. `repeat_interval` should not be less than `group_interval`.", + "example": "4h", + "type": "string" + } + }, + "required": [ + "receiver" + ], + "type": "object" + }, + "AlertRuleNotificationSettingsExport": { + "properties": { + "group_by": { + "items": { + "type": "string" + }, + "type": "array" + }, + "group_interval": { + "type": "string" + }, + "group_wait": { + "type": "string" + }, + "mute_time_intervals": { + "items": { + "type": "string" + }, + "type": "array" + }, + "receiver": { + "type": "string" + }, + "repeat_interval": { + "type": "string" + } + }, + "title": "AlertRuleNotificationSettingsExport is the provisioned export of models.NotificationSettings.", + "type": "object" + }, "AlertRuleUpgrade": { "properties": { "sendsTo": { @@ -752,6 +840,9 @@ }, "webhook_url": { "$ref": "#/definitions/SecretURL" + }, + "webhook_url_file": { + "type": "string" } }, "title": "DiscordConfig configures notifications via Discord.", @@ -1560,6 +1651,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "orgId": { "format": "int64", "type": "integer" @@ -2028,6 +2122,9 @@ "send_resolved": { "type": "boolean" }, + "summary": { + "type": "string" + }, "text": { "type": "string" }, @@ -2036,6 +2133,9 @@ }, "webhook_url": { "$ref": "#/definitions/SecretURL" + }, + "webhook_url_file": { + "type": "string" } }, "type": "object" @@ -2531,24 +2631,6 @@ "PermissionDenied": { "type": "object" }, - "Point": { - "description": "If H is not nil, then this is a histogram point and only (T, H) is valid.\nIf H is nil, then only (T, V) is valid.", - "properties": { - "H": { - "$ref": "#/definitions/FloatHistogram" - }, - "T": { - "format": "int64", - "type": "integer" - }, - "V": { - "format": "double", - "type": "number" - } - }, - "title": "Point represents a single data point for a given timestamp.", - "type": "object" - }, "PostableApiAlertingConfig": { "properties": { "global": { @@ -2803,6 +2885,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "title": { "type": "string" }, @@ -2979,6 +3064,9 @@ ], "type": "string" }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "orgID": { "format": "int64", "type": "integer" @@ -3659,7 +3747,12 @@ "type": "object" }, "Sample": { + "description": "Sample is a single sample belonging to a metric. It represents either a float\nsample or a histogram sample. If H is nil, it is a float sample. Otherwise,\nit is a histogram sample.", "properties": { + "F": { + "format": "double", + "type": "number" + }, "H": { "$ref": "#/definitions/FloatHistogram" }, @@ -3669,13 +3762,8 @@ "T": { "format": "int64", "type": "integer" - }, - "V": { - "format": "double", - "type": "number" } }, - "title": "Sample is a single sample belonging to a metric.", "type": "object" }, "Secret": { @@ -4270,7 +4358,6 @@ "type": "object" }, "URL": { - "description": "The general form represented is:\n\n[scheme:][//[userinfo@]host][/]path[?query][#fragment]\n\nURLs that do not start with a slash after the scheme are interpreted as:\n\nscheme:opaque[?query][#fragment]\n\nNote that the Path field is stored in decoded form: /%47%6f%2f becomes /Go/.\nA consequence is that it is impossible to tell which slashes in the Path were\nslashes in the raw URL and which were %2f. This distinction is rarely important,\nbut when it is, the code should use the EscapedPath method, which preserves\nthe original encoding of Path.\n\nThe RawPath field is an optional field which is only set when the default\nencoding of Path is different from the escaped path. See the EscapedPath method\nfor more details.\n\nURL's String method uses the EscapedPath method to obtain the path.", "properties": { "ForceQuery": { "type": "boolean" @@ -4306,7 +4393,7 @@ "$ref": "#/definitions/Userinfo" } }, - "title": "A URL represents a parsed URL (technically, a URI reference).", + "title": "URL is a custom URL type that allows validation at configuration load time.", "type": "object" }, "UpdateRuleGroupResponse": { @@ -4359,7 +4446,7 @@ "type": "array" }, "Vector": { - "description": "Vector is basically only an alias for model.Samples, but the\ncontract is that in a Vector, all Samples have the same timestamp.", + "description": "Vector is basically only an alias for []Sample, but the contract is that\nin a Vector, all Samples have the same timestamp.", "items": { "$ref": "#/definitions/Sample" }, @@ -4535,7 +4622,6 @@ "type": "object" }, "alertGroups": { - "description": "AlertGroups alert groups", "items": { "$ref": "#/definitions/alertGroup" }, @@ -4696,12 +4782,14 @@ "type": "object" }, "gettableAlerts": { + "description": "GettableAlerts gettable alerts", "items": { "$ref": "#/definitions/gettableAlert" }, "type": "array" }, "gettableSilence": { + "description": "GettableSilence gettable silence", "properties": { "comment": { "description": "comment", @@ -4750,13 +4838,13 @@ "type": "object" }, "gettableSilences": { + "description": "GettableSilences gettable silences", "items": { "$ref": "#/definitions/gettableSilence" }, "type": "array" }, "integration": { - "description": "Integration integration", "properties": { "lastNotifyAttempt": { "description": "A timestamp indicating the last attempt to deliver a notification regardless of the outcome.\nFormat: date-time", @@ -4937,6 +5025,7 @@ "type": "object" }, "receiver": { + "description": "Receiver receiver", "properties": { "active": { "description": "active", @@ -7113,6 +7202,12 @@ "200": { "$ref": "#/responses/GetReceiverResponse" }, + "403": { + "description": "PermissionDenied", + "schema": { + "$ref": "#/definitions/PermissionDenied" + } + }, "404": { "description": "NotFound", "schema": { diff --git a/pkg/services/ngalert/api/tooling/spec.json b/pkg/services/ngalert/api/tooling/spec.json index 9b208a3ea17f8..19f9afbf8320b 100644 --- a/pkg/services/ngalert/api/tooling/spec.json +++ b/pkg/services/ngalert/api/tooling/spec.json @@ -2078,6 +2078,12 @@ "200": { "$ref": "#/responses/GetReceiverResponse" }, + "403": { + "description": "PermissionDenied", + "schema": { + "$ref": "#/definitions/PermissionDenied" + } + }, "404": { "description": "NotFound", "schema": { @@ -3783,6 +3789,9 @@ "OK" ] }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettingsExport" + }, "panelId": { "type": "integer", "format": "int64" @@ -3850,6 +3859,91 @@ } } }, + "AlertRuleNotificationSettings": { + "description": "swagger: model", + "type": "object", + "required": [ + "receiver" + ], + "properties": { + "group_by": { + "description": "Override the labels by which incoming alerts are grouped together. For example, multiple alerts coming in for\ncluster=A and alertname=LatencyHigh would be batched into a single group. To aggregate by all possible labels\nuse the special value '...' as the sole label name.\nThis effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what\nyou want, unless you have a very low alert volume or your upstream notification system performs its own grouping.\nMust include 'alertname' and 'grafana_folder' if not using '...'.", + "type": "array", + "default": [ + "alertname", + "grafana_folder" + ], + "items": { + "type": "string" + }, + "example": [ + "alertname", + "grafana_folder", + "cluster" + ] + }, + "group_interval": { + "description": "Override how long to wait before sending a notification about new alerts that are added to a group of alerts for\nwhich an initial notification has already been sent. (Usually ~5m or more.)", + "type": "string", + "example": "5m" + }, + "group_wait": { + "description": "Override how long to initially wait to send a notification for a group of alerts. Allows to wait for an\ninhibiting alert to arrive or collect more initial alerts for the same group. (Usually ~0s to few minutes.)", + "type": "string", + "example": "30s" + }, + "mute_time_intervals": { + "description": "Override the times when notifications should be muted. These must match the name of a mute time interval defined\nin the alertmanager configuration mute_time_intervals section. When muted it will not send any notifications, but\notherwise acts normally.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "maintenance" + ] + }, + "receiver": { + "description": "Name of the receiver to send notifications to.", + "type": "string", + "example": "grafana-default-email" + }, + "repeat_interval": { + "description": "Override how long to wait before sending a notification again if it has already been sent successfully for an\nalert. (Usually ~3h or more).\nNote that this parameter is implicitly bound by Alertmanager's `--data.retention` configuration flag.\nNotifications will be resent after either repeat_interval or the data retention period have passed, whichever\noccurs first. `repeat_interval` should not be less than `group_interval`.", + "type": "string", + "example": "4h" + } + } + }, + "AlertRuleNotificationSettingsExport": { + "type": "object", + "title": "AlertRuleNotificationSettingsExport is the provisioned export of models.NotificationSettings.", + "properties": { + "group_by": { + "type": "array", + "items": { + "type": "string" + } + }, + "group_interval": { + "type": "string" + }, + "group_wait": { + "type": "string" + }, + "mute_time_intervals": { + "type": "array", + "items": { + "type": "string" + } + }, + "receiver": { + "type": "string" + }, + "repeat_interval": { + "type": "string" + } + } + }, "AlertRuleUpgrade": { "type": "object", "properties": { @@ -4310,6 +4404,9 @@ }, "webhook_url": { "$ref": "#/definitions/SecretURL" + }, + "webhook_url_file": { + "type": "string" } } }, @@ -5120,6 +5217,9 @@ "OK" ] }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "orgId": { "type": "integer", "format": "int64" @@ -5588,6 +5688,9 @@ "send_resolved": { "type": "boolean" }, + "summary": { + "type": "string" + }, "text": { "type": "string" }, @@ -5596,6 +5699,9 @@ }, "webhook_url": { "$ref": "#/definitions/SecretURL" + }, + "webhook_url_file": { + "type": "string" } } }, @@ -6091,24 +6197,6 @@ "PermissionDenied": { "type": "object" }, - "Point": { - "description": "If H is not nil, then this is a histogram point and only (T, H) is valid.\nIf H is nil, then only (T, V) is valid.", - "type": "object", - "title": "Point represents a single data point for a given timestamp.", - "properties": { - "H": { - "$ref": "#/definitions/FloatHistogram" - }, - "T": { - "type": "integer", - "format": "int64" - }, - "V": { - "type": "number", - "format": "double" - } - } - }, "PostableApiAlertingConfig": { "type": "object", "properties": { @@ -6364,6 +6452,9 @@ "OK" ] }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "title": { "type": "string" }, @@ -6551,6 +6642,9 @@ "OK" ] }, + "notification_settings": { + "$ref": "#/definitions/AlertRuleNotificationSettings" + }, "orgID": { "type": "integer", "format": "int64" @@ -7219,9 +7313,13 @@ } }, "Sample": { + "description": "Sample is a single sample belonging to a metric. It represents either a float\nsample or a histogram sample. If H is nil, it is a float sample. Otherwise,\nit is a histogram sample.", "type": "object", - "title": "Sample is a single sample belonging to a metric.", "properties": { + "F": { + "type": "number", + "format": "double" + }, "H": { "$ref": "#/definitions/FloatHistogram" }, @@ -7231,10 +7329,6 @@ "T": { "type": "integer", "format": "int64" - }, - "V": { - "type": "number", - "format": "double" } } }, @@ -7830,9 +7924,8 @@ } }, "URL": { - "description": "The general form represented is:\n\n[scheme:][//[userinfo@]host][/]path[?query][#fragment]\n\nURLs that do not start with a slash after the scheme are interpreted as:\n\nscheme:opaque[?query][#fragment]\n\nNote that the Path field is stored in decoded form: /%47%6f%2f becomes /Go/.\nA consequence is that it is impossible to tell which slashes in the Path were\nslashes in the raw URL and which were %2f. This distinction is rarely important,\nbut when it is, the code should use the EscapedPath method, which preserves\nthe original encoding of Path.\n\nThe RawPath field is an optional field which is only set when the default\nencoding of Path is different from the escaped path. See the EscapedPath method\nfor more details.\n\nURL's String method uses the EscapedPath method to obtain the path.", "type": "object", - "title": "A URL represents a parsed URL (technically, a URI reference).", + "title": "URL is a custom URL type that allows validation at configuration load time.", "properties": { "ForceQuery": { "type": "boolean" @@ -7919,7 +8012,7 @@ } }, "Vector": { - "description": "Vector is basically only an alias for model.Samples, but the\ncontract is that in a Vector, all Samples have the same timestamp.", + "description": "Vector is basically only an alias for []Sample, but the contract is that\nin a Vector, all Samples have the same timestamp.", "type": "array", "items": { "$ref": "#/definitions/Sample" @@ -8096,7 +8189,6 @@ "$ref": "#/definitions/alertGroup" }, "alertGroups": { - "description": "AlertGroups alert groups", "type": "array", "items": { "$ref": "#/definitions/alertGroup" @@ -8259,6 +8351,7 @@ "$ref": "#/definitions/gettableAlert" }, "gettableAlerts": { + "description": "GettableAlerts gettable alerts", "type": "array", "items": { "$ref": "#/definitions/gettableAlert" @@ -8266,6 +8359,7 @@ "$ref": "#/definitions/gettableAlerts" }, "gettableSilence": { + "description": "GettableSilence gettable silence", "type": "object", "required": [ "comment", @@ -8315,6 +8409,7 @@ "$ref": "#/definitions/gettableSilence" }, "gettableSilences": { + "description": "GettableSilences gettable silences", "type": "array", "items": { "$ref": "#/definitions/gettableSilence" @@ -8322,7 +8417,6 @@ "$ref": "#/definitions/gettableSilences" }, "integration": { - "description": "Integration integration", "type": "object", "required": [ "name", @@ -8505,6 +8599,7 @@ "$ref": "#/definitions/postableSilence" }, "receiver": { + "description": "Receiver receiver", "type": "object", "required": [ "active",