组合监控器

关于组合监控器

告警插件的基本监控器类型设计用于定义单一触发类型。例如，按文档监控器可以根据查询与文档的匹配来触发告警，而按桶监控器可以根据针对数据源中聚合值的查询来触发告警。组合监控器将多个监控器按顺序组合，以基于多个标准分析数据源，然后使用它们各自的告警生成一个链式告警。这允许您获取关于数据源的更细粒度信息，并且无需手动协调各个独立监控器的调度。

组合监控器在以下方面消除了基本监控器的限制：

  • 组合监控器使您能够通过结合多种监控器生成的触发器来创建复杂查询。

  • 它们能够定义规则和查询的流水线，作为单次执行运行。

  • 它们向用户交付单一告警，而不是工作流中各个监控器的多个告警。

  • 它们通过按顺序运行多个监控器和多种类型的监控器，提供对给定数据源更完整的视图，创建更聚焦的结果并减少结果中的噪音。

关键术语

下表中的关键术语描述了组合监控器的基本概念。有关所有类型监控器共通的更多术语，请参阅 告警 部分的关键术语。

术语 定义
Composite monitor 组合监控器是一种支持在顺序工作流中执行多个监控器的监控器类型。它支持配置触发器以创建链式告警。
Delegate monitor 委托监控器根据其在组合监控器定义中的顺序依次执行。当委托监控器的触发条件满足时，它会生成一个审计告警。此审计告警随后成为组合监控器触发器的条件。组合监控器支持按查询、按桶和按文档监控器作为委托监控器。
workflow ID 工作流 ID 为所有委托监控器的整个工作流提供标识符。它与组合监控器的监控器 ID 同义。
Chained alert 当委托监控器生成审计告警时，组合监控器触发器会生成链式告警。链式告警触发条件支持使用逻辑运算符 AND、OR 和 NOT，因此您可以将多个函数组合到单个表达式中。
Audit alert 委托监控器在审计状态下生成告警。用户不会收到每个单独的审计告警通知，也不需要确认它们。审计告警用于评估组合监控器中的链式告警触发条件。
Execution 在组合监控器配置中定义的所有委托监控器的单次运行序列。

基本工作流

您通过在工作流中组合各个监控器来创建组合监控器，该工作流按照定义的顺序执行每个监控器。当来自委托监控器的各个审计告警满足组合监控器的触发条件时，组合监控器会生成自己的链式告警。考虑以下事件序列，以了解配置了两个委托监控器的简单组合监控器如何执行其工作流。在此示例中，当第一个监控器和第二个监控器都生成告警时，组合监控器的触发条件得到满足。

  1. 组合监控器开始执行并将其委托给第一个监控器。第一个监控器的触发条件得到满足，并生成审计告警。

  2. 组合监控器然后将执行委托给第二个监控器。第二个监控器的触发条件也得到满足，并生成其自己的审计告警。

  3. 由于组合监控器的触发条件要求第一个和第二个监控器都生成审计告警，组合监控器随后触发链式告警。

  4. 如果在组合监控器的定义中配置了通知，用户将收到关于链式告警的通知。但是，他们不会收到由两个委托监控器生成的各个审计告警。

在这个简单示例中，第一个监控器可以是按文档监控器，配置为使用三个不同查询分析数据源，而第二个监控器可以是按桶监控器，按客户端 IP 聚合数据。通过结合每个委托监控器的要求，组合监控器聚焦了决定是否生成告警的标准。这可以提高告警的意义，同时去除提供非确定性价值的无关告警。

使用 API 管理组合监控器

您可以使用 UDB-SX REST API 或 UDB-SX Dashboards 来管理组合监控器。本节描述了组合监控器的 API 功能。

创建组合监控器

此 API 允许您创建组合监控器。

POST _plugins/_alerting/workflows

请求体字段

