lite

Documentation

Overview

Package lite provides shared building blocks for the Agent Health "invalid-config" issue.

Package lite extracts a minimum bootstrap config from a possibly-broken datadog.yaml, without depending on the full agent config layer

Index

• Constants
• func BuildInvalidConfigIssue(info IssueInfo) *healthplatform.Issue
• func DefaultConfigPath() string
• func IntakeURL(site string) string
• func Rescue(ctx context.Context, cliConfPath, defaultConfPath string, startupErr error) (err error)
• type ConfigField
• type ErrorKind
• type IssueInfo
  • func IssueInfoFromContext(ctx map[string]string) IssueInfo
  • func (info IssueInfo) Tags() []string
  • func (info IssueInfo) ToContext() map[string]string
• type LiteConfig
  • func Extract(ctx context.Context, cliConfPath, defaultConfPath string) LiteConfig
• type Source
• type ValidationResult
  • func ValidateRawConfig(raw []byte) ValidationResult
• type Verdict

Constants

const (
	ContextKeyErrorKind    = "error_kind"
	ContextKeyConfigPath   = "config_path"
	ContextKeyErrorMessage = "error_message"
	ContextKeyErrors       = "errors"
	ContextKeyErrorCount   = "error_count"
	ContextKeyImpact       = "impact"
)

Context keys used in Issue.Extra and IssueReport.Context

const DefaultSite = "datadoghq.com"

DefaultSite is the Datadog site used when nothing else resolves it.

const IssueID = "invalid-config"

IssueID is the stable Agent Health issue identifier for configuration-validation

Functions

func BuildInvalidConfigIssue

func BuildInvalidConfigIssue(info IssueInfo) *healthplatform.Issue

BuildInvalidConfigIssue produces the healthplatform.Issue for an invalid datadog.yaml. Sets kind-based tags; producers add context-specific ones (env, host) on top.

func DefaultConfigPath

func DefaultConfigPath() string

DefaultConfigPath returns the platform-default location of datadog.yaml. Callers can pass it as defaultConfPath when invoking Rescue.

func IntakeURL

func IntakeURL(site string) string

IntakeURL builds the rescue POST target for site. Falls back to DefaultSite when site is empty or fails DNS-label validation, preventing an attacker- controlled `site:` value from redirecting the request to an arbitrary host.

func Rescue

func Rescue(ctx context.Context, cliConfPath, defaultConfPath string, startupErr error) (err error)

Rescue is the one-shot orchestrator invoked from the agent's failure path (defer/recover or returned Fx error). It runs the resolver pipeline, schema-validates any config it could parse, and best-effort POSTs an Agent Health issue to the Datadog intake.

Rescue never panics. On any internal failure it returns the wrapped error for the caller to log; it must not gate process exit on the result.

Types

type ConfigField

type ConfigField struct {
	Value      string
	Source     Source
	MatchedKey string // literal key text seen in the file (fuzzy/regex tiers only)
}

ConfigField is a resolved value for a single lite-mode config key.

type ErrorKind

type ErrorKind string

ErrorKind discriminates the variant of invalid-config issue

const (
	// ErrorKindYAMLParse means yaml.Unmarshal rejected datadog.yaml outright
	ErrorKindYAMLParse ErrorKind = "yaml_parse"
	// ErrorKindSchemaValidation means the parsed map failed the embedded schema
	ErrorKindSchemaValidation ErrorKind = "schema_validation"
	// ErrorKindStartupFailure is a catch-all when the agent fails to start
	ErrorKindStartupFailure ErrorKind = "startup_failure"
)

type IssueInfo

type IssueInfo struct {
	Kind         ErrorKind
	ConfigPath   string
	ErrorMessage string // yaml_parse / startup_failure
	Errors       string // schema_validation, newline-joined
	ErrorCount   int    // schema_validation: total violation count
}

IssueInfo is the input to BuildInvalidConfigIssue.

func IssueInfoFromContext

func IssueInfoFromContext(ctx map[string]string) IssueInfo

IssueInfoFromContext is the inverse of IssueInfo.ToContext.

func (IssueInfo) Tags

func (info IssueInfo) Tags() []string

Tags returns the static tag list that pairs with this issue kind.

func (IssueInfo) ToContext

func (info IssueInfo) ToContext() map[string]string

ToContext serialises IssueInfo into the IssueReport.Context

type LiteConfig

type LiteConfig struct {
	APIKey ConfigField
	Site   ConfigField
	DDURL  ConfigField

	// APIKeyCandidates holds alternative api_key candidates the fuzzy tier
	// found alongside APIKey (sorted best-to-worst by edit distance). The
	// rescue path tries each in order to find a working key.
	APIKeyCandidates []ConfigField

	// used to decrypt ENC[handle] placeholders
	SecretBackendCommand ConfigField

	ConfigFilePath string // absolute path of the datadog.yaml we read, or ""
	FileReadErr    error
	YAMLParseErr   error          // set if the full yaml.Unmarshal failed
	ParsedConfig   map[string]any // parse config success, for schema checks
}

LiteConfig is the result of running Extract against env + datadog.yaml.

func Extract

func Extract(ctx context.Context, cliConfPath, defaultConfPath string) LiteConfig

Extract runs the tiered resolver pipeline against the process environment and the candidate datadog.yaml paths. cliConfPath is from `--cfgpath` (or empty); defaultConfPath is the platform-specific default. The first path that exists is used.

type Source

type Source string

Source records where a ConfigField value was resolved from. Order somewhat mirrors the agent's source priority

const (
	SourceNone          Source = "none"
	SourceDefault       Source = "default"
	SourceFileFuzzy     Source = "file_fuzzy"
	SourceFileRegex     Source = "file_regex"
	SourceFileYAMLTop   Source = "file_yaml_top"
	SourceFileYAMLFull  Source = "file_yaml_full"
	SourceEnv           Source = "env"
	SourceEncrypted     Source = "encrypted" // ENC[handle] not yet (or not) decrypted
	SourceSecretBackend Source = "secret_backend"
)

type ValidationResult

type ValidationResult struct {
	Verdict      Verdict
	ParseError   error
	SchemaErrors []string
	Parsed       map[string]any
}

func ValidateRawConfig

func ValidateRawConfig(raw []byte) ValidationResult

ValidateRawConfig uses the schema to validate a raw datadog.yaml Empty input is treated as VerdictOK

type Verdict

type Verdict int

Verdict is the outcome of ValidateRawConfig.

const (
	// VerdictOK means the file parsed and passed schema validation
	VerdictOK Verdict = iota
	// VerdictYAMLParseFailure means yaml.Unmarshal returned an error
	VerdictYAMLParseFailure
	// VerdictSchemaInvalid means YAML parsed but the schema produced at least one error
	VerdictSchemaInvalid
	// VerdictSchemaUnavailable means the validator itself failed
	VerdictSchemaUnavailable
)