anomaly(1) | User Manuals | anomaly(1) |
NAME¶
anomaly - anomalous data detectionSYNOPSIS¶
anomaly [-h|--help] [-v|--version] [-d|--details][-t|--threshold] [--min N] [--max N]
[-s|--stddev] [-n|--sample N] [-c|--coefficient N]
[-q|--quiet]
[-e|--execute PROGRAM]
[-p|--pid PID]
DESCRIPTION¶
Anomaly can detect anomalous data in a numeric stream. In order to do this, anomaly needs to see a stream of numeric data, and apply one of its detection methods. If an anomaly is detected, a response is made, chosen from one or more built in methods.NUMERIC STREAM¶
Anomaly works best in a pipe, and will read only numeric data from its input. As a simple example, suppose you wish to monitor load average and look for unusual spikes. The load average can be obtained from the 'uptime' command:$ uptime
11:40 up 15 days, 4:04, 6 users, load averages: 0.38 0.32 0.32
We can extract the 5-minute load (the second of the three numbers) using this:
$ uptime | cut -f 13 -d ' '
0.29
That number can be extracted once a minute, using this:
$ while [ 1 ]; do uptime | cut -f 13 -d ' '; sleep 60;
done
0.29
0.26
0.19
That is the kind of data stream that anomaly monitors. White space (spaces,
tabs, newlines) between the numbers are ignored, so we can simulate the above
stream like this:
$ echo 0.29 0.26 0.19
This is a convenient way to demonstrate anomaly, shown below.
DETECTION - THRESHOLD¶
The simplest detection method is threshold, which compares the data to an absolute value. This method can use a minimum and a maximum value for comparison. These alternatives are all valid, and make use of --min, --max or both:anomaly --threshold --min 1.22 --max 9.75
anomaly --threshold --min 1.22
anomaly --threshold --max 9.75
In the following example, the values '1' and '10' would be detected as
anomalies:
$ echo 2 1 3 6 10 5 | anomaly --threshold --min 1.5 --max
8
Anomalous data detected. The value 1 is below the minimum of 1.5.
Anomalous data detected. The value 10 is above the maximum of 8.
DETECTION - STANDARD DEVIATION¶
Standard deviation measures differences from the mean value of a sample of data, and is useful for detecting extraordinary values. The sample size can be chosen such that there is enough data to determine a good mean value, but defaults to 10. The limited sample size means that a rolling window of data is used, and therefore the mean and standard deviation is updated for the current window. This makes the monitoring somewhat adaptive. Here is an example:anomaly --stddev --sample 20
This uses a sample size of the 20 most recent values, and will detect any values
that are +/- 1 standard deviation from the mean. An example:
$ echo 1 2 3 4 5 6 | anomaly --stddev --sample 5
Anomalous data detected. The value 6 is more than 1 sigma(s) above the mean
value 3, with a sample size of 5.
With a sample size of 5, comparisons being only after the 6th value is seen. In
the example, the mean value of [1 2 3 4 5] is 3, and the standard deviation is
1.58. This means that the 6th value is considered an anomaly if it is within
the range (3 +/- 1.58), which is between 1.42 and 4.58.
To make this less sensitive, a coefficient is introduced, which defaults to 1.0
(as above) but can be overridden:
$ echo 1 2 3 4 5 6 | anomaly --stddev --sample 5
--coefficient 1.9
$
In this example, the 6th value is not considered an anomaly because it is within
the range (3 +/- (1.9 * 1.58)), which is between -0.002 and 6.002.
RESPONSE - MESSAGE¶
The message response is the default, and consists of a single line of printed text. It is a description of why the data value is considered an anomaly. Here is an example:$ echo 1 2 3 | anomaly --threshold --max 2.5
Anomalous data detected. The value 3 is above the maximum of 2.5.
The message can be suppressed, but another response must be specified, so that
there is some kind of response:
$ echo 1 2 3 | anomaly --threshold --max 2.5 --quiet
...
RESPONSE - EXECUTE¶
Anomaly can execute a program in response to detection. Here an example uses the 'date' command, but any program can be used:$ echo 1 2 3 | anomaly --threshold --max 2.5 --quiet
--execute '/bin/date +%s'
1361727327
RESPONSE - SIGNAL¶
Anomaly can send a USR1 signal to a program in response to detection:$ echo 1 2 3 | anomaly --threshold --max 2.5 --quiet
--pid 12345
This sends the USR1 signal to the process with PID 12345. The receiving program
would need to respond accordingly.
CREDITS & COPYRIGHTS¶
Copyright (C) 2013 Göteborg Bit Factory. Anomaly is distributed under the MIT license. See http://www.opensource.org/licenses/mit-license.php for more information.SEE ALSO¶
For more information, see:- The official site at
- <http://tasktools.org/projects/anomaly>
- You can contact the project by writing an email to
- <support@tasktools.org>
REPORTING BUGS¶
- Bugs in anomaly may be reported to <support@tasktools.org>
2013-05-05 | ${PACKAGE_STRING} |