字段 类型 描述
schedule 对象 决定执行运行频率的计划。
schedule.period.interval 数字 接受数值以设置执行运行的频率。
schedule.period.unit 对象 间隔的时间单位：SECONDS、MINUTES、HOURS、DAYS。
inputs 对象 接受输入以定义委托监控器，这些输入指定委托监控器及其在执行序列中的顺序。
inputs.composite_input.sequence.delegates 对象 构成组合监控器的各个监控器的设置。
inputs.composite_input.sequence.delegates.order 数字 指定监控器在执行中的运行顺序。
inputs.composite_input.sequence.delegates.monitor_id 字符串 监控器的唯一标识符。
enabled_time 数字 监控器启用的时间。以纪元时间表示。
enabled 布尔值 决定组合监控器是否启用的设置。设置为 true 启用组合监控器。默认为 true。
workflow_type 字符串 对于组合监控器，设置为 composite。
triggers 对象 各个告警触发器的详细信息。
triggers.chained_alert_trigger 对象 每个单独告警触发器的详细信息。每个监控器的告警触发器都需要其配置的设置。
triggers.chained_alert_trigger.id 字符串 告警触发器的唯一标识符。
triggers.chained_alert_trigger.name 字符串 告警触发器的名称。
triggers.chained_alert_trigger.severity 数字 告警严重性。1 = 最高；2 = 高；3 = 中；4 = 低；5 = 最低。
triggers.chained_alert_trigger.condition.script 对象 决定触发告警条件的脚本详细信息。
triggers.chained_alert_trigger.condition.script.source 字符串 定义触发告警条件的 Painless 脚本。
triggers.chained_alert_trigger.condition.script.lang 字符串 输入 painless 表示 Painless 脚本语言。
actions 对象 提供用于配置告警通知的字段。

示例请求

POST _plugins/_alerting/workflows
{
	"last_update_time": 1679468231835,
	"owner": "alerting",
	"type": "workflow",
	"schedule": {
		"period": {
			"interval": 1,
			"unit": "MINUTES"
		}
	},
	"inputs": [{
		"composite_input": {
			"sequence": {
				"delegates": [{
						"order": 1,
						"monitor_id": "AfQQMZwByb2pzGJGFlHr"
					},
					{
						"order": 2,
						"monitor_id": "HfQRMZwByb2pzGJGkFEv"
					}
				]
			}
		}
	}],
	"enabled_time": 1679468231835,
	"enabled": true,
	"workflow_type": "composite",
	"name": "scale_up",
	"triggers": [{
			"chained_alert_trigger": {
				"id": "m1ANDm2",
				"name": "and_trigger",
				"severity": "1",
				"condition": {
					"script": {
						"source": "(monitor[id=AfQQMZwByb2pzGJGFlHr] && monitor[id=HfQRMZwByb2pzGJGkFEv])",
						"lang": "painless"
					}
				},
				"actions": [{
					"name": "test-action",
					"destination_id": "ld7912sBlQ5JUWWFThoW",
					"message_template": {
						"source": "This is my message body."
					},
					"throttle_enabled": true,
					"throttle": {
						"value": 27,
						"unit": "MINUTES"
					},
					"subject_template": {
						"source": "TheSubject"
					}
				}]
			}
		},
		{
			"chained_alert_trigger": {
				"id": "m1ORm3",
				"name": "or_trigger",
				"severity": "1",
				"condition": {
					"script": {
						"source": "(monitor[id=AfQQMZwByb2pzGJGFlHr] || monitor[id=HfQRMZwByb2pzGJGkFEv])",
						"lang": "painless"
					}
				},
				"actions": [{
					"name": "test-action2",
					"destination_id": "ld7913sBlQ5JUWWFThoW",
					"message_template": {
						"source": "This is my message body."
					},
					"throttle_enabled": true,
					"throttle": {
						"value": 27,
						"unit": "MINUTES"
					},
					"subject_template": {
						"source": "TheSubject"
					}
				}]
			}
		}
	]
}

使用 Painless 脚本语言定义链式告警触发条件

组合监控器配置使用 Painless 脚本语言来定义生成链式告警的条件。条件应用于组合监控器的每次执行。您在请求的 triggers.chained_alert_triggers.condition.script.source 字段中定义告警触发条件。使用 Painless 语法，您可以将逻辑应用于监控器之间的链接，使用基本布尔运算符 AND、OR、NOT 和优先级：

  • AND = &&

  • OR = ||

  • NOT = !

  • 优先级 = ()

