WARNING: Version 6.1 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
This API enables you to retrieve overall bucket results that summarize the bucket results of multiple jobs.
GET _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
You 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
.
-
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.
-
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
.
The API returns the following information:
-
overall_buckets
- (array) An array of overall bucket objects. For more information, see Overall Buckets.
You 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.
The 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" } ] }