Experimental: runtime usage report + /actuator/bootusage endpoint

[dhruv-15-03]

Summary

Adds an experimental runtime usage reporting feature that generates a structured JSON (and optional Markdown) report of auto‑configuration behavior, starter usage, bean origins, and policy outcomes. Exposes the report via a new Actuator endpoint: /actuator/bootusage.

Motivation

Helps developers:

• See which auto‑configurations applied or were skipped.
• Identify declared vs actually used starters (and unused jars).
• Trace (sanitized) bean origin locations.
• Enforce custom usage policies (e.g., forbid certain starters) with optional fail-fast.
• Retrieve usage insights at runtime (cached endpoint) or as a persisted build artifact.

Key Components

• Auto-config: UsageAnalysisAutoConfiguration
• Service & generation: UsageReportService, UsageReportGenerator, StarterUsageAnalyzer
• Post-processor: BeanOriginTrackingPostProcessor
• Endpoint: UsageEndpoint + UsageEndpointAutoConfiguration
• SPIs:
  • UsageReportCustomizer (augment structured report)
  • UsagePolicy (validate and optionally fail startup)
• JSON Schema: bootusage-schema-v1.json
• Documentation: bootusage.adoc
• Metadata: Added configuration property entries (core + actuator)

Configuration Properties (prefix spring.boot.usage.report.)

• enabled (boolean) – master switch (default: false)
• cache-ttl (duration, ms by default) – endpoint cache TTL (0 = no cache)
• include-origins (boolean) – include sanitized bean origin paths
• include-confidence (boolean) – include heuristic confidence scoring
• detect-unused-jars (boolean) – list jars on classpath not contributing beans
• markdown-summary (boolean) – also emit a Markdown summary file
• output-dir (string) – output directory for persisted report (default: build/boot-usage)
• policies.fail-on-violation (boolean) – throw on first policy violation
  (Actuator exposure still controlled by normal management.* settings.)

Actuator Endpoint

• ID: bootusage
• GET /actuator/bootusage
  • Query parameter force=true bypasses cache.
• Structure includes:
  • appliedAutoConfigurations
  • skippedAutoConfigurations (with optional detail)
  • starters (declared, used, unused)
  • suggestions (confidence, unusedJars, future policy slots)
  • beanOrigins (when enabled)
  • policies (violations, if any)
  • metadata (generation timestamp, version)

Policy & Customization SPIs

• Implement UsagePolicy to validate the generated report (return violations).
• Implement UsageReportCustomizer to mutate the structured map before exposure/persist.
• Both discovered through the application context (standard bean registration).

Failure Semantics

• If policies.fail-on-violation=true, startup fails on first violation.
• If detect-unused-jars=true and (optionally) integrated policies deem unused jars unacceptable, it can contribute to violations.

Persistence

• When enabled=true, a JSON report is written on ApplicationReadyEvent.
• Optional Markdown summary when markdown-summary=true.

Security & Sanitization

• Bean origins are trimmed / sanitized to remove user-specific absolute paths.
• No class byte inspection; heuristics rely on configuration report and bean definitions.

Backward Compatibility

• Disabled by default; no impact on existing applications unless explicitly enabled.
• No public API changes outside newly added classes and endpoint.

Tests Added

• Activation / conditional creation
• Endpoint exposure & caching
• Customizer invocation
• Policy failure path
• Unused jars detection
• Bean origin sanitization

Limitations / Future Work

• Heuristics for unused jars are best-effort; could be refined with class usage tracing.
• Policy SPI currently synchronous at startup (consider deferred evaluation).
• Potential integration with build tooling for aggregated multi-module analysis.

How to Try

Enable and expose:

spring.boot.usage.report.enabled=true
management.endpoints.web.exposure.include=bootusage
management.endpoint.bootusage.enabled=true

Optional extras:

spring.boot.usage.report.include-origins=true
spring.boot.usage.report.detect-unused-jars=true
spring.boot.usage.report.policies.fail-on-violation=true

Reviewer Checklist

• Feature is property-gated (default off)
• Endpoint only present when feature enabled
• Documentation and metadata entries present
• NullAway clean in touched code
• No regressions in unrelated modules (CI baseline)
• Experimental scope acceptable (naming + docs clarity)

Notes

Snapshot dependency resolution flakiness may cause unrelated CI failures (infrastructure). Re-run if failures are only network/timeouts.