IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Get overall buckets API

edit

Get overall buckets API

edit

Retrieves overall bucket results that summarize the bucket results of multiple anomaly detection jobs.

Request

edit

GET _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

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.

Description

edit

You 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) If false and the job_id does not match any anomaly detection jobs, an error occurs. The default value is true.
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: (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: (Optional, integer) The number of top anomaly detection job bucket scores to be used in the overall_score calculation. The default value is 1.

Response body

edit

The API returns the following information:

overall_buckets: (array) An array of overall bucket objects. For more information, see Overall Buckets.

Examples

edit

The following example gets overall buckets for anomaly detection jobs with IDs matching job-*:

GET _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"
    }
  ]
}

« Get buckets API Get categories API »