99 lines
3.7 KiB
Plaintext
99 lines
3.7 KiB
Plaintext
[[ml-time-functions]]
|
|
=== Time Functions
|
|
|
|
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.
|
|
|
|
The {xpackml} features include the following time functions:
|
|
|
|
* <<ml-time-of-day,`time_of_day`>>
|
|
* <<ml-time-of-week,`time_of_week`>>
|
|
|
|
|
|
[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.
|
|
====
|
|
|
|
[float]
|
|
[[ml-time-of-day]]
|
|
==== Time_of_day
|
|
|
|
The `time_of_day` function detects when events occur that are outside normal
|
|
usage patterns. For example, it detects unusual activity in the middle of the
|
|
night.
|
|
|
|
The function expects daily behavior to be similar. If you expect the behavior of
|
|
your data to differ on Saturdays compared to Wednesdays, the `time_of_week`
|
|
function is more appropriate.
|
|
|
|
This function supports the following properties:
|
|
|
|
* `by_field_name` (optional)
|
|
* `over_field_name` (optional)
|
|
* `partition_field_name` (optional)
|
|
|
|
For more information about those properties,
|
|
see <<ml-detectorconfig,Detector Configuration Objects>>.
|
|
|
|
.Example 1: Analyzing events with the time_of_day function
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"function" : "time_of_day",
|
|
"by_field_name" : "process"
|
|
}
|
|
--------------------------------------------------
|
|
|
|
If you use this `time_of_day` function in a detector in your job, it
|
|
models when events occur throughout a day for each process. It detects when an
|
|
event occurs for a process that is at an unusual time in the day compared to
|
|
its past behavior.
|
|
|
|
[float]
|
|
[[ml-time-of-week]]
|
|
==== Time_of_week
|
|
|
|
The `time_of_week` function detects when events occur that are outside normal
|
|
usage patterns. For example, it detects login events on the weekend.
|
|
|
|
This function supports the following properties:
|
|
|
|
* `by_field_name` (optional)
|
|
* `over_field_name` (optional)
|
|
* `partition_field_name` (optional)
|
|
|
|
For more information about those properties,
|
|
see <<ml-detectorconfig,Detector Configuration Objects>>.
|
|
|
|
.Example 2: Analyzing events with the time_of_week function
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"function" : "time_of_week",
|
|
"by_field_name" : "eventcode",
|
|
"over_field_name" : "workstation"
|
|
}
|
|
--------------------------------------------------
|
|
|
|
If you use this `time_of_week` function in a detector in your job, it
|
|
models when events occur throughout the week for each `eventcode`. It detects
|
|
when a workstation event occurs at an unusual time during the week for that
|
|
`eventcode` compared to other workstations. It detects events for a
|
|
particular workstation that are outside the normal usage pattern.
|