GitHub - rlaope/Argus: ✨ The best JVM observability, troubleshoot, and optimize. 🚀 Unlock deep insights instantly via our dashboard and robust CLI. 📊

Lightweight JVM diagnostic toolkit. CLI works on Java 11+, Dashboard on Java 17+, full features on Java 21+. No agent required for CLI diagnostics.

Two independent tools in one package:

argus CLI — 50 diagnostic commands that work on any running JVM via jcmd/jstat
Argus Agent — Real-time web dashboard with JFR streaming, flame graphs, and metric export

curl -fsSL https://raw.githubusercontent.com/rlaope/argus/master/install.sh | bash

Argus CLI

Diagnose any running JVM process directly from the terminal. No agent, no instrumentation, no restart needed.

Commands

Command	Description
Process & System
`argus ps`	List running JVM processes (with Java version, uptime)
`argus info <pid>`	JVM information, flags, and CPU utilization
`argus env <pid>`	JVM launch environment
`argus sysprops <pid>`	System properties (`--filter` supported)
`argus vmflag <pid>`	VM flags (`--filter`, `--set` supported)
`argus vmset <pid> Flag=val`	Set VM flag at runtime
`argus vmlog <pid>`	JVM unified logging control
`argus jmx <pid> [cmd]`	JMX agent control
Memory & GC
`argus heap <pid>`	Heap memory with detailed pool breakdown
`argus histo <pid>`	Heap object histogram
`argus gc <pid>`	GC statistics (collectors, pauses, overhead)
`argus gcutil <pid>`	GC generation utilization (jstat-style)
`argus gccause <pid>`	GC cause with utilization stats
`argus gcnew <pid>`	Young generation GC detail
`argus gcrun <pid>`	Trigger System.gc() remotely
`argus metaspace <pid>`	Detailed metaspace breakdown
`argus nmt <pid>`	Native memory tracking
`argus buffers <pid>`	NIO buffer pool statistics (direct, mapped)
`argus finalizer <pid>`	Finalizer queue status
`argus diff <pid> [interval]`	Heap snapshot diff (leak detection)
`argus heapdump <pid>`	Generate heap dump (with STW warning)
Threads
`argus threads <pid>`	Thread dump summary (daemon, peak counts)
`argus threaddump <pid>`	Full thread dump with stack traces
`argus deadlock <pid>`	Detect Java-level deadlocks
`argus pool <pid>`	Thread pool analysis
Runtime & Class Loading
`argus classloader <pid>`	Class loader hierarchy
`argus classstat <pid>`	Class loading statistics
`argus sc <pid> <pattern>`	Search loaded classes by glob pattern
`argus compiler <pid>`	JIT compiler and code cache stats
`argus compilerqueue <pid>`	JIT compilation queue
`argus stringtable <pid>`	Interned string table statistics
`argus symboltable <pid>`	Symbol table statistics
`argus dynlibs <pid>`	Loaded native libraries
Profiling & Diagnostics
`argus profile <pid>`	CPU/allocation/lock profiling (async-profiler)
`argus jfr <pid> start\|stop\|check\|dump`	Flight Recorder control
`argus jfranalyze <file.jfr>`	Analyze JFR recording (GC, CPU, hot methods, I/O)
`argus logger <pid>`	View and change log levels at runtime
`argus events <pid>`	VM internal event log (safepoints, deopt, GC)
`argus report <pid>`	Comprehensive diagnostic report
`argus doctor`	One-click JVM health diagnosis with tuning recommendations
`argus gclog <file>`	GC log analysis with pause distribution and tuning (GCEasy alternative)
`argus flame <pid>`	One-shot flame graph — profiles, generates HTML, opens browser
`argus suggest`	JVM flag optimization based on workload analysis
`argus ci`	CI/CD health gate — exit codes + GitHub annotations
`argus compare <pid1> <pid2>`	Side-by-side JVM comparison (live or baseline)
`argus slowlog <pid>`	Real-time slow method detection via JFR streaming
Monitoring
`argus top`	Real-time monitoring (agent required)
`argus watch <pid>`	Real-time terminal dashboard (htop for JVM)
`argus tui [pid]`	Interactive terminal UI — browse all commands (k9s-style)
`argus init`	First-time setup (language selection)

`argus report` — Comprehensive Diagnostic

$ argus report 39113

 argus report
 Comprehensive JVM diagnostic report. Collects all available metrics in one view.

