PyRCA: metric-based root cause analysis for microservice teams

The metric search problem PyRCA was written to solve

PyRCA exists because microservice estates make manual root cause hunting expensive. The project starts from a plain observation: a multi-service application typically consists of hundreds of interacting services, so detecting a failure and then identifying what caused it becomes a search problem rather than a single alert. Root cause analysis methods usually work from KPI metrics, traces, or logs collected on those services, and the point is to hand engineers and SREs a shortlist instead of a wall of telemetry. PyRCA is a Python machine learning library from Salesforce Research that packages that search into analyzers you can call on a pandas dataframe. It is aimed at teams that already run metric pipelines, since the library expects historical metric series as input and an incident window of anomalous metrics as the trigger. It is not an observability agent. It does not scrape, store, or monitor your metrics for you, and it does not replace the pipeline that produced them.

Five analyzers split between parallel search and causal graphs

PyRCA supports five RCA methods, and they fall into two families that matter for how you feed the library. The first family identifies anomalous metrics in parallel with the observed anomaly through metric data analysis, and the project lists epsilon-diagnosis here. The second family works from a topology or causal graph that encodes causal relationships between metrics, and it covers Bayesian inference based RCA, Random Walk based RCA, Root Cause Discovery, and Hypothesis Testing based RCA. The choice between the families is not cosmetic, because the graph-based methods need a causal graph as part of their configuration. If you cannot say how metric A can lead to metric B, you are limited to the analysis-based route. The project description also notes that trace and log based RCA methods will be supported in the future, so today the library is metric-only by design rather than by omission. That statement sets the ceiling on what a PyRCA deployment can be expected to catch.

Installing sfr-pyrca, and the pins that come with it

Installation is a pip call, and the distribution name is not the repository name. The package on PyPI is published as sfr-pyrca while the project directory is PyRCA, so a mistaken name will fail to resolve. The project documentation gives three ways in. From PyPI the command is pip install sfr-pyrca. From a clone of the repository at its root, pip install . performs a source install, and pip install -e . installs in editable mode for a development checkout. Two extras widen the footprint. The plot extra pulls in the visualization stack that the causal graph dashboard needs, through pip install sfr-pyrca[plot] or pip install .[plot]. The all extra installs every dependency the project defines, through pip install sfr-pyrca[all] or pip install .[all]. setup.py pins Python to >=3.7,<4 and holds scikit-learn to >=0.24,<1.2, a ceiling worth noticing if a newer scikit-learn already runs in the same environment. The required install list also includes numpy, pandas, networkx, matplotlib, pyyaml, schema, pyparsing, dill, tqdm, packaging, and JPype1.

Training a BayesianNetwork against a metric causal graph

Every analyzer takes the same three inputs: the RCA method, a configuration object, and time series data. For a BayesianNetwork the configuration carries the causal graph, supplied as a pandas dataframe called graph_df, while df holds the historical metric series with a timestamp index and one column per monitored metric. Training looks like this.

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

The trained model is written to disk and loaded again when an incident arrives.

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

Look closely at the split of responsibility at that point. PyRCA does not decide which metrics are anomalous during the incident, it takes the list you pass in. The project points at the stats-based detector built into PyRCA and at detectors in the Merlion library for that step. So the practical pipeline is: detect anomalies, hand PyRCA the metric names, receive ranked root causes in a result object that exposes a dictionary form.

EpsilonDiagnosis takes history instead of a graph

Methods that do not need a causal graph take plain anomaly-free history. EpsilonDiagnosis is configured with an alpha threshold and trained on normal_data.

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

At incident time it is handed the abnormal_data collected in the incident window and returns the same kind of result object as the Bayesian analyzer.

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

The difference in inputs is worth internalizing. The Bayesian path needs a graph at configuration time and a list of metric names at inference time, while the epsilon-diagnosis path needs only time series. That makes it the lower-friction entry point for a team that has metric history but no causal model, and it is also the analyzer to reach for when you want to compare a graph-based score against a purely statistical one on the same incident.

The Dash dashboard replaces hand-revised causal graphs

Assembling the causal graph that BayesianNetwork and the other graph-based methods require used to be the most manual part of this work. The project ships a Dash application for it, launched by running python -m pyrca.tools from a shell, which opens a dashboard for time series analysis and causal discovery. Inside it you can compare causal discovery methods, tune their parameters, and add domain knowledge constraints such as root and leaf nodes, forbidden links, and required links. The generated graph can be visualized and, once you are satisfied with it, downloaded for use as the graph_df input. This is the part of the workflow that most deserves attention, because a causal graph is where the silent errors live. A missing edge removes a real propagation path, and an invented edge produces a root cause score with no basis in the running system. The dashboard shortens that loop; it does not verify the result. The dependency list backs this up, since the plot extra installs plotly, dash, dash_bootstrap_components, jupyter-dash, dash[diskcache], and dash_cytoscape, and setup.py ships dashboard assets as package data under pyrca/tools/dashboard/assets.

Where PyRCA stops, and how it differs from a hand-rolled ranker

The sharpest limitation is scope, and the project states it plainly: PyRCA at present focuses on metric-based RCA. Teams whose primary signal lives in traces or distributed logs get nothing from it, and the project lists trace and log based methods as future work rather than shipped features. A second constraint is the causal graph. Graph based analyzers can only rank what the graph permits, so a wrong edge propagates into every root cause score. Against the alternative most teams already have, a custom script that correlates metric deltas and ranks them by hand, the difference in approach is real. Such a script needs no causal model and no training step, and it can be tuned to a single service in minutes. What it cannot express is multi-hop causal paths, conditioning on a graph structure, or a controlled comparison of several methods on the same data. PyRCA also ships a benchmark for evaluating RCA methods, which is aimed at research and at anyone choosing between the five analyzers on their own data.

Release history, dependency ceiling, and the BSD-3-Clause footprint

PyRCA is distributed under BSD-3-Clause, a permissive license with no copyleft obligation, and setup.py records it as 3-Clause BSD. The LICENSE file in the repository root holds the full text, and reading it is your own step rather than advice from this page. The distribution declares itself zip_safe=False, so an install produces a regular directory rather than a single archive, Version 1.0.1 in setup.py matches the most recent tagged release, v1.0.1, published on 2023-06-27, preceded by v1.0.0 on 2023-05-18 and v0.0.1 on 2023-04-27. Those three releases landed inside two months, and nothing has been tagged since then. The last push was on 2026-06-02, so commits continued well after the last release, which means the 1.0.1 tag is not the newest state of the code. Because scikit-learn is capped below 1.2 and JPype1 is a required install, upgrading inside a modern environment means checking those pins before you plan the migration.

Editorial conclusion

Adopt PyRCA when you already hold clean metric time series and want ranked root causes from several analyzers on the same data. Skip it if your incident signal lives in traces or logs, or if you cannot supply a causal graph for the graph-based methods. Verify first that pip install sfr-pyrca resolves in your environment, because setup.py caps scikit-learn below 1.2 and requires Python >=3.7,<4, and check the released 1.0.1 line against the last push on 2026-06-02 before depending on a specific behavior.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. salesforce/PyRCA on GitHub