PyRCA：用于根本原因分析的 Python 库

目录

1. 简介
2. 安装
3. 快速入门
4. 文档
5. 教程
6. 应用示例
7. 基准测试
8. 如何贡献

简介

微服务架构的应用正以迅猛的速度增长，多服务应用程序已成为现实世界 IT 应用中的标准范式。通常，一个多服务应用程序由数百个相互协作的服务组成，这使得检测服务故障并确定其根本原因变得越来越困难。根本原因分析（RCA）方法通常依赖于在这些服务上监控的关键绩效指标、跟踪数据或日志，以便在检测到系统故障时确定根本原因。此类方法可以帮助工程师和 SRE 在故障排除过程中提高效率。

PyRCA 是一个基于 Python 的机器学习库，旨在通过提供多种最先进的 RCA 算法以及构建 RCA 解决方案的端到端流程，来促进根本原因分析工作。目前，PyRCA 主要专注于基于指标的 RCA，包括两类算法：(1) 通过指标数据分析，在观察到异常的同时识别出异常指标，例如 ε-诊断；(2) 基于表示观测指标之间因果关系的拓扑图或因果图来识别根本原因，例如贝叶斯推断和随机游走。PyRCA 还提供了一个便捷的工具，用于从观测的时间序列数据和领域知识中构建因果图，使用户能够快速开发基于图的解决方案。此外，PyRCA 提供了一个用于评估各种 RCA 方法的基准测试，这对工业界和学术研究都具有重要价值。

以下列出了我们库中支持的 RCA 方法：

1. ε-诊断
2. 基于贝叶斯推断的 RCA（BI）
3. 基于随机游走的 RCA（RW）
4. 根因发现方法（RCD）
5. 基于假设检验的 RCA（HT）

我们将继续改进这个库，使其在未来更加全面。未来，PyRCA 还将支持基于跟踪和日志的 RCA 方法。

安装

您可以通过运行 pip install sfr-pyrca 从 PyPI 安装 pyrca。您也可以从源代码安装：克隆 PyRCA 仓库，进入根目录，然后运行 pip install .，或者使用 pip install -e . 以可编辑模式安装。您还可以安装额外的依赖项：

• 用于绘图与可视化：运行 pip install sfr-pyrca[plot]，或从仓库根目录运行 pip install .[plot]。
• 安装所有依赖项：运行 pip install sfr-pyrca[all]，或从仓库根目录运行 pip install .[all]。

快速入门

PyRCA 提供了一个统一的接口，用于训练 RCA 模型和查找根本原因。要应用某种 RCA 方法，您只需指定：

• 所选的 RCA 方法：例如，BayesianNetwork、EpsilonDiagnosis。
• 方法配置：例如，BayesianNetworkConfig、EpsilonDiagnosisConfig。
• 用于初始化/训练的时间序列数据：例如，一个 Pandas DataFrame 格式的时间序列数据。
• 事件窗口中的异常时间序列数据：RCA 方法需要事件窗口内的异常 KPI 指标。

我们以 BayesianNetwork 为例。假设 graph_df 是表示指标之间因果关系的图的 Pandas DataFrame（如何构建此类因果图将在稍后讨论），而 df 是包含历史观测时间序列数据的 Pandas DataFrame（例如，索引为时间戳，每列代表一个被监控的指标）。要训练一个 BayesianNetwork，您可以简单地运行以下代码：

from pyrca.analyzers.bayesian import BayesianNetwork
model = BayesianNetwork(config=BayesianNetwork.config_class(graph=graph_df))
model.train(df)
model.save("model_folder")

模型训练完成后，您可以使用它来查找由某个异常检测器检测到的一组异常指标所对应的事件的根本原因（您可以使用 PyRCA 中支持的基于统计的检测器，或我们 Merlion 库中支持的其他异常检测方法），例如：

from pyrca.analyzers.bayesian import BayesianNetwork
model = BayesianNetwork.load("model_folder")
results = model.find_root_causes(["observed_anomalous_metric", ...])
print(results.to_dict())

对于其他 RCA 方法，您可以编写与上述类似的代码来查找根本原因。例如，如果您想尝试 EpsilonDiagnosis，可以按如下方式初始化 EpsilonDiagnosis：

from pyrca.analyzers.epsilon_diagnosis import EpsilonDiagnosis
model = EpsilonDiagnosis(config=EpsilonDiagnosis.config_class(alpha=0.01))
model.train(normal_data)