╭─ JVM Report ── pid:39113 ── source:auto ─────────────────────────────────────╮
│                                                                              │
│   ▸ JVM Info                                                                 │
│     39113: OpenJDK 64-Bit Server VM version 21.0.9    Uptime: 57m 5s         │
│                                                                              │
│   ▸ Memory                                                                   │
│     Heap    [███░░░░░░░░░░░░░]  41M / 256M  (16%)                            │
│     Free    215M                                                             │
│                                                                              │
│   ▸ GC                                                                       │
│     S0: 0%  S1: 0%  Eden: 0%  Old: 42%  Meta: 97%                            │
│                                                                              │
│   ▸ Threads                                                                  │
│     Total: 29    Virtual: 0    Platform: 29                                  │
│     TIMED_WAITING: 5  WAITING: 13  RUNNABLE: 11                              │
│                                                                              │
│   ▸ Top Heap Objects                                                         │
│     1. byte[]                111.0K instances   16M                          │
│     2. java.lang.String      107.2K instances   2M                           │
│     3. java.lang.Class       18.9K instances   2M                            │
│                                                                              │
│   ▸ Warnings                                                                 │
│     ⚠ Metaspace at 97% — near limit                                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

`argus histo` — Heap Object Histogram

$ argus histo 39113 --top 5

 argus histo
 Analyzes heap memory objects. Count = live instances, Size = total bytes occupied.

╭─ Heap Histogram ── pid:39113 ── source:auto ─────────────────────────────────╮
│                                                                              │
│    #  Class                                                  Count      Size │
│ ────  ────────────────────────────────────────────────  ──────────  ──────── │
│    1  byte[]                                               111,050       16M │
│    2  java.lang.String                                     107,249        2M │
│    3  java.lang.Class                                       18,914        2M │
│    4  ConcurrentHashMap.Node                                62,917        2M │
│    5  java.lang.Object[]                                    25,496        1M │
│                                                                              │
│ Total: 718.6K objects · 40M                                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

`argus gcutil` — GC Generation Utilization

$ argus gcutil 39113

 argus gcutil
 Monitors GC generation utilization. S0/S1 = Survivor, E = Eden, O = Old, M = Metaspace, CCS = Compressed Class.

╭─ GC Utilization ── pid:39113 ── source:auto ─────────────────────────────────╮
│                                                                              │
│ S0      S1      Eden    Old     Meta    CCS     YGC    FGC    GCT            │
│ ──────────────────────────────────────────────────────────────────────       │
│ 0.0%    0.0%    0.0%    41.8%   96.5%   87.1%   18     2      10.000         │
│                                                                              │
│   S0    [░░░░░░░░░░░░░░░░░░░░]    0.0%                                       │
│   S1    [░░░░░░░░░░░░░░░░░░░░]    0.0%                                       │
│   Eden  [░░░░░░░░░░░░░░░░░░░░]    0.0%                                       │
│   Old   [████████░░░░░░░░░░░░]   41.8%                                       │
│   Meta  [███████████████████░]   96.5%                                       │
│   CCS   [█████████████████░░░]   87.1%                                       │
│                                                                              │
│ YGC: 18 (0.163s)    FGC: 2 (0.215s)    Total: 10.000s                        │
╰──────────────────────────────────────────────────────────────────────────────╯

`argus profile` — async-profiler Integration

$ argus profile 29286 --duration 3

 argus profile
 Profiling with async-profiler. Shows hottest methods by sample count.

╭─ Profile Results ── pid:29286 ── cpu 3s ── 3 samples ────────────────────────╮
│                                                                              │
│   #   Method                                           Samples        %      │
│   ────  ────────────────────────────────────────────  ──────────  ────────   │
│   1   __psynch_cvwait                                        2    66.7%  ███ │
│   2   std::__1::basic_ostream<char, std::__1::cha…           1    33.3%  █   │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Options: --type cpu|alloc|lock|wall, --duration N, --flame (HTML flame graph + browser open), --top N

Multi-language Support

All commands support --lang=en|ko|ja|zh. Example with Korean (--lang=ko):

$ argus --lang=ko report 39113

 argus report
 종합 JVM 진단 보고서. 사용 가능한 모든 지표를 한 화면에 수집합니다.

╭─ JVM 보고서 ── pid:39113 ── source:auto ────────────────────────────────────────╮
│                                                                              │
│   ▸ JVM Info                                                                 │
│     39113: OpenJDK 64-Bit Server VM version 21.0.9    Uptime: 1h 3m          │
│                                                                              │
│   ▸ Memory                                                                   │
│     Heap    [██░░░░░░░░░░░░░░]  39M / 256M  (15%)                            │
│     Free    217M                                                             │
│                                                                              │
│   ▸ GC                                                                       │
│     S0: 0%  S1: 0%  Eden: 0%  Old: 41%  Meta: 96%                            │
│                                                                              │
│   ▸ Threads                                                                  │
│     Total: 25    Virtual: 0    Platform: 25                                  │
│     TIMED_WAITING: 6  RUNNABLE: 12  WAITING: 7                               │
│                                                                              │
│   ▸ Top Heap Objects                                                         │
│     1. byte[]                110.9K instances   16M                          │
│     2. java.lang.String      107.9K instances   2M                           │
│     3. java.lang.Class       18.9K instances   2M                            │
│                                                                              │
│   ▸ Warnings                                                                 │
│     ⚠ Metaspace at 96% — near limit                                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Global Options

