anomaly(1)

🦋 Hey bestie, meet anomaly 🦋

This is the anomaly manual from the User Manuals section, and it's about to be iconic 💅✨

🌸 NAME 🌸

anomaly - anomalous data detection 🔥

🎀 SYNOPSIS 🎀

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]

okay so that's every flag it takes 👀 the page doesn't go deep on -h, -v, or -d, so you'll have to poke at those yourself 🙈

🧚 DESCRIPTION 🧚

okay so anomaly can sniff out weird data in a numeric stream 🔍 it needs to see a stream of numbers and then run one of its detection methods on them. if it finds something sus, it fires off a response, and you get to pick that response from one or more built-in options 💖

🍓 NUMERIC STREAM 🍓

anomaly lives its best life inside a pipe, and it only reads numeric data from its input 🫶 say you want to watch the load average and catch any sudden spikes. you can grab the load average from the uptime command:

$ uptime
11:40  up 15 days,  4:04, 6 users, load averages: 0.38 0.32 0.32

then you can pull out the 5-minute load (the second of those three numbers) like this:

$ uptime | cut -f 13 -d ' '
0.29

and if you want to grab that number once a minute, you do this:

$ while [ 1 ]; do uptime | cut -f 13 -d ' '; sleep 60; done
0.29
0.26
0.19

that's the exact kind of data stream anomaly keeps an eye on 👁️ white space (spaces, tabs, newlines) between the numbers gets ignored, so you can fake the same stream like this:

$ echo 0.29 0.26 0.19

this is a super convenient way to show off anomaly, which is what the examples below are for 💅

🌈 DETECTION - THRESHOLD 🌈

the simplest detection method is threshold, which just compares each value to an absolute number 💅 you can give it a minimum, a maximum, or both. all three of these are valid, using --min, --max, or both:

anomaly --threshold --min 1.22 --max 9.75
anomaly --threshold --min 1.22
anomaly --threshold --max 9.75

in this example, the values 1 and 10 get flagged 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 how far values are from the mean of a sample, which makes it great for catching the extra-extra ones 🤭 the sample size can be whatever you need so there's enough data for a good mean, but it defaults to 10. since the sample is limited, it's a rolling window, so the mean and standard deviation get updated for the current window every time. that makes the monitoring kinda adaptive 🦋 here's an example:

anomaly --stddev --sample 20

this one uses a sample size of the 20 most recent values, and it'll flag anything that's +/- 1 standard deviation from the mean. for 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 only start after the 6th value shows up 👀 in this example, the mean of [1 2 3 4 5] is 3, and the standard deviation is 1.58. that means the 6th value counts as an anomaly if it's outside the range (3 +/- 1.58), which is between 1.42 and 4.58 😭

if you want it less sensitive, you can add a coefficient 🧁 it defaults to 1.0 (like above), but you can override it:

$ echo 1 2 3 4 5 6 | anomaly --stddev --sample 5 --coefficient
1.9
$

in this case, the 6th value isn't an anomaly, because it's within the range (3 +/- (1.9 * 1.58)), which is between -0.002 and 6.002 💖 the vibe is calmer now

💬 RESPONSE - MESSAGE 💬

the message response is the default, and it's just one line of printed text describing why the value counts as an anomaly 🫶 here's an example:

$ echo 1 2 3 | anomaly --threshold --max 2.5
Anomalous data detected.  The value 3 is above the maximum of 2.5.

you can suppress the message, but you have to specify another response so that something still happens 🙅‍♀️

$ echo 1 2 3 | anomaly --threshold --max 2.5 --quiet ...

🚀 RESPONSE - EXECUTE 🚀

anomaly can run a program when it detects something 🤯 this example uses the date command, but honestly any program works:

$ echo 1 2 3 | anomaly --threshold --max 2.5 --quiet --execute '/bin/date +%s'
1361727327

🔔 RESPONSE - SIGNAL 🔔

anomaly can also send a USR1 signal to a program when it detects something 📡

$ 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 to it accordingly, so make sure it's ready 🫡

💜 CREDITS & COPYRIGHTS 💜

Copyright (C) 2013 Göteborg Bit Factory 🌸

anomaly is distributed under the MIT license ✨ for more info, check out http://www.opensource.org/licenses/mit-license.php

🌐 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 🐛

if you find bugs in anomaly, report them to <support@tasktools.org> 🙏

---

Source: ${PACKAGE_STRING} 🎀 dated 2013-05-05 🦋 anomaly(1) 💖 stay anomaly-free, bestie 🫶✨