Skip to content

feat: argus explain — human-readable explanations for JVM metrics and flags #135

@rlaope

Description

@rlaope

Priority: P2

Perspective: Junior / Learning Developer

Why

"I see 'G1 Evacuation Pause' or '-XX:MaxGCPauseMillis' but I have no idea what they mean. I want Argus to explain it to me."

Design

argus explain "G1 Evacuation Pause"
→ G1 Evacuation Pause is a stop-the-world GC event where live objects 
  are copied from one set of regions to another. It happens during Young 
  GC or Mixed GC. High evacuation pause times usually mean too many 
  objects are surviving to old gen.
  
  Suggestion: Check tenuring threshold with `argus gcnew <pid> --age-histogram`

argus explain -XX:MaxGCPauseMillis
→ Sets the target maximum GC pause time in milliseconds. The GC will 
  try to keep pauses below this value by adjusting heap sizes and 
  collection frequency. Default: 200ms for G1GC.
  
  Current value on pid 12345: 200ms
  Recommendation: For latency-sensitive apps, try 100ms.

argus doctor <pid> --explain
→ (same doctor output but with inline explanations for each finding)

Implementation

  • Embedded knowledge base of ~200 JVM terms, GC causes, and flags
  • Can be a static Map<String, String> or a resource file
  • --explain flag on doctor/suggest commands adds inline context

Impact

Makes Argus approachable for developers who aren't JVM internals experts. Lowers the barrier to adoption significantly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions