Get Overall Buckets API
editGet Overall Buckets API
editRetrieves overall bucket results that summarize the bucket results of multiple jobs.
Request
editGET _xpack/ml/anomaly_detectors/<job_id>/results/overall_buckets
GET _xpack/ml/anomaly_detectors/<job_id>,<job_id>/results/overall_buckets
GET _xpack/ml/anomaly_detectors/_all/results/overall_buckets
Description
editYou can summarize the bucket results for all jobs by using _all
or by
specifying *
as the <job_id>
.
An overall bucket has a span equal to the largest bucket_span
value for the
specified jobs.
The overall_score
is calculated by combining the scores of all
the buckets within the overall bucket span. First, the maximum anomaly_score
per
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.
In addition, the optional parameter bucket_span
may be used in order
to request overall buckets that span longer than the largest job’s bucket_span
.
When set, the overall_score
will be the max overall_score
of the corresponding
overall buckets with a span equal to the largest job’s bucket_span
.
Path Parameters
edit-
job_id
- (string) Identifier for the 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
-
(boolean) If
false
and thejob_id
does not match any job an error will be returned. The default value istrue
. -
bucket_span
-
(string) The span of the overall buckets. Must be greater or equal
to the largest job’s
bucket_span
. Defaults to the largest job’sbucket_span
. -
end
- (string) Returns overall buckets with timestamps earlier than this time.
-
exclude_interim
-
(boolean) If
true
, the output excludes interim overall buckets. Overall buckets are interim if any of the job buckets within the overall bucket interval are interim. By default, interim results are included. -
overall_score
- (double) Returns overall buckets with overall scores greater or equal than this value.
-
start
- (string) Returns overall buckets with timestamps after this time.
-
top_n
-
(integer) The number of top job bucket scores to be used in the
overall_score
calculation. The default value is1
.
Results
editThe API returns the following information:
-
overall_buckets
- (array) An array of overall bucket objects. For more information, see Overall Buckets.
Authorization
editYou must have monitor_ml
, monitor
, manage_ml
, or manage
cluster
privileges to use this API. You also need read
index privilege on the index
that stores the results. The machine_learning_admin
and machine_learning_user
roles provide these privileges. For more information, see
Security privileges and
Built-in roles.
Examples
editThe following example gets overall buckets for jobs with IDs matching job-*
:
GET _xpack/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 _xpack/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" } ] }