Merge pull request #251 from opensearch-project/multi-category-filtering

Added multi-category filtering

_monitoring-plugins/ad/api.md

@@ -2226,6 +2226,73 @@ POST _plugins/_anomaly_detection/detectors/results/_search
 
 ---
 
+## Search top anomalies
+Introduced 1.2
+{: .label .label-purple }
+
+Returns the top anomaly results for a high-cardinality detector, bucketed by categorical field values.
+
+You can pass a `historical` boolean parameter to specify whether you want to analyze real-time or historical results.
+
+#### Request
+
+```json
+GET _plugins/_anomaly_detection/detectors/<detectorId>/results/_topAnomalies?historical=false
+{
+  "size": 3,
+  "category_field": [
+    "ip"
+  ],
+  "order": "severity",
+  "task_id": "example-task-id",
+  "start_time_ms": 123456789000,
+  "end_time_ms": 987654321000
+}
+```
+
+#### Sample response
+
+```json
+{
+  "buckets": [
+    {
+      "key": {
+        "ip": "1.2.3.4"
+      },
+      "doc_count": 10,
+      "max_anomaly_grade": 0.8
+    },
+    {
+      "key": {
+        "ip": "5.6.7.8"
+      },
+      "doc_count": 12,
+      "max_anomaly_grade": 0.6
+    },
+    {
+      "key": {
+        "ip": "9.10.11.12"
+      },
+      "doc_count": 3,
+      "max_anomaly_grade": 0.5
+    }
+  ]
+}
+```
+
+You can specify the following options.
+
+Options | Description | Type | Required
+:--- | :--- |:--- |:--- |
+`size` |  Specify the number of top buckets that you want to see. Default is 10. The maximum number is 10,000. | `integer` | No
+`category_field` |  Specify the set of category fields that you want to aggregate on. Defaults to all category fields for the detector. | `list` | No
+`order` |  Specify `severity` (anomaly grade) or `occurrence` (number of anomalies). Default is `severity`. | `string` | No
+`task_id`  |  Specify a historical task ID to see results only from that specific task. Use only when `historical=true`, otherwise the anomaly detection plugin ignores this parameter. | `string` | No
+`start_time_ms` | Specify the time to start analyzing results, in Epoch milliseconds. | `long` | Yes
+`end_time_ms` |  Specify the time to end analyzing results, in Epoch milliseconds. | `long` | Yes
+
+---
+
 ## Get detector stats
 Introduced 1.0
 {: .label .label-purple }

_monitoring-plugins/ad/index.md

@@ -160,6 +160,12 @@ If you set the category field, you see an additional **Heat map** chart. The hea
 Choose and drag over the anomaly line chart to zoom in and see a more detailed view of an anomaly.
 {: .note }
 
+If you have set multiple category fields, you can select a subset of fields to filter and sort the fields by. Selecting a subset of fields lets you see the top values of one field that share a common value with another field.
+
+For example, if you have a detector with the category fields `ip` and `endpoint`, you can select `endpoint` in the **View by** dropdown menu. Then, select a specific cell to overlay the top 20 values of `ip` on the charts. The anomaly detection plugin selects the top `ip` by default. You can see a maximum of 5 individual time-series values at the same time.
+
+![Anomaly detection results]({{site.url}}{{site.baseurl}}/images/multi-category-ad.png)
+
 ## Step 6: Set up alerts
 
 Under **Real-time results**, choose **Set up alerts** and configure a monitor to notify you when anomalies are detected. For steps to create a monitor and set up notifications based on your anomaly detector, see [Monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/).