atlas-incident 0.1.1

Deterministic, rule-based incident analysis and RCA system

ATLAS — Deterministic Incident Analysis & RCA (CLI)

ATLAS is a pip-installable CLI tool for deterministic incident analysis and root cause analysis (RCA). It ingests real production logs and produces explainable JSON reports with classification, root cause, and concrete actions — without AI/ML.

Audience: SREs, DevOps, Platform engineers. Guarantee: Same input → same output. Auditable rules. Zero black boxes.

---

Why ATLAS?

Most incident tools rely on black‑box AI or heuristics that cannot be trusted under pressure. ATLAS takes the opposite approach:

• 🔒 Zero‑AI (no LLMs, no ML, no embeddings)
• 🧠 Fully deterministic (same input → same output)
• 🧾 Explainable decisions (rule‑based logic)
• 🧪 100% testable core pipeline
• ⚙️ Real‑world workflow (file‑based CLI + JSON output)

---

What ATLAS Does

1. Parses raw production logs
2. Normalizes them into a canonical incident schema
3. Classifies the incident (DB, Network, Auth, etc.)
4. Infers probable root cause via rule chains
5. Suggests concrete remediation actions
6. Persists incident history for audit & comparison

---

High‑Level Architecture

flowchart TD
    A[Log File] --> B[Log Parsing Engine]
    B --> C[Incident Normalization]
    C --> D[Rule‑Based Classification]
    D --> E[Root Cause Analysis]
    E --> F[Recommendation Engine]
    F --> G[Final JSON Report]
    G --> H[Incident History (JSONL)]

---

Directory Structure

atlas/
├── atlas/
│   ├── cli/              # CLI entry point (file‑based)
│   ├── parsing/          # Log parsing engine
│   ├── normalization/    # Incident normalization
│   ├── classification/   # Rule‑based classifier
│   ├── rca/              # Root cause analysis engine
│   ├── recommendations/ # Action / remediation engine
│   ├── history/          # Incident persistence (JSONL)
│   ├── orchestrator/     # Pipeline orchestration
│   ├── io/               # JSON I/O helpers
│   ├── schemas/          # Shared data contracts
│   └── __main__.py       # `python -m atlas`
│
├── tests/                # pytest test suite
├── output/               # Generated reports (optional)
├── incident_history.jsonl# Append‑only incident history
├── README.md
└── pyproject.toml

---

Install (PyPI)

pip install atlas-incident

Run:

atlas <log_file> <service> <environment>

---

Usage (Real‑World Workflow)

1️⃣ Create a production‑like log file

2024-10-12T09:14:01Z INFO  payments-api Starting service
2024-10-12T09:14:05Z INFO  payments-api Connected to postgres
2024-10-12T09:15:22Z WARN  payments-api Slow query detected
2024-10-12T09:16:10Z ERROR payments-api Database connection timeout
2024-10-12T09:16:15Z ERROR payments-api Retries exhausted

2️⃣ Run ATLAS

python -m atlas prod_payments.log payments-api prod

3️⃣ Example Output (JSON)

{
  "service": "payments-api",
  "environment": "prod",
  "severity": "HIGH",
  "category": "DATABASE",
  "root_cause": "Connection pool exhausted",
  "actions": [
    "Increase database connection pool size",
    "Restart affected service",
    "Monitor latency for 15 minutes"
  ],
  "confidence": 1.0
}

---

Incident History (Persistence)

Each run is appended to incident_history.jsonl:

{"service":"payments-api","environment":"prod","severity":"HIGH","category":"DATABASE","root_cause":"Connection pool exhausted",...}

• Append‑only
• Audit‑friendly
• Replayable for future analysis

---

Testing

Run the full test suite:

pytest -v

All core modules are covered with deterministic tests.

---

Design Principles

• Determinism over intelligence
• Rules over models
• Schemas over guesses
• Clarity over cleverness
• Production realism over demos

---

Future Scope

ATLAS is intentionally minimal and deterministic. Potential future extensions include:

• Configurable rule sets (YAML-based)
• Additional log format parsers (NGINX, Kubernetes, Cloud logs)
• Enhanced similarity matching using statistical techniques (still non-AI)
• Optional output formats (Markdown / HTML reports)
• Integration hooks for alerting or ticketing systems

Any future additions will preserve ATLAS’s core principles: determinism, explainability, and zero-AI design.

---

License

This project is licensed under the MIT License, which permits use, modification, and distribution for both personal and commercial purposes.

ATLAS is provided “as is”, without warranty of any kind. It is suitable for learning, internal tooling, and experimental production use where deterministic and explainable behavior is required.