How Witr Detects Container Healthcheck Statuses: Runtime Parsing and Configuration Analysis

Witr detects container healthcheck statuses by parsing runtime status strings using the healthFromStatus function in internal/proc/runtime_dockerlike.go and validating healthcheck configuration presence in internal/source/detect.go, aggregating both signals into the Container.Health field for colorized CLI output.

Witr is an open-source container monitoring tool written in Go that analyzes running containers across multiple runtimes. Understanding how witr detects container healthcheck statuses requires examining its runtime adapters, regex-based parsing logic, and warning generation system. The implementation spans several key files in the pranshuparmar/witr repository that handle Docker-like runtimes, container model construction, and user-facing output formatting.

Parsing Runtime Status Strings with Regex

Witr extracts health states from container runtime outputs using pattern matching against status strings. The detection logic resides in the runtime adapters, particularly for Docker-compatible engines.

The healthFromStatus Function

In internal/proc/runtime_dockerlike.go, the healthFromStatus function processes raw status text to isolate health indicators. The function accepts a status string—such as "Up 4 minutes (healthy)"—and returns normalized health states:

// internal/proc/runtime_dockerlike.go
func healthFromStatus(status string) string {
    m := healthRe.FindStringSubmatch(status)
    if len(m) < 2 {
        return ""                     // no health string found
    }
    v := m[1]
    switch v {
    case "healthy", "unhealthy", "health: starting", "starting":
        return strings.TrimPrefix(v, "health: ")
    }
    return ""
}

This helper returns "healthy", "unhealthy", "starting", or an empty string when no healthcheck is wired to the container.

The Health Detection Regex Pattern

The extraction relies on healthRe, a compiled regular expression that captures text within trailing parentheses:

// internal/proc/runtime_dockerlike.go
healthRe = regexp.MustCompile(`\(([^)]+)\)\s*$`)

This pattern matches the health state appended to uptime strings by Docker, Podman, Nerdctl, and similar runtimes. When the regex matches, the first capture group contains the raw health status that healthFromStatus normalizes.

Aggregating Health Data in the Container Model

After parsing, witr assigns the extracted value to the container struct in internal/proc/container.go. The construction logic populates the Health field by invoking healthFromStatus on the runtime-provided status segment:

// internal/proc/container.go (excerpt)
parts := strings.SplitN(inspect.State.Status, " ", 6)
c := Container{
    // ... other fields ...
    Health: healthFromStatus(parts[5]), // e.g., "healthy" or "unhealthy"
}

This aggregation step ensures that downstream components access a consistent, normalized health value regardless of the specific container runtime in use.

Detecting Missing Healthcheck Configurations

Beyond parsing runtime status, witr explicitly checks whether containers lack healthcheck definitions. In internal/source/detect.go, the detection logic appends warnings when runtimes confirm no healthcheck is configured:

// internal/source/detect.go (excerpt)
if runtimeHealthcheck == "" {
    warnings = append(warnings, "Container has no healthcheck configured")
}

This validation distinguishes between containers that report health states and those without healthcheck mechanisms, enabling precise alerting for operational blind spots.

Rendering Health Status in CLI Output

Witr visualizes health information through specialized output formatters that colorize and filter health states based on severity.

Standard Output Formatting

The standard CLI renderer in internal/output/standard.go displays health tags in red when containers report non-healthy states:

// internal/output/standard.go (excerpt)
if container.Health != "" && container.Health != "healthy" {
    // Render red health tag
}

This visual cue immediately alerts operators to degraded containers without cluttering the interface with healthy indicators.

Docker-Specific Output Handling

For Docker-compatible environments, internal/output/docker.go implements conditional display logic that suppresses the health string when it equals "healthy":

// internal/output/docker.go (excerpt)
if container.Health != "" && container.Health != "healthy" {
    // Append health status to output
}

This approach maintains clean output while preserving critical visibility into starting or unhealthy containers.

Testing the Healthcheck Detection Logic

The detection pipeline is validated in internal/source/warnings_test.go, which ensures warnings emit only when ContainerHealthcheck is "absent" and the runtime-reported health status is not "healthy". These test cases verify that witr correctly suppresses false positives for containers that lack healthcheck configurations but are otherwise operational.

Summary

• Runtime Parsing: Witr uses the healthFromStatus function and \(([^)]+)\)\s*$ regex in internal/proc/runtime_dockerlike.go to extract health states from Docker-style status strings.
• Model Aggregation: The Container.Health field in internal/proc/container.go stores normalized values ("healthy", "unhealthy", "starting") parsed from runtime outputs.
• Configuration Detection: internal/source/detect.go explicitly checks for missing healthcheck definitions and generates targeted warnings when configurations are absent.
• Visual Feedback: Output formatters in internal/output/standard.go and internal/output/docker.go render health statuses with color coding, highlighting only non-healthy states to reduce noise.
• Validation: The test suite in internal/source/warnings_test.go confirms that healthcheck warnings trigger only under specific absence conditions.

Frequently Asked Questions

How does witr extract health status from Docker containers?

Witr extracts health status by applying the healthRe regular expression to the container status string provided by Docker-compatible runtimes. The healthFromStatus function in internal/proc/runtime_dockerlike.go parses strings like "Up 4 minutes (healthy)" and returns normalized values of "healthy", "unhealthy", or "starting".

What happens when a container has no healthcheck configured?

When witr detects that a container lacks a healthcheck configuration through internal/source/detect.go, it appends a warning stating "Container has no healthcheck configured" to the analysis results. This occurs when the runtime returns an empty healthcheck string, distinguishing unmonitored containers from those actively reporting health states.

Why does witr show some health statuses in red?

Witr renders health tags in red within internal/output/standard.go specifically when the Container.Health field contains a non-empty value that is not "healthy". This colorization immediately highlights containers in "unhealthy" or "starting" states, enabling rapid identification of problematic services in the terminal output.

Which container runtimes support healthcheck detection in witr?

Witr supports healthcheck detection for Docker-like runtimes including Docker, Podman, Nerdctl, and Crictl through the runtime_dockerlike.go adapter, as well as LXC and LXD through specialized runtime handlers. Each adapter normalizes runtime-specific status formats into the consistent Container.Health field used throughout the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}