Argus

One CLI for all JVM diagnostics. 71 commands, zero agent required, works on Java 11+. The free alternative to GCEasy + jcmd + VisualVM + Arthas + Eclipse MAT combined — GC analysis, health diagnosis, flame graphs, async-profiler integration, MAT-class heap leak analysis, continuous profiling, distributed-tracing correlation, opt-in live method instrumentation, ZGC live monitoring, and CI/CD profile gates.

---

Quick Start

# Install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/rlaope/argus/master/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/rlaope/argus/master/install.ps1 | iex

argus doctor <pid>              # One-click JVM health diagnosis
argus zgc <pid>                 # ZGC live diagnosis (30s JFR capture + verdict)
argus profile <pid> --duration=30  # CPU/allocation profiling via async-profiler

Shell completions (bash, zsh, fish, PowerShell) are installed automatically.

---

JVM Harness

Continuous JVM monitoring + optimization + troubleshooting on top of Argus, available as a Claude Code plugin.

/plugin marketplace add https://github.com/rlaope/Argus
/plugin install argus-jvm-harness

CLI equivalent (no Claude Code required):

argus harness <pid>                          # 30-min trend-aware health watch
argus harness <pid> --profile=quick --duration=1m
argus harness <pid> --out=session.json --format=json

The harness samples on a fixed interval, runs the doctor rule set plus four trend rules (heap-leak regression, GC overhead trend, thread growth, pause-time regression), and produces a single session report with severity-ranked findings and JVM-flag suggestions.

Full reference: docs/harness.md

---

Why Argus?

One CLI to diagnose a live JVM and watch a fleet — no agent, no restart, no -javaagent. It attaches externally over jcmd/JMX and reads the JVM right where it runs.

• Zero-install live attach — point it at a PID; the target needs no restart and no agent flag.
• One-command health verdict — argus doctor returns HEALTHY / WARN / CRITICAL with machine-readable exit codes for CI gates.
• MAT-class heap analysis, offline — dominator tree, retained sizes, and automated leak suspects on multi-GB dumps within a bounded heap.
• Continuous profiling, no TSDB — disk-backed per-pod CPU/alloc flamegraphs with time-window merges and differential views.
• GC ↔ trace correlation — see which traces a GC pause stalled, exported as OTel spans and Prometheus exemplars.
• Opt-in live instrumentation — watch/trace/monitor method args, returns, and timing via dynamic attach; default OFF, auto-detach, zero residual bytecode.
• JVM right-sizing for FinOps — argus rightsize recommends -Xmx and container memory from observed heap high-water-mark and GC headroom.
• GC-aware verdicts & Loom — argus g1 / argus zgc flag allocation stalls, cycle overlap, and SoftMax breaches; virtual-thread pinning detection on Java 21+.
• OpenTelemetry-native — OpenMetrics /prometheus, OTLP export, and a shipped Grafana dashboard.

71 commands in total — full reference: docs/cli-commands.md

---

Roadmap At A Glance

Argus keeps the fast single-PID JVM workflow at the center, then layers standard metrics, traces, profiles, dashboards, fleet views, and APM-grade service workflows around it.

---

Example: argus doctor <pid>

$ argus doctor 39113

╭─ Health Diagnosis ── pid:39113 ─────────────────────────────────────────────╮
│                                                                              │
│  ✅  Heap usage normal       41M / 256M  (16%)                               │
│  ✅  GC overhead acceptable  0.3%                                            │
│  ✅  No deadlocks detected                                                   │
│  ✅  Thread count normal     29 threads                                      │
│  ⚠   Metaspace near limit   96.5% — consider -XX:MaxMetaspaceSize           │
│  ⚠   Old Gen elevated        41.8% — monitor for promotion pressure         │
│                                                                              │
│  Overall: WARN — 2 recommendations                                           │
│                                                                              │
│  Tuning Tips                                                                 │
│  → Add -XX:MaxMetaspaceSize=256m to prevent unlimited growth                 │
│  → Run argus gclog <file> to analyze GC pressure over time                  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Exit codes are machine-readable: 0 = healthy, 1 = warnings, 2 = critical.

---

Where to Learn More

Topic	Doc
Installation, prerequisites, Java version compatibility	docs/getting-started.md
All commands with output examples	docs/cli-commands.md
Usage walkthroughs (agent, Spring Boot, ZGC, CI/CD, monitoring stack)	docs/usage.md
Agent properties, flag tables, env vars	docs/configuration.md
Module layout, SPI patterns, architecture diagrams	docs/architecture.md
Build, commit, i18n, release procedures	docs/contributing.md
Common errors and fixes	docs/troubleshooting.md

---

Building from Source

./gradlew :argus-cli:fatJar

See docs/contributing.md for the full build, test, and release workflow.

---

License & Contributing

MIT License — see LICENSE.

Contributions welcome — bugs, features, docs, tests. See docs/contributing.md.

Maintainer: @rlaope