Skip to content

container/ps: add HealthStatus formatter field#6913

Open
Mohammed-Thaha wants to merge 3 commits intodocker:masterfrom
Mohammed-Thaha:6203-add-healthcheck-format
Open

container/ps: add HealthStatus formatter field#6913
Mohammed-Thaha wants to merge 3 commits intodocker:masterfrom
Mohammed-Thaha:6203-add-healthcheck-format

Conversation

@Mohammed-Thaha
Copy link
Copy Markdown

@Mohammed-Thaha Mohammed-Thaha commented Apr 5, 2026

- What I did

Added a new docker ps --format placeholder: .HealthStatus, so users can print container health state directly as a dedicated field.

- How I did it

  • Added HealthStatus() to the container formatter context.
  • Returned health directly from c.c.Health.Status when available.
  • Added fallback parsing from .Status text for:
    • (healthy) -> healthy
    • (unhealthy) -> unhealthy
    • (health: starting) -> starting
  • Updated docs in docs/reference/commandline/container_ls.md to include .HealthStatus in the format placeholders table.
  • Added/updated unit tests in cli/command/formatter/container_test.go.

- How to verify it

  1. Start dev shell:

    make -f docker.Makefile shell
  2. Build the CLI binary:

    make binary
  3. Run a container that stays in starting during the start period:

    docker rm -f hc-starting 2>/dev/null || true
    
    ./build/docker-linux-amd64 run -d --name hc-starting \
      --health-cmd='exit 1' \
      --health-start-period=2m \
      --health-interval=5s \
      --health-retries=1 \
      alpine sh -c 'sleep 300'
  4. Verify formatter output:

    ./build/docker-linux-amd64 ps -a --filter name=hc-starting --format "table {{.Names}}\t{{.Status}}\t{{.HealthStatus}}"

Expected result:

  • STATUS contains (health: starting)
  • HEALTHSTATUS shows starting

- Human readable description for the release notes

`docker ps --format` now supports a `.HealthStatus` placeholder to print container health state (`starting`, `healthy`, `unhealthy`) as a dedicated field.

- A picture of a cute animal (not mandatory but encouraged)

Signed-off-by: Mohammed Thaha <mohammedthahacse@gmail.com>
Copy link
Copy Markdown
Member

@thaJeztah thaJeztah left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this! I left some comments/suggestions; feedback welcome!

Comment thread cli/command/formatter/container.go Outdated
// HealthCheck returns the container's health status (for example, "healthy","unhealthy", or "starting").
// If no healthcheck is configured, an empty
// string is returned.
func (c *ContainerContext) HealthCheck() string {
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should name this HealthStatus, as it's not showing information about the health-check otherwise.

Comment thread cli/command/formatter/container.go Outdated
return string(c.c.Health.Status)
}

// Fallback for daemons/API versions that include health only in Status text.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'd be good to reference the API version that introduced the new field to save future visitors of this code to decide whether the fallback is still needed (and perhaps a link to the pull request for future reference);

// Fallback for API versions before v1.52,  which include health only in Status text;
// see https://github.com/moby/moby/pull/50281
// see https://github.com/moby/moby/blob/docker-v29.4.3/daemon/container/health.go#L18-L43

Comment thread cli/command/formatter/container.go Outdated
Comment on lines +366 to +375
switch {
case strings.HasSuffix(c.c.Status, "(healthy)"):
return string(container.Healthy)
case strings.HasSuffix(c.c.Status, "(unhealthy)"):
return string(container.Unhealthy)
case strings.HasSuffix(c.c.Status, "(health: starting)"):
return string(container.Starting)
}

return ""
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should slightly optimise here; also adding an early return; something like;

_, health, ok := strings.Cut(c.c.Status, "(")
if !ok || !strings.HasSuffix(health, ")") {
	return ""
}


health = strings.TrimSuffix(health, ")")
health = strings.TrimPrefix(health, "health: ")

switch container.Health(health){
case container.Healthy, container.Unhealthy, container.Starting:
	return health
default:
	return ""
}

Slightly ugly because of the health: prefix but it makes it slightly more explicit that we're matching specific states.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Used parsedHealth := container.HealthStatus(health) before the switch so the parsed value matches the container.Healthy, container.Unhealthy, and container.Starting typed constants during comparison.

Comment thread cli/command/formatter/container.go Outdated
localVolumes = "LOCAL VOLUMES"
networksHeader = "NETWORKS"
platformHeader = "PLATFORM"
healthCheckHeader = "HEALTHCHECK"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related to my other comment; perhaps HEALTH STATUS

@thaJeztah thaJeztah added this to the 29.5.0 milestone May 8, 2026
@Mohammed-Thaha Mohammed-Thaha changed the title container/ps: add HealthCheck formatter field container/ps: add HealthStatus formatter field May 9, 2026
Signed-off-by: Mohammed Thaha <mohammedthahacse@gmail.com>
@Mohammed-Thaha Mohammed-Thaha force-pushed the 6203-add-healthcheck-format branch from 7c2e8b2 to ef9f2b7 Compare May 9, 2026 02:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

update docs, tests, local changes for "HealthCheck" in "ps" response

2 participants