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 ¶
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" CauseWrongDockerfilePath = "WRONG_DOCKERFILE_PATH" )
Cause codes a typed diagnosis can carry.
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.
const ( ConfidenceHigh = "high" ConfidenceMedium = "medium" ConfidenceNone = "none" )
Confidence levels Result.Confidence can hold.
const GitSourceBuildPathField = "git_source.build_path"
GitSourceBuildPathField is the Change field a Dockerfile path fix edits.
Variables ¶
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.
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
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 ¶
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 BoundSocket ¶
BoundSocket is one bound local UDP address and port.
func ParseBoundUDP ¶
func ParseBoundUDP(tables ...string) []BoundSocket
ParseBoundUDP extracts bound, unconnected UDP sockets from /proc/net/udp or /proc/net/udp6 content, in table order. Connected client sockets are skipped: they hold ephemeral ports, not services.
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.
type Change ¶ added in v0.2.0
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
// BuildType, BuildPath and DockerfileCandidates describe the git source;
// candidates are repository-root-relative Dockerfile paths.
BuildType string
BuildPath string
DockerfileCandidates []string
}
Facts are structured observations about the app and its container that the log text alone cannot supply. Zero values mean "unknown".
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.
Source Files