这里，normal_data 是历史上观测到的无异常的时间序列数据。要识别根本原因，您可以运行：

results = model.find_root_causes(abnormal_data)
print(results.to_dict())

其中，abnormal_data 是在事件窗口内收集的时间序列数据。

如上所述，某些 RCA 方法（如 BayesianNetwork）需要将因果图作为输入。要从观测到的时间序列数据中构建此类因果图，您可以使用我们的工具，运行 python -m pyrca.tools。该命令将启动一个用于时间序列数据分析和因果发现的 Dash 应用程序。

该仪表板使用户能够尝试不同的因果发现方法、自定义因果发现参数、添加领域知识约束（例如根节点/叶节点、禁止/必须存在的边），并可视化生成的因果图。此功能简化了基于领域知识手动修订因果图的过程。如果用户对工具生成的图满意，可以将其下载下来，随后该图可被 PyRCA 支持的 RCA 方法使用。

或者，用户也可以不使用仪表板，而是直接编写代码来构建此类图。包 pyrca.graphs.causal 包含了几种流行的因果发现方法，用户可以加以利用。所有这些方法都支持领域知识约束。例如，如果用户希望在观测到的时间序列数据 df 上应用 PC 算法来构建因果图，可以使用以下代码：

from pyrca.graphs.causal.pc import PC
model = PC(PC.config_class())
graph_df = model.train(df)

如果您有一些领域知识约束，可以运行：

from pyrca.graphs.causal.pc import PC
model = PC(PC.config_class(domain_knowledge_file="file_path"))
graph_df = model.train(df)

领域知识文件采用 YAML 格式，例如：

causal-graph:
  root-nodes: ["A", "B"]
  leaf-nodes: ["E", "F"]
  forbids:
    - ["A", "E"]
  requires: 
    - ["A", "C"]

该领域知识文件说明：

1. 指标 A 和 B 必须是根节点，
2. 指标 E 和 F 必须是叶节点，
3. A 和 E 之间不能有连接，
4. A 和 C 之间必须存在连接。

您可以根据此模板编写自己的领域知识文件，以生成更可靠的因果图。

应用示例

这里是一个将 BayesianNetwork 应用于构建 RCA 解决方案的真实世界示例，该示例改编自我们的内部用例。其中，“config”文件夹包含基于统计的异常检测器的设置以及领域知识；“models”文件夹则存储因果图和训练好的贝叶斯网络。“rca.py”文件中的 RCAEngine 类实现了利用 PyRCA 提供的模块来构建因果图、训练贝叶斯网络以及查找根本原因的方法。如果基于统计的异常检测器和贝叶斯推理适合您的问题，您可以直接使用该类。例如，给定一个时间序列 DataFrame df，您可以通过以下代码构建并训练一个贝叶斯网络：

from pyrca.applications.example.rca import RCAEngine
engine = RCAEngine()
engine.build_causal_graph(
    df=df,
    run_pdag2dag=True,
    max_num_points=5000000,
    verbose=True
)
bn = engine.train_bayesian_network(dfs=[df])
bn.print_probabilities()

贝叶斯网络构建完成后，您可以直接用它来查找根本原因：

engine = RCAEngine()
result = engine.find_root_causes_bn(anomalies=["conn_pool", "apt"])
pprint.pprint(result)

find_root_causes_bn 的输入是一组由基于统计的异常检测器检测到的异常指标。该方法会估计某个节点成为根本原因的概率，并提取从潜在的根本原因节点到叶节点的路径。

基准测试

下表总结了不同方法在模拟数据集上的根因分析性能。
如何生成模拟数据集可以参见这里，
而如何测试不同的根因分析方法则可以参见这里。

ε-Diagnosis 和 RCD 属于单阶段的根因分析方法，而其余方法均为双阶段的根因分析方法。
Local-RCD 表示采用局部学习的 RCD 算法。Bayesian Inference 算法通过估计每个结构因果模型来计算根因得分。Hypothesis-testing (ADJ) 表示带有后代调整的假设检验算法。对于双阶段模型，未带后缀的算法表示根因定位算法使用真实因果图进行模型训练。而带有“PC”后缀的算法则表示因果图是通过 PC 算法估计得到的。

如何贡献

我们欢迎开源社区为改进本库做出贡献！
在开始之前，请先克隆本仓库，运行 pip install pre-commit，并在仓库的根目录下执行 pre-commit install。这将确保您每次提交时，所有文件都格式正确，并包含适当的许可证头信息。

