Health Checks and System Readiness

Offline: ze doctor

Run ze doctor before starting the daemon to verify the environment is ready. Add --json for machine-readable output with stable diagnostic codes.

ze doctor
ze doctor --json
ze doctor --json /path/to/config.conf

Each check produces a diagnostic with a code (e.g., doctor-config-reference), severity (error or warning), and message. Use ze explain <code> for remediation guidance.

Checks

Exit code 0 means ready; exit code 1 means at least one error-severity issue.

Runtime: show health

The health registry aggregates component status from the running daemon.

show health
show health | json

The /health HTTP endpoint returns the same data as JSON, with HTTP 503 when any component is down.

Registered Components

Each check completes within 1 second. Components report healthy, degraded, or down. The overall status is the worst of all components.

Runtime: show warnings / show errors

The report bus surfaces individual anomalies:

• Warnings are state-based (raised when a condition exists, cleared when it resolves). Example: session-stuck clears when the peer reaches Established.
• Errors are event-based (recorded when something happens). Example: fib-sync-failure fires once per failed route install.

show warnings
show warnings | json
show errors
show errors | json
show warnings source bgp

Report Bus Codes

Adding Doctor Checks

Plugins and components extend ze doctor by registering their own checks. There are two registration paths depending on whether the owner is a plugin.

Internal plugins (preferred)

Declare checks in registry.Registration.DoctorChecks. The doctor runner bridges these at execution time. Each check receives a DoctorCheckContext (config tree + platform) and returns diagnostics.

reg := registry.Registration{
    Name: "my-plugin",
    // ...
    DoctorChecks: []registry.DoctorCheckDef{{
        Name:         "my-plugin-reachable",
        Phase:        rpc.DoctorPhasePostConfig,
        Order:        700,
        Dependencies: []string{"config-parse"},
        Platforms:    []string{"any"},
        Codes:        []string{"doctor-my-plugin-unreachable"},
        Check:        checkMyService,
    }},
}

Reference example: internal/component/l2tp/plugins/authradius/register.go.

Non-plugin components

Components that are not plugins (appliance, web, SSH) use diagnostic.RegisterDoctorCheck() from their owning package's init().

func init() {
    diagnostic.RegisterDoctorCheck(diagnostic.DoctorCheck{
        Name:         "my-component-ready",
        Phase:        "post-config",
        Order:        500,
        Component:    "my-component",
        Dependencies: []string{"config-parse"},
        Platforms:    []string{"any"},
        Codes:        []string{"doctor-my-component-missing"},
        Check:        checkMyComponent,
    })
}

External plugins (RPC)

External plugins declare checks in DoctorChecks during Stage 1 registration, then handle the doctor-check callback at runtime.

Declaration (in sdk.Registration):

p.Run(ctx, sdk.Registration{
    DoctorChecks: []rpc.DoctorCheckDecl{{
        Name:         "my-cache-reachable",
        Phase:        rpc.DoctorPhasePostConfig,
        Order:        700,
        Dependencies: []string{"config-parse"},
        Platforms:    []string{"any"},
        Codes:        []string{"doctor-my-cache-unreachable"},
    }},
})

Callback handler:

p.OnDoctorCheck(func(name string) ([]rpc.DoctorCheckDiagnostic, error) {
    if name == "my-cache-reachable" {
        if err := pingCache(); err != nil {
            return []rpc.DoctorCheckDiagnostic{{
                Code:     "doctor-my-cache-unreachable",
                Severity: "error",
                Message:  "cache server not reachable: " + err.Error(),
            }}, nil
        }
    }
    return nil, nil
})

The engine invokes plugin checks only at runtime (show doctor), not during offline ze doctor. See docs/architecture/api/process-protocol.md for the full protocol.

Requirements

Every new doctor check must:

1. Use a diagnostic code with the doctor- prefix.
2. Register the code in internal/core/diagnostic/codes.go so ze explain <code> works.
3. Include a unit test proving the check fires when the relevant config is present and emits the registered code.