"Argus Panoptes, the all-seeing giant with a hundred eyes, never slept - for when some of his eyes closed, others remained open, watching everything."
Inspired by Argus Panoptes from Greek mythology - the giant with a hundred eyes who never slept and watched over everything - this project observes and analyzes all Virtual Threads in the JVM in real-time.
A next-generation real-time visualization profiler for JVM 21+ environments, focusing on Virtual Threads (Project Loom) monitoring and memory analysis.
- Thread Lifecycle: Track creation, termination, and pinning of virtual threads
- Pinning Detection: Identify pinned threads with detailed stack traces
- Real-time State Tracking: Monitor running, pinned, and ended thread states
- GC Events: Real-time garbage collection tracking with pause time analysis
- Heap Usage: Before/after heap visualization with trend analysis
- Allocation Rate: Track object allocation rate and top allocating classes
- Metaspace Monitoring: Monitor metaspace usage and growth rate
- GC Overhead: Calculate GC overhead percentage with warnings
- CPU Utilization: JVM and system CPU tracking with history
- Method Profiling: Hot method detection via execution sampling
- Lock Contention: Monitor thread contention and lock wait times
- GC ↔ CPU Correlation: Detect CPU spikes related to GC events
- GC ↔ Pinning Correlation: Identify pinning increases during GC
- Automatic Recommendations: Get actionable insights based on metrics
- JFR Streaming: Low-overhead event collection using JDK Flight Recorder
- Real-time Dashboard: WebSocket-based streaming with interactive charts
- Lock-free Architecture: High-performance ring buffer for event collection
- Data Export: Export events in CSV, JSON, or JSONL formats
- Java 21+
- Gradle 8.4+ (only if building from source)
# Download the latest agent JAR
curl -LO https://github.com/rlaope/argus/releases/latest/download/argus-agent.jar
# Or download a specific version
curl -LO https://github.com/rlaope/argus/releases/download/v0.1.0/argus-agent.jargit clone https://github.com/rlaope/argus.git
cd argus
./gradlew build
# JARs are located at:
# argus-agent/build/libs/argus-agent-x.x.x-SNAPSHOT.jar
# argus-server/build/libs/argus-server-x.x.x-SNAPSHOT.jarjava -javaagent:argus-agent.jar \
--enable-preview \
-jar your-application.jarjava -javaagent:argus-agent.jar \
-Dargus.server.enabled=true \
--enable-preview \
-jar your-application.jar
# Open dashboard: http://localhost:9202/
# View metrics: curl http://localhost:9202/metricsThe agent accepts the following system properties:
| Property | Default | Description |
|---|---|---|
argus.server.enabled |
false |
Enable built-in dashboard server |
argus.server.port |
9202 |
Dashboard/WebSocket server port |
argus.buffer.size |
65536 |
Ring buffer size for event collection |
argus.gc.enabled |
true |
Enable GC monitoring |
argus.cpu.enabled |
true |
Enable CPU monitoring |
argus.cpu.interval |
1000 |
CPU sampling interval in milliseconds |
argus.allocation.enabled |
false |
Enable allocation tracking (high overhead) |
argus.allocation.threshold |
1048576 |
Minimum allocation size to track (1MB) |
argus.metaspace.enabled |
true |
Enable metaspace monitoring |
argus.profiling.enabled |
false |
Enable method profiling (high overhead) |
argus.profiling.interval |
20 |
Profiling sampling interval (ms) |
argus.contention.enabled |
false |
Enable lock contention tracking |
argus.contention.threshold |
50 |
Minimum contention duration (ms) |
argus.correlation.enabled |
true |
Enable correlation analysis |
See Configuration Guide for detailed documentation.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ argus-agent │───▶│ argus-core │◀───│ argus-server │
│ (JFR Stream) │ │ (Ring Buffer) │ │ (WebSocket) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ JFR Events │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Target JVM │ │ Frontend │
│ (Virtual Threads)│ │ (Visualization)│
└─────────────────┘ └─────────────────┘
- argus-core: Core event models, ring buffer, and serialization
- argus-agent: Java agent with JFR streaming engine
- argus-server: WebSocket server for event streaming
jdk.VirtualThreadStart- Thread creationjdk.VirtualThreadEnd- Thread terminationjdk.VirtualThreadPinned- Pinning detection (critical for Loom performance)jdk.VirtualThreadSubmitFailed- Submit failures
jdk.GarbageCollection- GC pause duration, cause, and typejdk.GCHeapSummary- Heap usage before and after GCjdk.ObjectAllocationInNewTLAB- Object allocation trackingjdk.MetaspaceSummary- Metaspace usage monitoring
jdk.CPULoad- JVM and system CPU utilizationjdk.ExecutionSample- Method execution sampling for CPU profilingjdk.JavaMonitorEnter- Lock acquisition contentionjdk.JavaMonitorWait- Lock wait contention
| 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 |
/export |
Export events (CSV, JSON, JSONL) |
/allocation-analysis |
Allocation rate and top allocating classes |
/metaspace-metrics |
Metaspace usage and growth |
/method-profiling |
Hot methods (Top 20) |
/contention-analysis |
Lock contention hotspots |
/correlation |
Correlation analysis and recommendations |
Everyone is welcome! Project Argus is an open-source project and we welcome all forms of contributions.
- Bug reports & feature requests
- Code contributions (bug fixes, new features)
- Documentation improvements
- Testing and feedback
See CONTRIBUTING.md for more details.
- @rlaope - Project Lead & Maintainer
For questions, suggestions, or collaboration inquiries, please open a GitHub Issue or contact @rlaope directly.
MIT License - see LICENSE for details.