要向本库添加新的根因分析方法，您可以按照以下步骤操作：

1. 在 pyrca/analyzers 文件夹中为该根因分析方法创建一个新的 Python 脚本文件。
2. 创建一个继承自 pyrca.base.BaseConfig 的配置类。
3. 创建一个继承自 pyrca.analyzers.base.BaseRCA 的方法类。新方法的构造函数应以新的配置实例作为输入。
4. 实现 train 函数，用于训练或初始化新方法。
5. 实现 find_root_causes 函数，该函数应返回一个 pyrca.analyzers.base.RCAResults 实例，用于存储根因分析结果。

要添加新的因果发现方法，您可以按照以下步骤操作：

1. 在 pyrca/graphs/causal 文件夹中为该因果发现方法创建一个新的 Python 脚本文件。
2. 创建一个继承自 pyrca.graphs.causal.base.CausalModelConfig 的配置类。
3. 创建一个继承自 pyrca.graphs.causal.base.CausalModel 的方法类。新方法的构造函数应以新的配置实例作为输入。
4. 实现 _train 函数，该函数应返回发现的因果图。_train 函数的输入参数包括时间序列数据框、禁止和必须存在的边列表以及其他附加参数。

联系我们

如果您有任何问题、意见或建议，请随时通过 pyrca@salesforce.com 与我们联系。

许可证

BSD 3-Clause 许可证

PyRCA 快速上手指南

PyRCA 是一个用于根因分析（Root Cause Analysis, RCA）的 Python 机器学习库，专为微服务架构设计。它提供多种先进的算法（如贝叶斯推断、随机游走、ε-Diagnosis 等），帮助工程师通过指标数据快速定位系统故障的根本原因。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.7, 3.8 或 3.9
• 前置依赖：
  • pandas：用于处理时间序列数据
  • numpy：数值计算基础
  • （可选）绘图依赖：若需使用可视化功能，需安装额外绘图库

提示：国内用户建议使用清华源或阿里源加速安装过程。

安装步骤

您可以通过 PyPI 直接安装，也可以从源码安装。

方式一：通过 PyPI 安装（推荐）

使用 pip 安装核心库：

pip install sfr-pyrca -i https://pypi.tuna.tsinghua.edu.cn/simple

若需要绘图与可视化功能：

pip install "sfr-pyrca[plot]" -i https://pypi.tuna.tsinghua.edu.cn/simple

若需要安装所有依赖：

pip install "sfr-pyrca[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

克隆仓库并进入根目录：

git clone https://github.com/salesforce/PyRCA.git
cd PyRCA

安装为可编辑模式（适合开发者）：

pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

PyRCA 提供了统一的接口来训练模型和查找根因。以下以 贝叶斯网络 (BayesianNetwork) 为例，展示最简化的工作流程。

1. 准备数据

假设您有一个包含历史监控指标的 Pandas DataFrame (df)，索引为时间戳，列为各项指标。同时假设您已有一个表示因果关系的图数据 (graph_df)。

2. 训练模型

初始化模型配置并训练：

from pyrca.analyzers.bayesian import BayesianNetwork

# 初始化模型，传入因果图配置
model = BayesianNetwork(config=BayesianNetwork.config_class(graph=graph_df))

# 使用历史正常数据进行训练
model.train(df)

# 保存模型
model.save("model_folder")

3. 查找根因

加载训练好的模型，并输入检测到的异常指标列表进行根因分析：

from pyrca.analyzers.bayesian import BayesianNetwork

# 加载模型
model = BayesianNetwork.load("model_folder")

# 输入检测到的异常指标列表
results = model.find_root_causes(["observed_anomalous_metric", "another_metric"])

# 输出结果
print(results.to_dict())

进阶：构建因果图

如果您的场景没有现成的因果图，可以使用 PyRCA 内置工具基于时间序列数据自动生成。

方法 A：使用命令行可视化工具（推荐） 运行以下命令启动 Dash 应用，通过界面交互式生成因果图：

python -m pyrca.tools

方法 B：代码自动生成 使用 PC 算法自动构建因果图：

from pyrca.graphs.causal.pc import PC

model = PC(PC.config_class())
graph_df = model.train(df)

若需加入领域知识约束（如指定根节点、禁止某些连接），可创建 YAML 配置文件并在 config_class 中指定 domain_knowledge_file 路径。