tsanomaly

A Python library for autonomous, explainable, real-time anomaly detection on time-series metrics.

pip install tsanomaly
tsanomaly detect metrics.csv     # or straight from the terminal

Why tsanomaly

• Nothing to configure - feed it raw metrics; the sampling interval, daily/weekly patterns, model choice, and expected range are learned per metric. No thresholds to set or maintain.
• Few false alarms - the expected range is continuously checked against what actually happens (adaptive conformal inference), and how rare a deviation is comes from the metric's own history (extreme value theory), not a bell-curve assumption that breaks on real data.
• One threshold works everywhere - every anomaly gets a 0-100 score from how far, how long, and how persistent. A 90 means the same rarity on any metric, so you can rank and alert across metrics with a single cutoff.
• A level shift alerts once - when a metric permanently moves (a deploy, a config change), you get one "new normal" finding and the baseline re-anchors, not days of repeat alerts.
• Related alerts arrive as one incident - metrics that break together are grouped into a single finding, ordered by which moved first: a starting point for root cause.
• Built for streaming - O(1) per-sample updates, out-of-order tolerance, an opened/escalated/closed alert lifecycle with pluggable sinks, silent-metric detection, checkpoint/restore.
• Every alert explains itself - the expected range it broke, the score breakdown, what the model learned from which data, and the value that would not have alerted.

Quickstart

import pandas as pd
import tsanomaly as tsa

# any long frame with metric / timestamp / value columns
history = pd.read_csv("payments.csv", parse_dates=["ts"])

det = tsa.Detector.auto()
det.fit(history)                      # learn normal, per metric
result = det.detect(new_data)         # scored, explained anomalies

print(result.summary())
for anomaly in result.alerts(min_score=70):
    print(anomaly.explain().to_text())

Output (NYC taxi ridership around the January 2015 blizzard):

learned seasonality: day (strength 0.67), week (strength 0.84)

`nyc.taxi.passengers` dropped to 7076 (expected 15912.1 to 27621.4)
    for 30.5 h starting 2014-11-27 05:30 UTC - score 100.   # Thanksgiving
`nyc.taxi.passengers` dropped to 4729 (expected 17111.8 to 26890.1)
    for 9.5 h starting 2015-01-26 14:30 UTC - score 100.    # blizzard arrives
`nyc.taxi.passengers` dropped to 570 (expected 7971.81 to 24646.4)
    for 16.0 h starting 2015-01-27 06:00 UTC - score 100.   # blizzard travel ban

Examples

• quickstart.py
• cnc_vibration.py
• streaming_alerts.py
• traffic_incident.py
• root_cause.py
• gallery.py
• adaptive_envelopes.py

Documentation

• Usage guide - data formats, batch & streaming APIs, configuration, persistence, incidents, events, feedback, evaluation utilities.
• Architecture - the full pipeline.
• Examples

How it works

For more details, refer to docs/architecture.md.

Acknowledgements

The autonomous per-metric architecture is inspired by ideas in Anodot's published patents, implemented here with different, modern mechanisms - see the acknowledgements in docs/architecture.md.

License

Apache-2.0