luminol, 异常检测与相关库

概述

发光氨是用于时间序列数据分析的重量轻 python 库。 它支持的两个主要功能是异常检测和相关性。 它可以用于调查异常的可能原因。 收集时间系列数据和可以：

• 给定一个时间序列，检测数据是否包含异常，并给出异常的时间戳。
• 给出两个时间序列，帮助找出它们的相关系数。 由于相关机制允许移动间隔，你可以以将两个峰值相关联的两个峰相关联。

to是可以配置的，你可以以在某种意义上选择你想要用于异常检测或者相关的特定算法。 另外，库不依赖于时间序列值的任何预定义阈值。 相反，它将每个数据点分配一个异常分数，并使用分数标识异常。

通过使用库，我们可以为 root 原因分析建立逻辑流。 例如假定网络延迟有一个峰值：

• 异常检测发现网络延迟时间序列中的峰值
• 获取异常的异常周期，并与其他系统指标( GC，IO，CPU，等等 ) 关联在同一时间范围内
• 获得相关度量的排列列表，root 原因候选人可以能在顶部。

研究自动化 root 原因分析的可能方法是我们开发这个库的主要原因之一，它将成为未来工作的基础部分。

安装

确保你有 python，pip，numpy，并直接通过pip安装：

pip install luminol

图书馆最常用的版本是 0.4.

快速启动

这是用于时间序列分析的快速入门指南。

• 导入库

import luminol

• 对单个时间序列进行异常检测。

detector = luminol.anomaly_detector.AnomalyDetector(ts)
anomalies = detector.get_anomalies()

• 如果存在异常，则将第一个异常周期与第二时间序列ts2关联。

if anomalies:
 time_period = anomalies[0].get_time_window()
 correlator = luminol.correlator.Correlator(ts, ts2, time_period)

• 打印相关系数

print(correlator.get_correlation_result().coefficient)

这些都是发光氨的简单使用。 有关参数类型，返回类型和可选参数的信息，请参见 API 。

模块

中的模块是指为更好的数据表示而开发的定制类，它们是 Anomaly 。CorrelationResult 和 TimeSeries 。

类 luminol.modules.anomaly 异常
它包含以下属性：

self.start_timestamp: # epoch seconds represents the start of the anomaly period.self.end_timestamp: # epoch seconds represents the end of the anomaly period.self.anomaly_score: # a score indicating how severe is this anomaly.self.exact_timestamp: # epoch seconds indicates when the anomaly reaches its severity.

它有以下 public 方法：

• get_time_window(): 返回元组( start_timestamp，end_timestamp ) 。

类 luminol.modules.correlation_result CorrelationResult
它包含以下属性：

self.coefficient: # correlation coefficient.self.shift: # the amount of shift needed to get the above coefficient.self.shifted_coefficient: # a correlation coefficient with shift taken into account.

类 luminol.modules.time_series

__init__(self, series)

• series(dict): 时间戳-> 值

它有多种操作时间序列的便捷方法，包括生成器 iterkeys 。itervalues 和 iteritems 。 它还支持二进制运算，如加和减。 请参考代码和内联注释以获得更多信息。

API

库包含两个类： AnomalyDetector 和 Correlator，有两组 api，每个类对应一个。 还有定制的模块来更好地表示数据。 在本文中，当你遍历api时，本文档中的模块部分可能提供有用的信息。

类 luminol.anomaly_detector AnomalyDetecor

__init__(self, time_series, baseline_time_series=None, score_only=False, score_threshold=None,
 score_percentile_threshold=None, algorithm_name=None, algorithm_params=None,
 refine_algorithm_name=None, refine_algorithm_params=None)

• time_series: 你要对它的进行异常检测的度量。 它可以有以下三种类型：

1. string: # path to a csv file2. dict: # timestamp -> value3. lumnol.modules.time_series.TimeSeries

• baseline_time_series: 上面提到的类型的可选基线时间序列。
• score only(bool): 如果断言，时间序列的异常分数将可以用，而异常期间将不会被识别。
• score_threshold: 如果通过，这个值上的异常分数将被标识为异常。 它可以覆盖 score_percentile_threshold 。
• score_precentile_threshold: 如果通过，这百分比上方的异常分数将被标识为异常。 它不能覆盖 score_threshold 。
• algorithm_name(string): 如果传递，将使用特定算法计算异常分数。
• algorithm_params(dict): algorithm_name指定的算法的附加参数。
• refine_algorithm_name(string): 如果传递，特定算法将用于计算每个异常周期内严重性的时间戳。
• refine_algorithm_params(dict): refine_algorithm_params指定的算法的附加参数。

