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

> Discover how witr detects container healthcheck statuses by parsing runtime strings and analyzing configuration. Get clear insights for your CLI output.

- Repository: [Pranshu Parmar/witr](https://github.com/pranshuparmar/witr)
- Tags: deep-dive
- Published: 2026-08-09

---

**Witr detects container healthcheck statuses by parsing runtime status strings using the `healthFromStatus` function in [`internal/proc/runtime_dockerlike.go`](https://github.com/pranshuparmar/witr/blob/main/internal/proc/runtime_dockerlike.go) and validating healthcheck configuration presence in [`internal/source/detect.go`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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:

```go
// 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:

```go
// 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`](https://github.com/pranshuparmar/witr/blob/main/internal/proc/container.go). The construction logic populates the `Health` field by invoking `healthFromStatus` on the runtime-provided status segment:

```go
// 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`](https://github.com/pranshuparmar/witr/blob/main/internal/source/detect.go), the detection logic appends warnings when runtimes confirm no healthcheck is configured:

```go
// 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`](https://github.com/pranshuparmar/witr/blob/main/internal/output/standard.go) displays health tags in red when containers report non-healthy states:

```go
// 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`](https://github.com/pranshuparmar/witr/blob/main/internal/output/docker.go) implements conditional display logic that suppresses the health string when it equals `"healthy"`:

```go
// 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`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/internal/proc/container.go) stores normalized values ("healthy", "unhealthy", "starting") parsed from runtime outputs.
- **Configuration Detection**: [`internal/source/detect.go`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/internal/output/standard.go) and [`internal/output/docker.go`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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`](https://github.com/pranshuparmar/witr/blob/main/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.