Search Monitors tool

Introduced 2.13

The SearchMonitorsTool retrieves information about alerting monitors set up on your cluster. For more information about alerting monitors, see Monitors.

Step 1: Register a flow agent that will run the SearchMonitorsTool

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:

  1. POST /_plugins/_ml/agents/_register
  2. {
  3.   "name": "Test_Agent_For_Search_Monitors_Tool",
  4.   "type": "flow",
  5.   "description": "this is a test agent for the SearchMonitorsTool",
  6.   "memory": {
  7.     "type": "demo"
  8.   },
  9.   "tools": [
  10.     {
  11.       "type": "SearchMonitorsTool",
  12.       "name": "DemoSearchMonitorsTool",
  13.       "parameters": {}
  14.     }
  15.   ]
  16. }

copy

For parameter descriptions, see Register parameters.

OpenSearch responds with an agent ID:

  1. {
  2.   "agent_id": "EuJYYo0B9RaBCvhuy1q8"
  3. }

Step 2: Run the agent

Run the agent by sending the following request:

  1. POST /_plugins/_ml/agents/EuJYYo0B9RaBCvhuy1q8/_execute
  2. {
  3.   "parameters": {
  4.     "question": "Do I have any alerting monitors?"
  5.   }
  6. }

copy

OpenSearch responds with a list of alerting monitors set up on your cluster and the total number of alerting monitors:

  1. {
  2.   "inference_results": [
  3.     {
  4.       "output": [
  5.         {
  6.           "name": "response",
  7.           "result": "Monitors=[{id=j_9mYo0Bk4MTqircEzk_,name=test-monitor,type=query_level_monitor,enabled=true,enabledTime=1706752873144,lastUpdateTime=1706752873145}{id=ZuJnYo0B9RaBCvhuEVux,name=test-monitor-2,type=query_level_monitor,enabled=true,enabledTime=1706752938405,lastUpdateTime=1706752938405}]TotalMonitors=2"
  8.         }
  9.       ]
  10.     }
  11.   ]
  12. }

If no monitors are found, OpenSearch responds with an empty array in the results:

  1. {
  2.   "inference_results": [
  3.     {
  4.       "output": [
  5.         {
  6.           "name": "response",
  7.           "result": "Monitors=[]TotalMonitors=0"
  8.         }
  9.       ]
  10.     }
  11.   ]
  12. }

Register parameters

The following table lists all tool parameters that are available when registering an agent. All parameters are optional.

ParameterTypeDescription
monitorIdStringThe ID of the monitor to search for.
monitorNameStringThe name of the monitor to search for.
monitorNamePatternStringA wildcard query used to match the monitor name to search for.
enabledBooleanWhether to return information about monitors that are currently enabled. Leave this parameter unset (or set it to null) to return information about both enabled and disabled monitors. Set this parameter to true to return only information about enabled monitors. Set this parameter to false to return only information about disabled monitors. Default is null.
hasTriggersBooleanWhether to return information about monitors that have triggers enabled. Leave this parameter unset (or set it to null) to return information about monitors that have triggers enabled and disabled. Set this parameter to true to return only information about monitors with triggers enabled. Set this parameter to false to return only information about monitors with triggers disabled. Default is null.
indicesStringThe index name or index pattern of the indexes tracked by the returned monitors.
sortOrderStringThe sort order of the results. Valid values are asc (ascending) and desc (descending). Default is asc.
sortStringStringSpecifies the monitor field by which to sort the results. Default is name.keyword.
sizeIntegerThe number of results to return. Default is 20.
startIndexIntegerThe paginated index of the monitor to start from. Default is 0.

Execute parameters

The following table lists all tool parameters that are available when running the agent.

ParameterTypeRequired/OptionalDescription
questionStringRequiredThe natural language question to send to the LLM.