参阅以下示例以了解每个在监控器定义中如何使用。

  • 示例 1

    monitor[id=1] && monitor[id=2]

    当监控器 #1 和监控器 #2 都生成告警时，以下委托监控器的条件将触发组合监控器产生链式告警。

  • 示例 2

    monitor[id=1] || !monitor[id=2]

    当监控器 #1 生成告警或监控器 #2 未生成告警时，以下条件将触发组合监控器产生链式告警。

  • 示例 3

    monitor[id=1] && (monitor[id=2] || monitor[id=3])

    当监控器 #1 生成告警且监控器 #2 或监控器 #3 生成告警时，以下条件将触发组合监控器产生链式告警。

Painless 脚本中监控器 ID 的顺序不定义监控器的执行顺序。监控器执行顺序在请求的 inputs.composite_input.sequence.delegates.order 字段中定义。

获取组合监控器

此 API 检索指定监控器的信息。

GET _plugins/_alerting/workflows/<workflow_id>

路径参数

字段 类型 描述
workflow_id 字符串 组合监控器的工作流 ID。

更新组合监控器

此 API 更新组合监控器的详细信息。有关请求字段的描述，请参阅创建组合监控器。

示例请求

PUT _plugins/_alerting/workflows/<workflow_id>
{
    "owner": "security_analytics",
    "type": "workflow",
    "schedule": {
        "period": {
        "interval": 1,
        "unit": "MINUTES"
        }
    },
    "inputs": [
        {
            "composite_input": {
                "sequence": {
                    "delegates": [
                        {
                            "order": 1,
                            "monitor_id": "grsbCIcBvEHfkjWFeCqb"
                        },
                        {
                            "order": 2,
                            "monitor_id": "agasbCIcBvEHfkjWFeCqa"
                        }
                    ]
                }
            }
        }
    ],
    "enabled_time": 1679468231835,
    "enabled": true,
    "workflow_type": "composite",
    "name": "NTxdwApKbv"
}

删除组合监控器

DELETE _plugins/_alerting/workflows/<workflow_id>

执行组合监控器

此 API 开始组合监控器的工作流执行：

POST /_plugins/_alerting/workflows/<workflow_id>/_execute

示例响应

{
    "execution_id": "I0GXeIgBYKBG2nHoiHCL_2023-06-01T20:18:48.511884_a9c1d055-9b70-49c2-b32a-716cff1f562e",
    "workflow_name": "scale_up",
    "workflow_id": "I0GXeIgBYKBG2nHoiHCL",
    "trigger_results": {
        "m1ANDm2": {
            "name": "jnkjn",
            "triggered": true,
            "action_results": {},
            "error": null
        },
        "m1ORm2": {
            "name": "jnkjn",
            "triggered": true,
            "action_results": {},
            "error": null
        }
    },
    "monitor_run_results": [{
            "monitor_name": "test triggers",
            "period_start": 1685650668501,
            "period_end": 1685650728501,
            "error": null,
            "input_results": {
                "results": [{
                    "bhjh": [
                        "OkGceIgBYKBG2nHoyHAn|test1",
                        "O0GceIgBYKBG2nHozHCW|test1"
                    ],
                    "nkjkj": [
                        "OkGceIgBYKBG2nHoyHAn|test1",
                        "O0GceIgBYKBG2nHozHCW|test1"
                    ],
                    "jknkjn": [
                        "OkGceIgBYKBG2nHoyHAn|test1",
                        "O0GceIgBYKBG2nHozHCW|test1"
                    ]
                }],
                "error": null
            },
            "trigger_results": {
                "NC3Dd4cBCDCIfBYtViLI": {
                    "name": "njkkj",
                    "triggeredDocs": [
                        "OkGceIgBYKBG2nHoyHAn|test1",
                        "O0GceIgBYKBG2nHozHCW|test1"
                    ],
                    "action_results": {},
                    "error": null
                }
            }
        },
        {
            "monitor_name": "test triggers 2",
            "period_start": 1685650668501,
            "period_end": 1685650728501,
            "error": null,
            "input_results": {
                "results": [{
                    "bhjh": [
                        "PEGceIgBYKBG2nHo1HCw|test",
                        "PUGceIgBYKBG2nHo3HA8|test"
                    ],
                    "nkjkj": [
                        "PEGceIgBYKBG2nHo1HCw|test",
                        "PUGceIgBYKBG2nHo3HA8|test"
                    ],
                    "jknkjn": [
                        "PEGceIgBYKBG2nHo1HCw|test",
                        "PUGceIgBYKBG2nHo3HA8|test"
                    ]
                }],
                "error": null
            },
            "trigger_results": {
                "NC3Dd4cBCDCIfBYtViLI": {
                    "name": "njkkj",
                    "triggeredDocs": [
                        "PEGceIgBYKBG2nHo1HCw|test",
                        "PUGceIgBYKBG2nHo3HA8|test"
                    ],
                    "action_results": {},
                    "error": null
                }
            }
        }
    ],
    "execution_start_time": "2023-06-01T20:18:48.511874Z",
    "execution_end_time": "2023-06-01T20:18:53.682405Z",
    "error": null
}

