Documentation
¶
Overview ¶
Package categorizer classifies pod failures into a single named category with an optional subcategory, based on configurable rules. It runs at the executor, where full Kubernetes pod status is available. The resulting category and subcategory are set on the Error proto attached to events.
Configuration ¶
Categories are defined in the executor config under application.errorCategories. Each category has a name and one or more rules. Rules are evaluated in config order across all categories; the first matching rule wins, setting both the category name and the rule's optional subcategory.
Each rule uses exactly one matcher:
- OnConditions: matches Kubernetes failure signals (OOMKilled, Evicted, DeadlineExceeded, AppError)
- OnExitCodes: matches non-zero container exit codes using In/NotIn set operators
- OnTerminationMessage: matches container termination messages against a regex
Exit code 0 is always skipped. Both regular and init containers are checked.
Example ¶
application:
errorCategories:
defaultCategory: "uncategorized"
defaultSubcategory: "unknown"
categories:
- name: infrastructure
rules:
- onConditions: ["OOMKilled"]
subcategory: "oom"
- onConditions: ["Evicted"]
subcategory: "eviction"
- name: user_code
rules:
- onExitCodes:
operator: In
values: [74, 75]
subcategory: "cuda"
- onTerminationMessage:
pattern: "(?i)cuda.*error"
subcategory: "cuda"
Validation ¶
NewClassifier validates all config upfront: unknown condition strings, invalid exit code operators, empty value lists, and invalid regexes all return errors at construction time.
Usage ¶
classifier, err := categorizer.NewClassifier(config.ErrorCategories)
if err != nil {
// handle invalid config
}
result := classifier.Classify(pod) // result.Category = "infrastructure", result.Subcategory = "oom"
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CategoryConfig ¶
type CategoryConfig struct {
Name string `yaml:"name"`
Rules []CategoryRule `yaml:"rules"`
}
CategoryConfig defines a named error category with rules that match against pod failure signals. The first matching rule (across all categories, in config order) wins - setting both the category name and the rule's optional subcategory.
type CategoryRule ¶
type CategoryRule struct {
ContainerName string `yaml:"containerName,omitempty"`
OnExitCodes *errormatch.ExitCodeMatcher `yaml:"onExitCodes,omitempty"`
OnTerminationMessage *errormatch.RegexMatcher `yaml:"onTerminationMessage,omitempty"`
OnConditions []string `yaml:"onConditions,omitempty"`
Subcategory string `yaml:"subcategory,omitempty"`
}
CategoryRule defines a single matching condition. Exactly one matcher must be set per rule (validated by NewClassifier). Rules within a category are OR'd. When ContainerName is set, only failures from that container are considered. When empty, failures from any container can match (default).
type Classifier ¶
type Classifier struct {
// contains filtered or unexported fields
}
Classifier evaluates pods against a set of category rules and returns the first matching category and subcategory.
func NewClassifier ¶
func NewClassifier(config ErrorCategoriesConfig) (*Classifier, error)
NewClassifier validates config and compiles regex patterns. Returns an error if any regex is invalid, a condition is unknown, or an exit code matcher has an invalid operator.
func (*Classifier) Classify ¶
func (c *Classifier) Classify(pod *v1.Pod) ClassifyResult
Classify returns the category and subcategory for the given pod. Rules are evaluated in config order; the first matching rule wins. Returns empty result if the receiver is nil or the pod is nil. Returns (defaultCategory, defaultSubcategory) if no rules match.
type ClassifyResult ¶ added in v0.20.41
ClassifyResult holds the classification output for a failed pod.
type ErrorCategoriesConfig ¶ added in v0.20.41
type ErrorCategoriesConfig struct {
// DefaultCategory is the category assigned when no rule matches.
// If empty, no category is assigned when no rule matches.
DefaultCategory string `yaml:"defaultCategory"`
// DefaultSubcategory is the subcategory assigned when no rule matches.
// If empty, no subcategory is assigned when no rule matches.
DefaultSubcategory string `yaml:"defaultSubcategory"`
Categories []CategoryConfig `yaml:"categories"`
}
ErrorCategoriesConfig is the top-level config for failure classification.
Source Files