Skip to content

feat: argus gcscore — GC Health Score Card with A–F grade#154

Merged
rlaope merged 1 commit intomasterfrom
feat/argus-gcscore
Apr 17, 2026
Merged

feat: argus gcscore — GC Health Score Card with A–F grade#154
rlaope merged 1 commit intomasterfrom
feat/argus-gcscore

Conversation

@rlaope
Copy link
Copy Markdown
Owner

@rlaope rlaope commented Apr 17, 2026

Closes #150.

Summary

argus gcscore <gc-log-file> — a one-page GC Health Score Card. Scores six KPI axes against widely-accepted thresholds and emits a weighted A–F grade plus up to three improvement hints.

Sample output:

┌─ GC Health Score ───────────────────────────────────────────┐
│  Overall: B  (good, minor tuning opportunities)  [82/100]   │
│                                                             │
│  Pause p99           ✓ Pass    82 ms   (target < 200 ms)    │
│  Pause tail (max)    ⚠ Warn   720 ms   (target < 500 ms)    │
│  Throughput          ✓ Pass   98.4%    (target > 95%)       │
│  Full GC frequency   ✓ Pass   0.2 /hour (target 0 / hour)   │
│  Allocation rate     ✓ Pass   280 MB/s (target < 1 GB/s)    │
│  Promotion ratio     ⚠ Warn   22.0%    (target < 20%)       │
│                                                             │
│  Hints:                                                     │
│   • Long tail pauses suggest concurrent-mode failure ...    │
│   • Survivor overflow promoting short-lived objects ...     │
└─────────────────────────────────────────────────────────────┘

Scope

  • Log-based: argus gcscore <gc-log-file> (reuses GcLogParser / GcLogAnalyzer)
  • --format=json for automation
  • Axes: Pause p99, Pause tail (max), Throughput, Full GC frequency, Allocation rate, Promotion ratio
  • Pass/Warn/Fail per axis, weighted overall → grade A (≥ 90) / B (≥ 75) / C (≥ 60) / D (≥ 40) / F (< 40)
  • Up to 3 hints from a rule base keyed on which axes failed
  • Fallback hint when no axis fails
  • Missing rate-analysis data marks axes as N/A (excluded from weighted average)
  • i18n (en, ko, ja, zh), shell completions (bash, zsh, fish, ps1)

Non-goals in this PR

  • Live <host:port> target mode — deferred. Server-side metric shape for p99/p999 from live scrape is not yet exposed in a form directly usable here; will be tracked in a follow-up issue.
  • Not auto-tuning — hints are suggestions only.

References (design lineage)

  • GCeasy.io Report Score Card (1-page KPI summary)
  • Censum (jClarity / Microsoft) rule-based recommendations with reasoning

Test plan

  • ./gradlew :argus-cli:test --tests io.argus.cli.gcscore.* — passes
  • ./gradlew :argus-cli:test full suite — passes
  • Unit tests cover: perfect GC (A grade), long p99 downgrade, frequent Full GC verdict, N/A axes when rate data missing, high promotion ratio surfacing survivor hint, grade boundaries
  • Manual smoke against a real GC log — pending a fixture log

Follow-up

  • Live target mode (requires server-side p99 histogram exposure) — new issue to be raised.

One-page GC Health Score Card from a GC log file. Scores six KPI axes
(pause p99, pause tail, throughput, Full GC frequency, allocation rate,
promotion ratio) against widely-accepted thresholds and emits a weighted
A-F grade plus up to three improvement hints.

Log-based in v1. Target mode (live /prometheus scraping) is deferred to
a follow-up; the server-side histogram data needed for p99/p999 from live
metrics is not yet exposed in a form usable here.

New files:
  - argus-cli/src/main/java/io/argus/cli/gcscore/AxisScore.java
  - argus-cli/src/main/java/io/argus/cli/gcscore/GcScoreResult.java
  - argus-cli/src/main/java/io/argus/cli/gcscore/GcScoreCalculator.java
  - argus-cli/src/main/java/io/argus/cli/command/GcScoreCommand.java
  - argus-cli/src/test/java/io/argus/cli/gcscore/GcScoreCalculatorTest.java

Updated:
  - ArgusCli command registration
  - i18n (en, ko, ja, zh) cmd.gcscore.desc / header.gcscore / desc.gcscore
  - Shell completions (bash, zsh, fish, ps1)

Closes #150.

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope rlaope merged commit 2fc32bc into master Apr 17, 2026
7 checks passed
@rlaope rlaope deleted the feat/argus-gcscore branch April 17, 2026 14:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: argus gcscore — GC Health Score Card (1-page KPI + grade)

1 participant