获取链式告警

此 API 返回在组合监控器工作流中生成的链式告警数组：

GET /_plugins/_alerting/workflows/alerts?workflowIds=<workflow_ids>&getAssociatedAlerts=true

查询参数

字段 类型 必需 描述
workflowIds 数组 否 使用此参数时，返回指定工作流创建的告警。
getAssociatedAlerts 布尔值 否 当为 true 时，响应返回组合监控器用于创建链式告警的审计告警。默认为 false。

示例响应

{
    "alerts": [
        {
            "id": "PbQoZokBfd2ci_FqMGi6",
            "version": 1,
            "monitor_id": "",
            "workflow_id": "G7QoZokBfd2ci_FqD2iZ",
            "workflow_name": "scale_up",
            "associated_alert_ids": [
                "4e8256c5-529a-484c-bf7b-d3980c03e9a4",
                "513a8cb3-44bc-4eee-8aac-131be10b399e"
            ],
            "schema_version": -1,
            "monitor_version": -1,
            "monitor_name": "",
            "execution_id": "G7QoZokBfd2ci_FqD2iZ_2023-07-17T23:20:55.244970_edd977d2-c02b-4cbe-8a79-2aa7991c4191",
            "trigger_id": "m1ANDm2",
            "trigger_name": "jnkjn",
            "finding_ids": [],
            "related_doc_ids": [],
            "state": "ACTIVE",
            "error_message": null,
            "alert_history": [],
            "severity": "1",
            "action_execution_results": [],
            "start_time": 1689636057269,
            "last_notification_time": 1689636057270,
            "end_time": null,
            "acknowledged_time": null
        },
        {
            "id": "PrQoZokBfd2ci_FqMGj8",
            "version": 1,
            "monitor_id": "",
            "workflow_id": "G7QoZokBfd2ci_FqD2iZ",
            "workflow_name": "scale_up",
            "associated_alert_ids": [
                "4e8256c5-529a-484c-bf7b-d3980c03e9a4",
                "513a8cb3-44bc-4eee-8aac-131be10b399e"
            ],
            "schema_version": -1,
            "monitor_version": -1,
            "monitor_name": "",
            "execution_id": "G7QoZokBfd2ci_FqD2iZ_2023-07-17T23:20:55.244970_edd977d2-c02b-4cbe-8a79-2aa7991c4191",
            "trigger_id": "m1ORm2",
            "trigger_name": "jnkjn",
            "finding_ids": [],
            "related_doc_ids": [],
            "state": "ACTIVE",
            "error_message": null,
            "alert_history": [],
            "severity": "1",
            "action_execution_results": [],
            "start_time": 1689636057340,
            "last_notification_time": 1689636057340,
            "end_time": null,
            "acknowledged_time": null
        }
    ],
    "associatedAlerts": [
        {
            "id": "4e8256c5-529a-484c-bf7b-d3980c03e9a4",
            "version": -1,
            "monitor_id": "DrQoZokBfd2ci_FqCWh8",
            "workflow_id": "G7QoZokBfd2ci_FqD2iZ",
            "workflow_name": "",
            "associated_alert_ids": [],
            "schema_version": 5,
            "monitor_version": 1,
            "monitor_name": "test triggers",
            "execution_id": "G7QoZokBfd2ci_FqD2iZ_2023-07-17T23:20:55.244970_edd977d2-c02b-4cbe-8a79-2aa7991c4191",
            "trigger_id": "NC3Dd4cBCDCIfBYtViLI",
            "trigger_name": "njkkj",
            "finding_ids": [
                "277afca7-d5aa-46ed-8023-5449ece65d36"
            ],
            "related_doc_ids": [
                "H7QoZokBfd2ci_FqFmii|test1"
            ],
            "state": "AUDIT",
            "error_message": null,
            "alert_history": [],
            "severity": "1",
            "action_execution_results": [],
            "start_time": 1689636056410,
            "last_notification_time": 1689636056410,
            "end_time": null,
            "acknowledged_time": null
        },
        {
            "id": "513a8cb3-44bc-4eee-8aac-131be10b399e",
            "version": -1,
            "monitor_id": "EbQoZokBfd2ci_FqCmiR",
            "workflow_id": "G7QoZokBfd2ci_FqD2iZ",
            "workflow_name": "",
            "associated_alert_ids": [],
            "schema_version": 5,
            "monitor_version": 1,
            "monitor_name": "test triggers 2",
            "execution_id": "G7QoZokBfd2ci_FqD2iZ_2023-07-17T23:20:55.244970_edd977d2-c02b-4cbe-8a79-2aa7991c4191",
            "trigger_id": "NC3Dd4cBCDCIfBYtViLI",
            "trigger_name": "njkkj",
            "finding_ids": [
                "6d185585-a077-4dde-8e43-b4c01b9f3102"
            ],
            "related_doc_ids": [
                "ILQoZokBfd2ci_FqGmhb|test"
            ],
            "state": "AUDIT",
            "error_message": null,
            "alert_history": [],
            "severity": "1",
            "action_execution_results": [],
            "start_time": 1689636056943,
            "last_notification_time": 1689636056943,
            "end_time": null,
            "acknowledged_time": null
        }
    ],
    "totalAlerts": 2
}

