skip to content

How does DiskSpaceHealthIndicator decide UP vs DOWN, and how do you configure its threshold and path?

level: middleimportance: should knowfreq 45%

answer

  1. getUsableSpace vs threshold
  2. default threshold 10MB (DataSize)
  3. path defaults to working dir
  4. management.health.diskspace.threshold / .path
  5. container: set path to the real volume

basics

~10 s

It reports the free space on a directory and returns DOWN when free space falls below a threshold (default 10 MB). You change it with management.health.diskspace.threshold and management.health.diskspace.path.

solid answer

~40 s

DiskSpaceHealthIndicator measures the usable/free space on a filesystem path (default: the application's current working directory) and compares it to a threshold. If free space is at or above the threshold it's UP; below it, DOWN. The default threshold is 10 MB. Both are configurable: management.health.diskspace.threshold (a DataSize, e.g. 100MB or 10GB) and management.health.diskspace.path (which directory to measure). Its details include total, free, and threshold in bytes. A common gotcha is that it measures the filesystem containing that path, so on a container the default working directory may not be the volume you actually care about — set the path explicitly. You can disable it with management.health.diskspace.enabled=false.

code

java · 13 lines
java
// application.yml
management:
  health:
    diskspace:
      enabled: true          # default; set false to remove the check
      path: /var/lib/app-data # measure the mounted volume, not the working dir
      threshold: 500MB        # DataSize; default is 10MB

// Resulting details when UP:
// "diskSpace": {
//   "status": "UP",
//   "details": { "total": 107374182400, "free": 64424509440, "threshold": 524288000, "path": "/var/lib/app-data/.", "exists": true }
// }

go deeper

for a junior

Know it warns when free space drops below a threshold and the two properties exist.

for a middle

Explain usable-space semantics, the 10MB default, DataSize suffixes, and setting path explicitly.

for a senior

Discuss container/volume gotchas and whether disk belongs in readiness vs liveness given worst-status → 503 ejection.

for a principal

Reason about threshold sizing relative to write rate and the operational blast radius of tying LB membership to a disk check.

## What it checks **DiskSpaceHealthIndicator** is one of the two always-registered built-in indicators (the other is `PingHealthIndicator`). It answers a narrow question: is there enough free disk space on a given path? Running out of disk is a classic cause of failures (can't write logs, temp files, or spill files), so this is a cheap early-warning check. ## The mechanism At check time it resolves the configured **path** to a `java.io.File`, then reads `File.getUsableSpace()` (the space actually available to the JVM, honoring quotas) and `File.getTotalSpace()`. It compares usable space against the **threshold**: - usable space **>= threshold** → `Status.UP` - usable space **< threshold** → `Status.DOWN` The returned `Health` details include `total`, `free`, `threshold` (all in bytes), the `path`, and `exists`. ## Configuration - **`management.health.diskspace.threshold`** — a Spring `DataSize`. Default is **10MB**. Accepts suffixes: `management.health.diskspace.threshold=1GB`. - **`management.health.diskspace.path`** — the directory whose filesystem is measured. Default is the process working directory (`.`). - **`management.health.diskspace.enabled=false`** — turns the indicator off entirely. ## Gotchas 1. **It measures the filesystem that contains the path, not a fixed volume.** In containers, the working directory may sit on the overlay/root filesystem while your real data lives on a mounted volume. Set `path` explicitly to the volume you care about. 2. **Usable vs free space.** It uses usable space (respects per-user quotas), so under quota systems the number can be lower than raw filesystem 'free'. 3. **Threshold is per-check, not a rate.** It won't warn you about a fast-filling disk that's still above threshold — pick a threshold with enough headroom for your write rate. 4. **A DOWN here fails the whole /health** by default (worst-status aggregation → HTTP 503), which can eject the instance from a load balancer. Consider whether disk space belongs in your readiness group. ## When to tune Defaults (10 MB) are extremely low and mostly a 'disk is essentially full' alarm. For real workloads raise it to something proportional to your write volume, e.g. hundreds of MB to several GB.

  • In a Kubernetes pod your app writes to a mounted PVC but the disk check monitors the ephemeral root FS. How do you fix it?
    Set management.health.diskspace.path to a directory on the PVC mount. The indicator measures the filesystem containing the configured path, so pointing it at the PVC makes the check reflect the volume that actually matters.

saying these in an interview costs you the question

  • Saying it checks 'the whole disk' rather than the filesystem containing the configured path
  • Thinking the default threshold is large (it's only 10MB)
  • Believing the path defaults to /tmp or root (/) — it defaults to the working directory

context

resolving links…