可用的算法及其附加参数包括：

1. 'bitmap_detector': # behaves well for huge data sets, and it is the default detector. {
 'precision'(4): # how many sections to categorize values,'lag_window_size'(2% of the series length): # lagging window size,'future_window_size'(2% of the series length): # future window size,'chunk_size'(2): # chunk size. }2. 'default_detector': # used when other algorithms fails, not meant to be explicitly used.3. 'derivative_detector': # meant to be used when abrupt changes of value are of main interest. {
 'smoothing factor'(0.2): # smoothing factor used to compute exponential moving averages# of derivatives. }4. 'exp_avg_detector': # meant to be used when values are in a roughly stationary range.# and it is the default refine algorithm. {
 'smoothing factor'(0.2): # smoothing factor used to compute exponential moving averages.'lag_window_size'(20% of the series length): # lagging window size.'use_lag_window'(False): # if asserted, a lagging window of size lag_window_size will be used. }

上面某些参数的含义似乎有些模糊。 以下是一些有用的见解：

• 位图控件
• 指数移动 Avg

AnomalyDetector 类具有以下 public 方法：

• get_all_scores(): 返回异常评分时间序列，类型为 TimeSeries 。
• get_anomalies(): 返回一个异常对象列表。

类 luminol.correlator 相关器

__init__(self, time_series_a, time_series_b, time_period=None, use_anomaly_score=False,
 algorithm_name=None, algorithm_params=None)

• time_series_a: 时序，请参考上面的time_series以获取 AnomalyDetector 。
• time_series_b: 时序，请参考上面的time_series以获取 AnomalyDetector 。
• time_period(tuple): 将两个时间序列关联在一起的时间段。
• use_anomaly_score(bool): 如果断言，时间序列的异常分数将用于计算时间序列中原始数据的相关系数。
• algorithm_name: 如果通过，则使用特定的算法来计算相关系数。
• algorithm_params: algorithm_name指定的算法的任何附加参数。

可用的算法及其附加参数包括：

1. 'cross_correlator': # when correlate two time series, it tries to shift the series around so that it# can catch spikes that are slightly apart in time. {
 'max_shift_seconds'(60): # maximal allowed shift room in seconds,'shift_impact'(0.05): # weight of shift in the shifted coefficient. }

相关类具有以下 public 方法：

• get_correlation_result(): 返回 CorrelationResult 对象。
• is_correlated(threshold=0.7): 如果超过阈值的系数，返回一个 CorrelationResult对象。 否则，return false 。

示例

• 计算异常分数。

from luminol.anomaly_detector import AnomalyDetector
ts = {0: 0, 1: 0.5, 2: 1, 3: 1, 4: 1, 5: 0, 6: 0, 7: 0, 8: 0}
my_detector = AnomalyDetector(ts)
score = my_detector.get_all_scores()for timestamp, value in score.iteritems():
 print(timestamp, value)""" Output:0 0.01 0.8731282501312 1.571630850243 2.136336863344 1.709069490675 2.905418134156 1.171541109357 0.9372328874798 0.749786309983"""

• 将ts1与ts2关联在每个异常中。

from luminol.anomaly_detector import AnomalyDetectorfrom luminol.correlator import Correlator
ts1 = {0: 0, 1: 0.5, 2: 1, 3: 1, 4: 1, 5: 0, 6: 0, 7: 0, 8: 0}
ts2 = {0: 0, 1: 0.5, 2: 1, 3: 0.5, 4: 1, 5: 0, 6: 1, 7: 1, 8: 1}
my_detector = AnomalyDetector(ts1, score_threshold=1.5)
score = my_detector.get_all_scores()
anomalies = my_detector.get_anomalies()for a in anomalies:
 time_period = a.get_time_window()
 my_correlator = Correlator(ts1, ts2, time_period)
 if my_correlator.is_correlated(threshold=0.8):
 print("ts2 correlate with ts1 at time period (%d, %d)"% time_period)""" Output:ts2 correlates with ts1 at time period (2, 5)"""

克隆源并安装软件包和开发要求：

pip install -r requirements.txt
pip install pytest pytest-cov pylama

测试和linting运行：

python -m pytest --cov=src/luminol/src/luminol/tests/
python -m pylama -i E501 src/luminol/