OpenSearch/docs/en/ml/functions/time.asciidoc

[[ml-time-functions]]
=== Time Functions

The {xpackml} features include the following time functions:

* `time_of_day`
* `time_of_week`

The time functions detect events that happen at unusual times, either of the day
or of the week. These functions can be used to find unusual patterns of behavior,
typically associated with suspicious user activity.


[NOTE]
====
* The `time_of_day` function is not aware of the difference between days, for instance
work days and weekends. When modeling different days, use the `time_of_week` function.
In general, the `time_of_week` function is more suited to modeling the behavior of people
rather than machines, as people vary their behavior according to the day of the week.
* Shorter bucket spans (for example, 10 minutes) are recommended when performing a
`time_of_day` or `time_of_week` analysis. The time of the events being modeled are not
affected by the bucket span, but a shorter bucket span enables quicker alerting on unusual
events.
* Unusual events are flagged based on the previous pattern of the data, not on what we
might think of as unusual based on human experience. So, if events typically occur
between 3 a.m. and 5 a.m., and event occurring at 3 p.m. is be flagged as unusual.
* When Daylight Saving Time starts or stops, regular events can be flagged as anomalous.
This situation occurs because the actual time of the event (as measured against a UTC
baseline) has changed. This situation is treated as a step change in behavior and the new
times will be learned quickly.
====


/////

[source,js]
--------------------------------------------------
{ "function" : "time_of_day", "byFieldName" : "process" }
--------------------------------------------------


/////