causalog 1.0.1

Intelligent Log Root Cause Analysis — one command opens a full React dashboard.

CausaLog 🔍

Intelligent Log Root Cause Analysis — one command, instant dashboard.

Quick start

pip install causalog
python -m spacy download en_core_web_sm

causalog run                     # auto-discovers .log/.json in current directory
causalog run /var/log/app.log    # explicit file
causalog run logs/               # scan a directory

Opens an interactive React dashboard at http://localhost:8000 showing:

• Dashboard — metric cards, system health timeline, AI insights, root cause hypotheses
• Analysis — full paginated log stream with filtering by level/service/keyword
• Clusters — grouped log clusters with severity, keywords, sparklines
• Timelines — area chart of errors/anomalies over time with spike markers and debug runbooks

Options

causalog run app.log --port 9000       # custom port
causalog run app.log --no-browser      # server only, no browser popup
causalog run app.log --no-server       # terminal report only
causalog run app.log --report out.json # also save a JSON report
causalog version

Windows install troubleshooting

If editable install fails with:

[WinError 32] ... python...\Scripts\causalog.exe is being used by another process

it means a running causalog process is locking the executable. Stop it first, then reinstall:

Get-CimInstance Win32_Process |
  Where-Object { $_.ExecutablePath -like "*\\Python314\\Scripts\\causalog.exe" } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

python -m pip install -e .

Tip: always use python -m pip ... to ensure you are installing into the same Python interpreter.

How it works

Log file upload
      ↓
Preprocessing    (Pandas + Regex) — parse timestamps, levels, services
      ↓
NLP Extraction   (spaCy)          — extract keywords from messages
      ↓
Clustering       (TF-IDF+KMeans)  — group similar log entries
      ↓
Anomaly Detection(IsolationForest)— flag statistically unusual entries
      ↓
Ontology Mapping (keyword→cause)  — map to root cause categories
      ↓
RCA Engine       (rule-based)     — frequency + per-error details
      ↓
Intelligence Layer               — hypotheses, confidence scores,
                                   temporal trend analysis,
                                   actionable debug suggestions
      ↓
React Dashboard  (FastAPI + CDN)  — live, connected, no npm needed

Requirements

• Python ≥ 3.9
• spaCy English model: python -m spacy download en_core_web_sm

Stack

Layer	Technology
Backend API	FastAPI + Uvicorn
Frontend	React 18 + Recharts (CDN, no npm)
ML/NLP	scikit-learn, spaCy
Data	Pandas, NumPy

License

MIT