Get overall buckets API
editGet overall buckets API
editRetrieves overall bucket results that summarize the bucket results of multiple anomaly detection jobs.
Request
editGET _ml/anomaly_detectors/<job_id>/results/overall_buckets
GET _ml/anomaly_detectors/<job_id>,<job_id>/results/overall_buckets
GET _ml/anomaly_detectors/_all/results/overall_buckets
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have
monitor_ml
,monitor
,manage_ml
, ormanage
cluster privileges to use this API. You also needread
index privilege on the index that stores the results. Themachine_learning_admin
andmachine_learning_user
roles provide these privileges. See Security privileges, Built-in roles, and Machine learning security privileges.
Description
editYou can summarize the bucket results for all anomaly detection jobs by using _all
or
by specifying *
as the <job_id>
.
By default, an overall bucket has a span equal to the largest bucket span of the
specified anomaly detection jobs. To override that behavior, use the optional
bucket_span
parameter. To learn more about the concept of buckets, see
Buckets.
The overall_score
is calculated by combining the scores of all the buckets
within the overall bucket span. First, the maximum anomaly_score
per
anomaly detection job in the overall bucket is calculated. Then the top_n
of those
scores are averaged to result in the overall_score
. This means that you can
fine-tune the overall_score
so that it is more or less sensitive to the number
of jobs that detect an anomaly at the same time. For example, if you set top_n
to 1
, the overall_score
is the maximum bucket score in the overall bucket.
Alternatively, if you set top_n
to the number of jobs, the overall_score
is
high only when all jobs detect anomalies in that overall bucket. If you set
the bucket_span
parameter (to a value greater than its default), the
overall_score
is the maximum overall_score
of the overall buckets that have
a span equal to the jobs' largest bucket span.
Path parameters
edit-
<job_id>
- (Required, string) Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression.
Request body
edit-
allow_no_jobs
-
(Optional, Boolean) Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs that match.
-
Contains the
_all
string or no identifiers and there are no matches. - Contains wildcard expressions and there are only partial matches.
The default value is
true
, which returns an emptyjobs
array when there are no matches and the subset of results when there are partial matches. If this parameter isfalse
, the request returns a404
status code when there are no matches or only partial matches. -
bucket_span
- (Optional, string) The span of the overall buckets. Must be greater or equal to the largest bucket span of the specified anomaly detection jobs, which is the default value.
-
end
- (Optional, string) Returns overall buckets with timestamps earlier than this time.
-
exclude_interim
-
(Optional, Boolean) If
true
, the output excludes interim results. By default, interim results are included.If any of the job bucket results within the overall bucket interval are interim results, the overall bucket results are interim results.
-
overall_score
- (Optional, double) Returns overall buckets with overall scores greater than or equal to this value.
-
start
- (Optional, string) Returns overall buckets with timestamps after this time.
-
top_n
-
(Optional, integer) The number of top anomaly detection job bucket scores to be used in
the
overall_score
calculation. The default value is1
.
Response body
editThe API returns an array of overall bucket objects, which have the following properties:
-
bucket_span
-
(number) The length of the bucket in seconds. Matches the job with the longest
bucket_span
value. -
is_interim
-
(Boolean)
If
true
, this is an interim result. In other words, the results are calculated based on partial input data. -
jobs
-
(array) An array of objects that contain the
max_anomaly_score
perjob_id
. -
overall_score
-
(number) The
top_n
average of the maximum bucketanomaly_score
per job. -
result_type
-
(string) Internal. This is always set to
overall_bucket
. -
timestamp
- (date) The start time of the bucket for which these results were calculated.
Examples
editGET _ml/anomaly_detectors/job-*/results/overall_buckets { "overall_score": 80, "start": "1403532000000" }
In this example, the API returns a single result that matches the specified
score and time constraints. The overall_score
is the max job score as
top_n
defaults to 1 when not specified:
{ "count": 1, "overall_buckets": [ { "timestamp" : 1403532000000, "bucket_span" : 3600, "overall_score" : 80.0, "jobs" : [ { "job_id" : "job-1", "max_anomaly_score" : 30.0 }, { "job_id" : "job-2", "max_anomaly_score" : 10.0 }, { "job_id" : "job-3", "max_anomaly_score" : 80.0 } ], "is_interim" : false, "result_type" : "overall_bucket" } ] }
The next example is similar but this time top_n
is set to 2
:
GET _ml/anomaly_detectors/job-*/results/overall_buckets { "top_n": 2, "overall_score": 50.0, "start": "1403532000000" }
Note how the overall_score
is now the average of the top 2 job scores:
{ "count": 1, "overall_buckets": [ { "timestamp" : 1403532000000, "bucket_span" : 3600, "overall_score" : 55.0, "jobs" : [ { "job_id" : "job-1", "max_anomaly_score" : 30.0 }, { "job_id" : "job-2", "max_anomaly_score" : 10.0 }, { "job_id" : "job-3", "max_anomaly_score" : 80.0 } ], "is_interim" : false, "result_type" : "overall_bucket" } ] }