You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Search Alerts tool
Introduced 2.13
The SearchAlertsTool
retrieves information about generated alerts. For more information about alerts, see Alerting.
Step 1: Register a flow agent that will run the SearchAlertsTool
A flow agent runs a sequence of tools in order and returns the last tool’s output. To create a flow agent, send the following register agent request:
POST /_plugins/_ml/agents/_register
{
"name": "Test_Agent_For_Search_Alerts_Tool",
"type": "flow",
"description": "this is a test agent for the SearchAlertsTool",
"memory": {
"type": "demo"
},
"tools": [
{
"type": "SearchAlertsTool",
"name": "DemoSearchAlertsTool",
"parameters": {}
}
]
}
For parameter descriptions, see Register parameters.
OpenSearch responds with an agent ID:
{
"agent_id": "EuJYYo0B9RaBCvhuy1q8"
}
Step 2: Run the agent
Run the agent by sending the following request:
POST /_plugins/_ml/agents/EuJYYo0B9RaBCvhuy1q8/_execute
{
"parameters": {
"question": "Do I have any alerts?"
}
}
OpenSearch responds with a list of generated alerts and the total number of alerts:
{
"inference_results": [
{
"output": [
{
"name": "response",
"result": "Alerts=[Alert(id=rv9nYo0Bk4MTqirc_DkW, version=394, schemaVersion=5, monitorId=ZuJnYo0B9RaBCvhuEVux, workflowId=, workflowName=, monitorName=test-monitor-2, monitorVersion=1, monitorUser=User[name=admin, backend_roles=[admin], roles=[own_index, all_access], custom_attribute_names=[], user_requested_tenant=null], triggerId=ZeJnYo0B9RaBCvhuEVul, triggerName=t-1, findingIds=[], relatedDocIds=[], state=ACTIVE, startTime=2024-02-01T02:03:18.420Z, endTime=null, lastNotificationTime=2024-02-01T08:36:18.409Z, acknowledgedTime=null, errorMessage=null, errorHistory=[], severity=1, actionExecutionResults=[], aggregationResultBucket=null, executionId=ZuJnYo0B9RaBCvhuEVux_2024-02-01T02:03:18.404853331_51c18f2c-5923-47c3-b476-0f5a66c6319b, associatedAlertIds=[])]TotalAlerts=1"
}
]
}
]
}
If no alerts are found, OpenSearch responds with an empty array in the results:
{
"inference_results": [
{
"output": [
{
"name": "response",
"result": "Alerts=[]TotalAlerts=0"
}
]
}
]
}
Register parameters
The following table lists all tool parameters that are available when registering an agent. All parameters are optional.
Parameter | Type | Description |
---|---|---|
alertIds | Array | The ID of the alert to search for. |
monitorId | String | The name of the monitor by which to filter the alerts. |
workflowIds | Array | A list of workflow IDs by which to filter the alerts. |
alertState | String | The alert state by which to filter the alerts. Valid values are ALL , ACTIVE , ERROR , COMPLETED , and ACKNOWLEDGED . Default is ALL . |
severityLevel | String | The severity level by which to filter the alerts. Valid values are ALL , 1 , 2 , and 3 . Default is ALL . |
searchString | String | The search string to use for searching for a specific alert. |
sortOrder | String | The sort order of the results. Valid values are asc (ascending) and desc (descending). Default is asc . |
sortString | String | Specifies the monitor field by which to sort the results. Default is monitor_name.keyword . |
size | Integer | The number of results to return. Default is 20 . |
startIndex | Integer | The paginated index of the alert to start from. Default is 0 . |
Execute parameters
The following table lists all tool parameters that are available when running the agent.
Parameter | Type | Required/Optional | Description |
---|---|---|---|
question | String | Required | The natural language question to send to the LLM. |