Search Anomaly Detectors tool

Introduced 2.12

This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated GitHub issue.

The SearchAnomalyDetectorsTool retrieves information about anomaly detectors set up on your cluster. For more information about anomaly detectors, see Anomaly detection.

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

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_Anomaly_Detectors_Tool",
  4. "type": "flow",
  5. "description": "this is a test agent for the SearchAnomalyDetectorsTool",
  6. "memory": {
  7. "type": "demo"
  8. },
  9. "tools": [
  10. {
  11. "type": "SearchAnomalyDetectorsTool",
  12. "name": "DemoSearchAnomalyDetectorsTool",
  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 anomaly detectors?"
  5. }
  6. }

copy

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

  1. {
  2. "inference_results": [
  3. {
  4. "output": [
  5. {
  6. "name": "response",
  7. "result": "AnomalyDetectors=[{id=y2M-Yo0B-yCFzT-N_XXU,name=sample-http-responses-detector,type=SINGLE_ENTITY,description=A sample detector to detect anomalies with HTTP response code logs.,index=[sample-http-responses],lastUpdateTime=1706750311891}]TotalAnomalyDetectors=1"
  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
detectorNameStringThe name of the detector to search for.
detectorNamePatternStringA wildcard query used to match the detector name to search for.
indicesStringThe index name or index pattern of the indexes that the returned detectors are using as data sources.
highCardinalityBooleanWhether to return information about high-cardinality detectors. Leave this parameter unset (or set it to null) to return information about both high-cardinality (multi-entity) and non-high-cardinality (single-entity) detectors. Set this parameter to true to only return information about high-cardinality detectors. Set this parameter to false to only return information about non-high-cardinality detectors.
lastUpdateTimeLongSpecifies the earliest last updated time of the detectors to return, in epoch milliseconds. Default is null.
sortOrderStringThe sort order for the results. Valid values are asc (ascending) and desc (descending). Default is desc.
sortStringStringSpecifies the detector 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 detector to start from. Default is 0.
runningBooleanWhether to return information about detectors that are currently running. Leave this parameter unset (or set it to null) to return both running and non-running detector information. Set this parameter to true to only return information about running detectors. Set this parameter to false to return only information about detectors that are not currently running. Default is null.
disabledBooleanWhether to return information about detectors that are currently disabled. Leave this parameter unset (or set it to null) to return information about both enabled and disabled detectors. Set this parameter to true to return only information about disabled detectors. Set this parameter to false to return only information about enabled detectors. Default is null.
failedBooleanWhether to return information about detectors that are currently failing. Leave this parameter unset (or set it to null) to return information about both failed and non-failed detectors. Set this parameter to true to return only information about failed detectors. Set this parameter to false to return only information about non-failed detectors. Default is null.

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.