--source=auto|agent|jdk   Data source (default: auto)
--no-color                Disable colors
--lang=en|ko|ja|zh        Output language
--format=table|json       Output format (default: table)
--help, -h                Show help
--version, -v             Show version

See CLI Command Reference for all 50 commands with full output examples.

Argus Agent (Dashboard)

Attach to your JVM for real-time monitoring with a web dashboard, flame graphs, and metric export.

When the agent starts, you'll see the Argus banner:

       _____
      /  _  \_______  ____  __ __  ______
     /  /_\  \_  __ \/ ___\|  |  \/  ___/
    /    |    \  | \/ /_/  >  |  /\___ \
    \____|__  /__|  \___  /|____//____  >
            \/     /_____/            \/

    JVM Observability Platform v0.8.0
[Argus] Initializing JFR streaming engine...
[Argus] Agent initialized successfully
[Argus] Ring buffer size: 65536
[Argus] JFR streaming started
[Argus] Dashboard: http://localhost:9202/

Features

Real-time Dashboard — WebSocket streaming with Chart.js, dual tabs (Virtual Threads + JVM Overview)
Flame Graph — Continuous profiling with d3-flamegraph (zoom, hover, export)
Virtual Thread Monitoring — Lifecycle tracking, pinning detection, carrier thread analysis
Memory & GC — Heap usage, GC pause analysis, allocation rate, metaspace monitoring
CPU & Profiling — CPU tracking with 60s history, hot method detection, lock contention
Metric Export — Prometheus /prometheus endpoint, OTLP push export, CSV/JSON/JSONL data export
Correlation Analysis — Cross-metric correlation with automatic recommendations

Quick Start

# 1. Attach agent to your app
java -javaagent:$(argus-agent --path) -jar your-app.jar

# 2. Open dashboard
open http://localhost:9202/

# 3. Enable profiling + flame graph
java -javaagent:~/.argus/argus-agent.jar \
     -Dargus.profiling.enabled=true \
     -Dargus.contention.enabled=true \
     -jar your-app.jar

# 4. Export to OpenTelemetry
java -javaagent:~/.argus/argus-agent.jar \
     -Dargus.otlp.enabled=true \
     -Dargus.otlp.endpoint=http://localhost:4318/v1/metrics \
     -jar your-app.jar

API Endpoints

Endpoint	Description
`/`	Dashboard UI
`/health`	Health check
`/metrics`	Virtual thread metrics
`/gc-analysis`	GC statistics and recent events
`/cpu-metrics`	CPU utilization history
`/pinning-analysis`	Pinning hotspot analysis
`/allocation-analysis`	Allocation rate and top classes
`/metaspace-metrics`	Metaspace usage and growth
`/method-profiling`	Hot methods (Top 20)
`/contention-analysis`	Lock contention hotspots
`/correlation`	Correlation analysis and recommendations
`/flame-graph`	Flame graph data (JSON or `?format=collapsed`)
`/prometheus`	Prometheus metrics endpoint
`/carrier-threads`	Carrier thread distribution
`/active-threads`	Currently active virtual threads
`/export`	Export events (CSV, JSON, JSONL)

Agent Configuration

Property	Default	Description
`argus.server.port`	`9202`	Dashboard server port
`argus.gc.enabled`	`true`	GC monitoring
`argus.cpu.enabled`	`true`	CPU monitoring
`argus.profiling.enabled`	`false`	Method profiling (high overhead)
`argus.contention.enabled`	`false`	Lock contention tracking
`argus.allocation.enabled`	`false`	Allocation tracking (high overhead)
`argus.otlp.enabled`	`false`	OTLP push export
`argus.otlp.endpoint`	`http://localhost:4318/v1/metrics`	OTLP collector URL

See Configuration Guide for all options.

Installation

One-line Install (Recommended)

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

Installs both CLI + Agent to ~/.argus/ and adds argus to PATH.

Shell completions: bash, zsh, fish, PowerShell are all supported and installed automatically.

Build from Source

git clone https://github.com/rlaope/argus.git
cd argus
./gradlew build
./gradlew :argus-cli:fatJar

Requirements

CLI: Java 11+ (JDK required for jcmd/jstat)
Agent + Dashboard: Java 17+ (MXBean polling) or Java 21+ (full JFR streaming)
Gradle 8.4+ (only if building from source)

Java Version Compatibility

