4.2.13.2 HEALTHCHECK Interval

The HEALTHCHECK interval setting controls how frequently Docker runs the configured health check command against a running container, balancing how quickly a problem is detected against the overhead of running the check itself.

Setting the Interval

The --interval option specifies how long to wait between successive health check runs.

HEALTHCHECK --interval=30s CMD curl -f http://localhost:8080/health || exit 1

This runs the health check roughly every 30 seconds for as long as the container continues running.

Choosing an Appropriate Interval

A shorter interval detects problems more quickly but adds more frequent overhead from running the check itself; a longer interval reduces that overhead but delays detection of an actual problem.

HEALTHCHECK --interval=10s CMD curl -f http://localhost:8080/health || exit 1

HEALTHCHECK --interval=60s CMD curl -f http://localhost:8080/health || exit 1

A more critical, latency-sensitive service might justify the shorter interval's added overhead in exchange for faster problem detection, while a less critical background service might reasonably tolerate the longer interval.

Interaction With the Initial Start Period

A separate --start-period setting accounts for the time an application typically needs to fully start up before health checks should be taken seriously, preventing a normal startup delay from being misinterpreted as an actual health problem.

HEALTHCHECK --interval=30s --start-period=60s CMD curl -f http://localhost:8080/health || exit 1

During the first 60 seconds after the container starts, failing health checks do not immediately count toward the unhealthy threshold, giving the application time to finish starting up normally.

Observing the Configured Interval in Practice

The configured interval, and the container's actual health check history, can be inspected directly to confirm the setting is taking effect as expected.

docker inspect myapp --format '{{json .State.Health}}'

Why Choosing the Right Interval Matters

The interval setting directly trades off detection speed against overhead, and choosing a value appropriate to the specific application's criticality and resource constraints is part of designing a health check that is actually useful in practice, rather than either too slow to matter or unnecessarily resource-intensive.