The-AnkitPatel/otel-trace-gnn

TraceGNN: OpenTelemetry Microservice Root-Cause Localizer

Model Overview

TraceGNN is a directed Graph Attention Network (GAT) trained on distributed trace directed acyclic graphs (DAGs) generated by OpenTelemetry collectors in Kubernetes environments.

When microservices experience failures, latency propagation and retry amplification often make upstream callers appear slower or more erratic than the actual failing callee. TraceGNN aggregates multi-dimensional node telemetry (duration, self-time, CPU/memory saturation, queue delay, retries, error status) across caller-to-callee edges to pinpoint the root-cause service with 98.4% Top-1 accuracy in under 0.2 milliseconds.

• Author: Ankit Kumar Patel
• Testbed: Distributed Systems & Telemetry Lab, IIT Roorkee
• Open Source: Upstream Contributor, Cloud Native Computing Foundation (CNCF OpenTelemetry-Go)
• Framework: PyTorch (TorchScript / ONNX exportable)
• License: Apache 2.0

Performance on Held-Out Test Set (N = 1,500 Traces)

Metric	TraceGNN	Baseline (Max Duration Heuristic)	Baseline (Random Forest)
Top-1 Root Cause Accuracy	98.40%	64.20%	78.50%
F1 Score	0.978	0.612	0.741
Precision	0.965	0.580	0.730
Recall	0.992	0.648	0.752
ROC-AUC	0.994	0.720	0.886
p50 CPU Latency	0.18 ms	0.05 ms	1.45 ms
p99 CPU Latency	0.31 ms	0.09 ms	2.80 ms

Quickstart

import torch
from huggingface_hub import hf_hub_download

# Download weights
model_file = hf_hub_download(
    repo_id="The-AnkitPatel/otel-trace-gnn",
    filename="trace_gnn_model.pt"
)

checkpoint = torch.load(model_file, map_location="cpu", weights_only=False)
print("Model loaded successfully. Architecture:", checkpoint["hidden_dim"], "hidden units, 4 attention heads.")

Citation

@article{patel2026tracegnn,
  title   = {Root-Cause Localization in Distributed Microservice Traces via Directed Graph Attention Networks},
  author  = {Patel, Ankit Kumar},
  journal = {Distributed Systems & Telemetry Lab, IIT Roorkee},
  year    = {2026}
}