19.2.6.5 Inspect Health Output

When you run docker inspect on a container that has a health check configured, the output includes a State.Health section containing the container current health status along with a history of recent health check executions. This section is only present if the container was started with a HEALTHCHECK instruction in its image or with health check flags in the docker run command.

Accessing Health Output

docker inspect <container_name_or_id>

To extract only the health section:

docker inspect --format "{{json .State.Health}}" my_container

To get just the current health status:

docker inspect --format "{{.State.Health.Status}}" my_container

Health Status Values

The Status field in State.Health can be one of four values:

• starting: The container has started but the health check has not yet produced a result. This is the initial state while Docker waits for the first check to complete or the start period to elapse.
• healthy: The most recent health check exited with code 0, and the container is considered operational.
• unhealthy: The health check has failed consecutively for the configured number of retries, and the container is considered non-functional.
• none: No health check is configured for this container.

Full Health Output Structure

"State": {
  "Status": "running",
  "Running": true,
  "Health": {
    "Status": "healthy",
    "FailingStreak": 0,
    "Log": [
      {
        "Start": "2024-03-15T10:25:00.000000000Z",
        "End": "2024-03-15T10:25:00.123456789Z",
        "ExitCode": 0,
        "Output": ""
      },
      {
        "Start": "2024-03-15T10:24:30.000000000Z",
        "End": "2024-03-15T10:24:30.098765432Z",
        "ExitCode": 0,
        "Output": ""
      }
    ]
  }
}

FailingStreak

The FailingStreak field counts how many consecutive health check failures have occurred since the last successful check. When a health check succeeds, this resets to 0. When it reaches the configured retries threshold, the container transitions to the unhealthy status.

For example, if retries is set to 3 and a check fails three times in a row, FailingStreak becomes 3 and the container is marked unhealthy.

Log Array

The Log array holds the results of recent health check executions. Docker retains the last five check results by default:

"Log": [
  {
    "Start": "2024-03-15T10:30:00.000000000Z",
    "End": "2024-03-15T10:30:00.215000000Z",
    "ExitCode": 1,
    "Output": "curl: (7) Failed to connect to localhost port 8080: Connection refused\n"
  },
  {
    "Start": "2024-03-15T10:29:30.000000000Z",
    "End": "2024-03-15T10:29:30.189000000Z",
    "ExitCode": 0,
    "Output": ""
  }
]

Each log entry contains:

• Start: ISO 8601 timestamp when the health check command started executing.
• End: ISO 8601 timestamp when the health check command finished executing.
• ExitCode: The exit code of the health check command. 0 means healthy, any non-zero value means the check failed. The special code 137 indicates the check was killed, typically due to exceeding the timeout.
• Output: Standard output and standard error from the health check command. Empty if the command succeeded silently. This output is what you use to understand why a health check is failing.

Health Check Configuration

The health check parameters that govern how the log entries are produced come from Config.Healthcheck:

"Config": {
  "Healthcheck": {
    "Test": ["CMD", "curl", "-f", "http://localhost:8080/health"],
    "Interval": 30000000000,
    "Timeout": 10000000000,
    "Retries": 3,
    "StartPeriod": 60000000000
  }
}

• Test: The command to run. CMD runs the command directly; CMD-SHELL runs it through the shell.
• Interval: Time in nanoseconds between each health check run.
• Timeout: Maximum time in nanoseconds the check is allowed to run before being killed.
• Retries: Number of consecutive failures required before the container is declared unhealthy.
• StartPeriod: Grace period in nanoseconds after the container starts during which failures do not count toward the Retries threshold.

Setting a Health Check at Runtime

You can override or add a health check when running a container:

docker run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  --health-start-period 60s \
  my_image

Diagnosing a Failing Health Check

When a container is unhealthy, the most useful information is in the Output field of the failed log entries:

docker inspect --format "{{range .State.Health.Log}}ExitCode: {{.ExitCode}} Output: {{.Output}}{{println}}{{end}}" my_container

Common failure patterns visible in Output:

• Connection refused: The application process is not listening on the expected port.
• curl: (6) Could not resolve host: DNS resolution failure.
• Non-empty error output from custom scripts indicating application-level errors.
• Empty output with a non-zero exit code: The process exited with an error but produced no output.

Checking Health in Scripts

Health status from inspect is useful in deployment scripts and orchestration:

STATUS=$(docker inspect --format "{{.State.Health.Status}}" my_container)
if [ "$STATUS" = "healthy" ]; then
  echo "Container is ready"
else
  echo "Container is not healthy: $STATUS"
  exit 1
fi

Health and Docker PS

The health status is also visible in docker ps output in the STATUS column, which shows the status as (healthy), (unhealthy), or (health: starting) appended to the running state. The docker inspect output provides the detailed log that docker ps does not show.

docker ps --format "{{.Names}}\t{{.Status}}"

my_container    Up 2 hours (healthy)
other_container Up 30 minutes (unhealthy)

The health output in docker inspect is essential for monitoring container readiness, debugging application startup failures, and verifying that services are functional before routing traffic to them.