请求体字段

字段 类型 描述
alerts 数组 由组合监控器生成的链式告警列表。
associatedAlerts 数组 由委托监控器生成的审计告警列表。

确认链式告警

获取告警后，您可以在一次调用中确认多个活动告警。如果告警已处于 ERROR、COMPLETED 或 ACKNOWLEDGED 状态，它将出现在失败数组中。

POST _plugins/_alerting/workflows/<workflow_id>/_acknowledge/alerts
{
    "alerts": ["eQURa3gBKo1jAh6qUo49"]
}

请求体字段

字段 类型 描述
alerts 数组 按 ID 列出的告警列表。结果包括系统已确认的告警以及系统未识别的告警。

示例响应

{
    "success": [
    "eQURa3gBKo1jAh6qUo49"
    ],
    "failed": []
}

在 UDB-SX Dashboards 中创建组合监控器

首先导航到 UDB-SX Dashboards 中的 创建监控 页面：告警 > 监控，然后选择 创建监控。为监控器命名，然后选择 组合监控器 作为监控器类型。创建组合监控器工作流和触发条件的步骤因您使用可视化编辑器还是提取查询编辑器而异。第一个提供用于定义组合监控器的基本 UI 选择器，而第二个允许您使用脚本构建工作流和触发条件。决定使用哪种方法后，请参考相应部分。

可视化编辑器

要使用可视化编辑器定义工作流和触发条件，请在 监控定义方式 部分选择 可视化编辑器 单选按钮。如下图所示。

../../../_images/vis-editor.png

