OpenSearch/docs/reference/ml/anomaly-detection/functions/ml-count-functions.asciidoc

[role="xpack"]
[[ml-count-functions]]
= Count functions

Count functions detect anomalies when the number of events in a bucket is
anomalous.

Use `non_zero_count` functions if your data is sparse and you want to ignore
cases where the bucket count is zero.

Use `distinct_count` functions to determine when the number of distinct values
in one field is unusual, as opposed to the total count.

Use high-sided functions if you want to monitor unusually high event rates.
Use low-sided functions if you want to look at drops in event rate.

The {ml-features} include the following count functions:

* xref:ml-count[`count`, `high_count`, `low_count`]
* xref:ml-nonzero-count[`non_zero_count`, `high_non_zero_count`, `low_non_zero_count`]
* xref:ml-distinct-count[`distinct_count`, `high_distinct_count`, `low_distinct_count`]

[float]
[[ml-count]]
== Count, high_count, low_count

The `count` function detects anomalies when the number of events in a bucket is
anomalous.

The `high_count` function detects anomalies when the count of events in a
bucket are unusually high.

The `low_count` function detects anomalies when the count of events in a
bucket are unusually low.

These functions support the following properties:

* `by_field_name` (optional)
* `over_field_name` (optional)
* `partition_field_name` (optional)

For more information about those properties, see the
{ref}/ml-put-job.html#ml-put-job-request-body[create {anomaly-jobs} API].

.Example 1: Analyzing events with the count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example1
{
  "analysis_config": {
    "detectors": [{
      "function" : "count"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

This example is probably the simplest possible analysis. It identifies
time buckets during which the overall count of events is higher or lower than
usual.

When you use this function in a detector in your {anomaly-job}, it models the
event rate and detects when the event rate is unusual compared to its past
behavior.

.Example 2: Analyzing errors with the high_count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example2
{
  "analysis_config": {
    "detectors": [{
      "function" : "high_count",
      "by_field_name" : "error_code",
      "over_field_name": "user"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

If you use this `high_count` function in a detector in your {anomaly-job}, it
models the event rate for each error code. It detects users that generate an
unusually high count of error codes compared to other users.


.Example 3: Analyzing status codes with the low_count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example3
{
  "analysis_config": {
    "detectors": [{
      "function" : "low_count",
      "by_field_name" : "status_code"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

In this example, the function detects when the count of events for a
status code is lower than usual.

When you use this function in a detector in your {anomaly-job}, it models the
event rate for each status code and detects when a status code has an unusually
low count compared to its past behavior.

.Example 4: Analyzing aggregated data with the count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example4
{
  "analysis_config": {
    "summary_count_field_name" : "events_per_min",
    "detectors": [{
      "function" : "count"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}  
--------------------------------------------------
// TEST[skip:needs-licence]

If you are analyzing an aggregated `events_per_min` field, do not use a sum
function (for example, `sum(events_per_min)`). Instead, use the count function
and the `summary_count_field_name` property. For more information, see 
<<ml-configuring-aggregation>>.

[float]
[[ml-nonzero-count]]
== Non_zero_count, high_non_zero_count, low_non_zero_count

The `non_zero_count` function detects anomalies when the number of events in a
bucket is anomalous, but it ignores cases where the bucket count is zero. Use
this function if you know your data is sparse or has gaps and the gaps are not
important.

The `high_non_zero_count` function detects anomalies when the number of events
in a bucket is unusually high and it ignores cases where the bucket count is
zero.

The `low_non_zero_count` function detects anomalies when the number of events in
a bucket is unusually low and it ignores cases where the bucket count is zero.

These functions support the following properties:

* `by_field_name` (optional)
* `partition_field_name` (optional)

For more information about those properties, see the 
{ref}/ml-put-job.html#ml-put-job-request-body[create {anomaly-jobs} API].

For example, if you have the following number of events per bucket:

========================================

1,22,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,43,31,0,0,0,0,0,0,0,0,0,0,0,0,2,1

========================================

The `non_zero_count` function models only the following data:

========================================

1,22,2,43,31,2,1

========================================

.Example 5: Analyzing signatures with the high_non_zero_count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example5
{
  "analysis_config": {
    "detectors": [{
      "function" : "high_non_zero_count",
      "by_field_name" : "signaturename"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

If you use this `high_non_zero_count` function in a detector in your
{anomaly-job}, it models the count of events for the `signaturename` field. It
ignores any buckets where the count is zero and detects when a `signaturename`
value has an unusually high count of events compared to its past behavior.

NOTE: Population analysis (using an `over_field_name` property value) is not
supported for the `non_zero_count`, `high_non_zero_count`, and
`low_non_zero_count` functions. If you want to do population analysis and your
data is sparse, use the `count` functions, which are optimized for that scenario.


[float]
[[ml-distinct-count]]
== Distinct_count, high_distinct_count, low_distinct_count

The `distinct_count` function detects anomalies where the number of distinct
values in one field is unusual.

The `high_distinct_count` function detects unusually high numbers of distinct
values in one field.

The `low_distinct_count` function detects unusually low numbers of distinct
values in one field.

These functions support the following properties:

* `field_name` (required)
* `by_field_name` (optional)
* `over_field_name` (optional)
* `partition_field_name` (optional)

For more information about those properties, see the 
{ref}/ml-put-job.html#ml-put-job-request-body[create {anomaly-jobs} API].

.Example 6: Analyzing users with the distinct_count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example6
{
  "analysis_config": {
    "detectors": [{
      "function" : "distinct_count",
      "field_name" : "user"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

This `distinct_count` function detects when a system has an unusual number
of logged in users. When you use this function in a detector in your
{anomaly-job}, it models the distinct count of users. It also detects when the
distinct number of users is unusual compared to the past.

.Example 7: Analyzing ports with the high_distinct_count function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example7
{
  "analysis_config": {
    "detectors": [{
      "function" : "high_distinct_count",
      "field_name" : "dst_port",
      "over_field_name": "src_ip"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

This example detects instances of port scanning. When you use this function in a
detector in your {anomaly-job}, it models the distinct count of ports. It also
detects the `src_ip` values that connect to an unusually high number of different
`dst_ports` values compared to other `src_ip` values.