diagnose

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package diagnose is a deterministic, pure-Go pattern matcher over diagnostic signals the platform already collects: deploy attempt status/error, reconcile condition reason strings, crashloop alert state, and recent log lines. It is a read-and-suggest layer on top of the platform API, per this project's AI design rule: it never calls an external model, never writes to any resource, and never influences the reconciler. Every explanation this package returns is backed by a literal signal it read; when nothing matches, Diagnose returns the fallback response rather than a guess.

Index

Constants

View Source 
const (
	CauseWrongPort        = "WRONG_PORT"
	CauseOOMKilled        = "OOM_KILLED"
	CauseMissingEnv       = "MISSING_ENV"
	CausePortInUse        = "PORT_IN_USE"
	CausePermissionDenied = "PERMISSION_DENIED"
	CauseExecFormatError  = "EXEC_FORMAT_ERROR"
	CauseCommandNotFound  = "COMMAND_NOT_FOUND"
	CauseHealthcheckFail  = "HEALTHCHECK_FAILING"
	CauseCrashloopGeneric = "CRASHLOOP_GENERIC"
	CauseImagePullFailed  = "IMAGE_PULL_FAILED"
	CauseBuildOutOfDisk   = "BUILD_OUT_OF_DISK"
)

Cause codes a typed diagnosis can carry.

View Source 
const (
	FixPatch  = "patch"  // every change has a concrete value, safe to apply as previewed
	FixInput  = "input"  // at least one change needs a value the operator supplies
	FixManual = "manual" // no API setter exists, Hint says what to do
)

Fix kinds.

View Source 
const (
	ConfidenceHigh   = "high"
	ConfidenceMedium = "medium"
	ConfidenceNone   = "none"
)

Confidence levels Result.Confidence can hold.

Variables

View Source 
var HealthPathCandidates = []string{"/healthz", "/health", "/", "/api/health", "/up", "/status", "/ping"}

HealthPathCandidates are the readiness paths tried, in order, when a probe gets a 404 from the configured one.

View Source 
var OOMLogPatterns = []string{"oomkilled", "out of memory", "exit code 137", "code: 137", "exit status 137"}

OOMLogPatterns are the lowercase substrings that identify a log line as an OOM-kill signal, shared with internal/rightsizing so that package's resource-recommendation engine treats "this app was OOM-killed" as the same tracked signal this package already diagnoses, not a second, possibly-drifting definition of the same thing.

Functions

func ParseListeningPorts added in v0.2.0 

func ParseListeningPorts(tables ...string) []int

ParseListeningPorts extracts listening TCP ports from /proc/net/tcp or /proc/net/tcp6 content. Ports bound to every address come first, then other non-loopback ports, then loopback-only ones, each group ascending.

Types

type AttemptInput 

type AttemptInput struct {
	Status string
	Error  string
}

AttemptInput is the deploy attempt signal, nil if the caller found no attempt to diagnose (e.g. an app that has never been deployed).

type Cause added in v0.2.0 

type Cause struct {
	Code        string
	Title       string
	Explanation string
	Confidence  string
	Evidence    []Signal
	Fixes       []Fix
}

Cause is one typed, evidence-backed reason for a failure.

func Analyze added in v0.2.0 

func Analyze(in Input) []Cause

Analyze runs every typed rule over in and returns causes ordered by confidence, then rule order, with fixes numbered across the whole slice.

type Change added in v0.2.0 

type Change struct {
	Field      string
	From       string
	To         string
	NeedsInput bool
}

Change is one field edit a fix proposes. Field uses the app resource's own JSON paths, with env vars as "env.NAME".

type ConditionInput 

type ConditionInput struct {
	Type, Status, Reason, Message string
}

ConditionInput is one reconcile condition, the same shape GET /api/v1/apps/{name}/deploys already returns.

type CrashloopInput 

type CrashloopInput struct {
	Firing                bool
	RestartCount          int
	RestartCountThreshold int
	RestartWindow         string
}

CrashloopInput is a crashloop alert rule's current evaluation state, nil if no crashloop rule is configured for this app.

type Facts added in v0.2.0 

type Facts struct {
	Port           int
	HealthPath     string
	MemoryBytes    int64
	OOMFactor      float64
	HasExit        bool
	ExitCode       int
	OOMKilled      bool
	NodeArch       string
	ListeningPorts []int
	ExposedPorts   []int
	EnvKeys        []string
	BuildFailed    bool
}

Facts are structured observations about the app and its container that the log text alone cannot supply. Zero values mean "unknown".

type Fix added in v0.2.0 

type Fix struct {
	N        int
	Label    string
	Kind     string
	Changes  []Change
	Hint     string
	Redeploy bool
}

Fix is one remedy for a Cause. N is 1-based and unique across a Result.

type Input 

type Input struct {
	ServiceName    string
	Attempt        *AttemptInput
	Conditions     []ConditionInput
	Crashloop      *CrashloopInput
	RecentLogLines []string
	Facts          Facts
}

Input bundles every signal Diagnose considers. Every field is optional except ServiceName: a caller with fewer signals available (no telemetry configured, no crashloop rule set up) still gets a best-effort result, it just has less evidence to draw on.

type Result 

type Result struct {
	Explanation    string
	Suggestion     string
	Confidence     string
	MatchedSignals []Signal
	Causes         []Cause
}

Result is what Diagnose returns.

func Diagnose 

func Diagnose(in Input) Result

Diagnose synthesizes in's signals into a human-readable explanation and suggested next action. Deterministic: the same Input always produces the same Result.

type Signal 

type Signal struct {
	Source  string
	Excerpt string
}

Signal is one piece of evidence a signature matched against, always tied to the literal text it was read from.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.