要在可视化编辑器中完成创建组合监控器，请按照以下步骤操作：

  1. 在 频率 下拉列表中，选择 按间隔、每天、每周、每月 或 自定义corn表达式：

  • 按间隔 — 允许您根据指定的分钟、小时或天数重复运行计划。

  • 每天 — 指定一天中的时间和时区。

  • 每周 — 指定星期几、一天中的时间和时区。

  • 每月 — 指定月份中的日期、一天中的时间和时区。

  • 自定义corn表达式 — 为计划创建自定义 cron 表达式。使用 cron表达式 链接获取有关创建这些表达式的帮助，或参阅 Cron 表达式参考。

  1. 在 委派监控器 部分，通过在下拉列表中选择它们来输入要包含在工作流中的各个监控器。在可视化编辑器中，您选择监控器的顺序决定了它们在工作流中的顺序。

    选择 添加另一个监控器 以添加另一个下拉列表。至少需要两个委托监控器，最多允许总共 10 个。请记住，组合监控器支持按查询、按桶和按文档监控器作为委托监控器。

    在每个下拉列表旁边，您可以选择查看监控器图标（alt text）以打开监控器的详细信息窗口并查看相关信息。

  2. 为组合监控器定义一个或多个触发器。在 触发器 部分，选择 添加触发器。添加触发器名称，然后定义触发条件。

    • 使用 选择委托监控 标签打开弹出窗口，如下图所示。

    ../../../_images/trigger1.png

    • 使用 选择委托监控 下拉列表从先前步骤中定义的委托监控器中选择一个。对于第一个委托监控器，如果您愿意，可以选择 NOT 作为运算符。监控器填充到字段后，您可以使用列表右侧的垃圾桶图标（alt text）在需要时移除监控器。

    • 选择第一个监控器右侧的加号（alt text）以选择第二个委托监控器。选择第二个监控器后，选择运算符 AND、OR、AND NOT 或 OR NOT 之一以在两个监控器之间应用条件。应用运算符后，您可以选择该运算符以再次打开弹出窗口并更改选择。

    • 选择告警的严重性级别。选项包括 1 (最高)、2 (高)、3 (中)、4 (低) 和 5 (最低)。

    • 在 通知 部分，从下拉列表中选择一个通知通道。如果不存在通道，请选择下拉列表右侧的 管理通道 标签以设置通知通道。有关通知的更多信息，请参阅 Notifications 文档。您还可以选择 添加通知 为告警触发器指定其他通知。

      通知对于所有监控器类型都是可选的。

    • 要定义其他触发器，请选择 添加另一个触发器。最多可拥有总共 10 个触发器。选择屏幕右侧的 移除触发器 以移除触发器。

  3. 完成监控器工作流并定义触发器后，选择屏幕右下角的 创建。组合监控器被创建，监控器的详细信息窗口打开。

提取查询编辑器

要使用提取查询编辑器定义工作流和触发器，请在 监控定义方式 部分选择 提取查询编辑器 单选按钮。如下图所示。

../../../_images/extract-q-editor.png

提取查询编辑器遵循与可视化编辑器相同的一般步骤，但允许您使用 API 查询的提取来构建组合监控器工作流和告警触发器。这使您能够创建可视化编辑器不支持的高级配置。以下部分为这两个字段中的每个提供内容示例。组合监控器创建的所有其他步骤与可视化编辑器中的步骤相同。

  • 定义工作流

    在 定义工作流 字段中，输入定义委托监控器及其在工作流中顺序的序列。以下示例显示了工作流中包含的委托监控器及其在序列中的顺序：

    {
    "sequence": {
        "delegates": [
            {
                "order": 1,
                "monitor_id": "0TgBZokB2ZtsLaRvXz70"
            },
            {
                "order": 2,
                "monitor_id": "8jgBZokB2ZtsLaRv6z4N"
            }
        ]
    }
}

    工作流中包含的所有委托监控器都需要 monitor_id 和 order 值。

  • 触发条件

    在 触发条件 字段中，输入将用于定义监控器之间条件的监控器和运算符。此字段要求触发条件以 Painless 脚本语言格式化。要了解这些脚本如何为触发条件形成，请参阅使用 Painless 脚本定义链式告警触发条件。

    以下示例显示了一个触发条件，要求在组合监控器生成链式告警之前，第一个监控器或第二个监控器生成审计告警：

    (monitor[id=8d36S4kB0DWOHH7wpkET] || monitor[id=4t36S4kB0DWOHH7wL0Hk])

查看监控器详情

组合监控器创建后，它将出现在 监控 选项卡的监控器列表中。类型 列指示监控器类型，包括组合监控器类型。与复合监控器的关联 列提供一个基本监控器作为委托监控器被用于多少组合监控器的计数。选择 监控器名称 列中的监控器以打开其详细信息窗口。

对于组合监控器，详细信息窗口的 告警 部分包括 操作 列，其中包含查看详细信息图标（alt text）。下图显示 操作 列作为最右侧的最后一列。

alt text

选择此图标以打开 告警详情 窗口。此窗口向您展示作为生成链式告警的执行一部分的所有审计告警，并包括生成审计告警的委托监控器。选择窗口右上角的 X 以关闭 告警详情。

返回监控器详细信息窗口的 告警 部分后，您可以选中 告警开始时间 左侧的复选框以高亮显示告警。告警高亮显示后，您可以在此部分右上角选择 确认。告警被确认，状态 列中的状态从 Active 更改为 Acknowledged。