Argus adapts its capabilities based on the target JVM version at runtime:

Feature	Java 11+	Java 17+	Java 21+
CLI (50 commands)	✅	✅	✅
Dashboard & Web UI	—	✅	✅
GC Analysis	CLI only	✅ MXBean	✅ JFR
CPU Monitoring	CLI only	✅ MXBean	✅ JFR
Heap / Memory	CLI only	✅ MXBean	✅ JFR
Metaspace	CLI only	✅ MXBean	✅ JFR
Thread Analysis	CLI only	✅ MXBean	✅ JFR
Lock Contention	—	—	✅ JFR
Allocation Tracking	—	—	✅ JFR
Virtual Thread Monitoring	—	—	✅ JFR
Flame Graph	—	—	✅ JFR
Micrometer Metrics	—	✅	✅
Spring Boot Starter	—	✅	✅

Note: On Java 17-20, the agent uses MXBean polling for GC/CPU/Memory metrics. Virtual thread monitoring and JFR-based profiling require Java 21+. The dashboard automatically adapts its UI based on the detected Java version.

Uninstall

rm -rf ~/.argus
# Remove the PATH line from ~/.zshrc or ~/.bashrc

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   argus-agent   │───▶│   argus-core    │◀───│  argus-server   │
│  (JFR Stream)   │    │ (Config/Buffer) │    │ (Netty/Analysis)│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                     ▲                       │
         │                     │                       ▼
         ▼              ┌──────┴──────┐     ┌─────────────────┐
┌─────────────────┐     │  argus-cli  │     │ argus-frontend  │
│   Target JVM    │◀────│  (Unified   │     │  (Dashboard UI) │
└─────────────────┘     │  Diagnostic)│     └─────────────────┘
       ▲  jcmd          └─────────────┘            │
       │                   │        │         WebSocket +
       └───────────────────┘   HTTP Polling   Flame Graph
         Direct JDK Access    (Agent Mode)

┌──────────────────────────┐    ┌──────────────────────────────────┐
│    argus-micrometer      │    │   argus-spring-boot-starter      │
│  (MeterBinder, ~25       │    │  (Spring Boot 3.2+ auto-config)  │
│   metrics bridge)        │    │                                  │
└──────────────────────────┘    └──────────────────────────────────┘

Module	Description
argus-core	Shared config, event models, ring buffer
argus-agent	Java agent with JFR streaming engine
argus-server	Netty HTTP/WS server, 10 analyzers, Prometheus + OTLP
argus-frontend	Static dashboard with Chart.js and d3-flamegraph
argus-cli	50 diagnostic commands, auto source detection, i18n
argus-micrometer	Micrometer MeterBinder exposing ~25 JVM metrics
argus-spring-boot-starter	Spring Boot 3.2+ auto-configuration for Argus agent

Docker

docker run --pid=host ghcr.io/rlaope/argus ps
docker run --pid=host ghcr.io/rlaope/argus doctor
docker run --pid=host ghcr.io/rlaope/argus watch

CI/CD Integration

Add JVM health checks to your GitHub Actions pipeline:

- name: JVM Health Check
  uses: rlaope/Argus/action@master
  with:
    command: ci
    fail-on: critical
    format: github-annotations

Or use argus ci directly:

argus ci --pid=auto --fail-on=critical --format=summary
# Exit code: 0=pass, 1=warnings, 2=critical

Spring Boot Integration

The argus-spring-boot-starter provides zero-configuration auto-setup for Spring Boot 3.2+ applications.

Add the dependency:

<dependency>
  <groupId>io.argus</groupId>
  <artifactId>argus-spring-boot-starter</artifactId>
  <version>0.8.0</version>
</dependency>

Or with Gradle:

implementation 'io.argus:argus-spring-boot-starter:0.8.0'

The starter auto-configures the Argus agent on application startup. All argus.* properties can be set in application.properties / application.yml:

argus.server.port=9202
argus.profiling.enabled=true
argus.contention.enabled=true
argus.otlp.enabled=false

Micrometer Metrics

The argus-micrometer module provides a MeterBinder implementation that bridges ~25 JVM metrics into any Micrometer-compatible registry (Prometheus, Datadog, InfluxDB, etc.).

Metrics exposed include GC pause time, heap usage, thread counts (virtual and platform), allocation rate, metaspace usage, CPU load, lock contention, and method profiling data.

When used with the Spring Boot starter and a Micrometer registry on the classpath, metrics are registered automatically. For standalone use:

ArgusMetrics argusMetrics = new ArgusMetrics();
argusMetrics.bindTo(meterRegistry);

Contributing

Contributions welcome — bug reports, features, docs, testing. See CONTRIBUTING.md for details.

Maintainer

@rlaope

License

MIT License - see LICENSE for details.