Syscope 🩺

A Linux System Diagnostics & Root-Cause Analysis Tool

Syscope is a lightweight, snapshot-based Linux system diagnostics tool focused on root-cause analysis, not raw metrics.

Instead of continuously monitoring your system, syscope takes a one-shot snapshot, analyzes CPU, memory, disk, network, and services, and produces:

• a primary cause
• contributing factors
• actionable recommendations
• a confidence score
• meaningful exit codes for scripting

---

Features

• CPU analysis

  • Load averages
  • Per-process CPU usage
  • Context switching rate
  • PSI-aware CPU pressure detection (graceful fallback)

• Memory analysis

  • Memory PSI (some/full stalls)
  • Swap activity (pswpin / pswpout)
  • Near-OOM detection

• Disk I/O diagnostics

  • Diskstats read/write activity
  • Disk I/O saturation
  • PSI-aware I/O pressure

• Network diagnostics

  • Packet drops
  • TCP retransmissions
  • RX/TX throughput

• Service inspection

  • Memory-heavy services
  • RSS, swap usage, thread count
  • Top offenders highlighted

• Unified diagnosis engine

  • Primary cause detection
  • Secondary contributors
  • Confidence scoring (High / Medium / Low)

• Actionable recommendations

  • Tailored advice per subsystem
  • Safe, non-destructive suggestions

---

Design Philosophy

• Signal-based, not noise-based
• No daemon, no background service
• No root required
• Safe on all modern Linux distributions
• Graceful degradation on older kernels
• Fast, deterministic, one-shot execution

---

Requirements

• Linux kernel ≥ 4.20 for full PSI support
  (older kernels work with reduced diagnostics)
• C++17 compatible compiler
• /proc filesystem available

---

Installation

From AUR (Arch Linux)

Prebuilt binary package:

yay -S syscope-bin

Manual AUR build:

git clone https://aur.archlinux.org/syscope-bin.git
cd syscope-bin
makepkg -si

Build from source

git clone https://github.com/ashvin-to/syscope.git
cd syscope

g++ -std=c++17 \
    main.cpp core/*.cpp engine/*.cpp \
    -o syscope \
    -I. -pthread

Usage

syscope [options]

Syscope runs once, analyzes the system, prints results, and exits.

Command-line Options

Option	Description
--help, -h	Show help and exit
--verbose	Show full diagnostics, evidence, and recommendations
--quiet	Show only primary cause and confidence
--json	Output machine-readable JSON

JSON Output

Syscope can emit structured JSON for automation:

syscope --json

Example:

{
  "primary": "Minor performance fluctuations detected",
  "confidence": "low",
  "issues": [
    {
      "summary": "Very memory-heavy services detected",
      "score": 30
    }
  ]
}

Useful for:

• scripts
• cron jobs
• CI pipelines
• system health checks

Exit Codes

Syscope exits with meaningful status codes:

Code	Meaning
0	System healthy
1	Degraded performance
2	Potential system issue detected

Example:

syscope --quiet
echo $?

Project Structure

├── core/
│   ├── cpu.cpp        # CPU metrics, PSI, processes
│   ├── memory.cpp     # Memory pressure, swap
│   ├── disk.cpp       # Disk I/O and PSI
│   ├── network.cpp    # Packet loss, retransmissions
│   ├── services.cpp   # Memory-heavy services
│   └── utils.cpp      # Shared helpers (PSI detection, etc.)

├── engine/
│   ├── analyzer.cpp   # Aggregates subsystem results
│   ├── analyzer.h
│   ├── verdict.cpp    # Final verdict & confidence logic
│   └── verdict.h

├── main.cpp           # CLI, argument parsing, output
└── system.h           # Shared data structures

Configuration

Syscope currently uses no external configuration files. All thresholds are intentionally conservative and hardcoded for safety.

Contributing

Contributions are welcome! If you have suggestions for improvements, bug fixes, or new features, please feel free to open an issue or submit a pull request on the GitHub repository.

License

GNU General Public License v3.0 (GPL-3.0)

See the LICENSE file for details.

Author

• ashvin-to - https://github.com/ashvin-to