datadog_agent_config/classifier/

mod.rs

//! Configuration key classifier.
//!
//! A programmatic registry of all recognized configuration keys. Each entry describes the key
//! purely from the configuration system's perspective: its canonical YAML path, the environment
//! variables that map to it, the shape of its value, and which internal config structs consume it.
//!
//! This registry is intentionally free of Rust field names and struct internals—it models the
//! configuration surface as an operator would see it, and can be used at runtime to detect
//! unknown or unsupported keys in a loaded configuration file.
//!
//! ## User Guide
//!
//! The registry is generated at build time from `schema_overlay.yaml`, which partitions every
//! key in `core_schema.yaml` into exactly one of: supported, unsupported, or ignored. Data
//! integrity (uniqueness, full coverage, sorted sections) is enforced by `SchemaOverlay::load()`
//! during the build.
//!
//! ### Adding a Configuration Key
//!
//! Add a `supported` entry in `lib/datadog-agent/config/schema/schema_overlay.yaml` with
//! `support_level`, `pipelines`, `used_by`, `description`, and `config_registry_filename`.
//! The build generates the annotation constants automatically.
//!
//! ### Updating the Vendored Schema
//!
//! After updating `core_schema.yaml`, the build will fail if any new keys are not covered
//! by the overlay. For each new key, add it to the appropriate section of
//! `schema_overlay.yaml`.

#[allow(clippy::module_inception)]
mod classifier;

pub use classifier::{Classification, ConfigClassifier};

/// Identifiers for known configuration consumers.
///
/// Used as values in annotation `used_by` fields to declare which consumers incorporate a key.
pub mod structs {
    /// Identifier for `ProxyConfiguration`.
    pub const PROXY_CONFIGURATION: &str = "ProxyConfiguration";
    /// Identifier for `ForwarderConfiguration`.
    pub const FORWARDER_CONFIGURATION: &str = "ForwarderConfiguration";
    /// Identifier for `DogStatsDConfiguration`.
    pub const DOGSTATSD_CONFIGURATION: &str = "DogStatsDConfiguration";
    /// Identifier for `ContainerdConfiguration`.
    pub const CONTAINERD_CONFIGURATION: &str = "ContainerdConfiguration";
    /// Identifier for `AggregateConfiguration`.
    pub const AGGREGATE_CONFIGURATION: &str = "AggregateConfiguration";
    /// Identifier for `DogStatsDMapperConfiguration`.
    pub const DOGSTATSD_MAPPER_CONFIGURATION: &str = "DogStatsDMapperConfiguration";
    /// Identifier for `DogStatsDDebugLogConfiguration`.
    pub const DOGSTATSD_DEBUG_LOG_CONFIGURATION: &str = "DogStatsDDebugLogConfiguration";
    /// Identifier for `DogStatsDPrefixFilterConfiguration`.
    pub const DOGSTATSD_PREFIX_FILTER_CONFIGURATION: &str = "DogStatsDPrefixFilterConfiguration";
    /// Identifier for `DatadogMetricsConfiguration`.
    pub const DATADOG_METRICS_CONFIGURATION: &str = "DatadogMetricsConfiguration";
    /// Identifier for `DatadogTraceConfiguration`.
    pub const DATADOG_TRACE_CONFIGURATION: &str = "DatadogTraceConfiguration";
    /// Identifier for `DatadogLogsConfiguration`.
    pub const DATADOG_LOGS_CONFIGURATION: &str = "DatadogLogsConfiguration";
    /// Identifier for `DatadogEventsConfiguration`.
    pub const DATADOG_EVENTS_CONFIGURATION: &str = "DatadogEventsConfiguration";
    /// Identifier for `DatadogServiceChecksConfiguration`.
    pub const DATADOG_SERVICE_CHECKS_CONFIGURATION: &str = "DatadogServiceChecksConfiguration";
    /// Identifier for `DatadogApmStatsEncoderConfiguration`.
    pub const DATADOG_APM_STATS_ENCODER_CONFIGURATION: &str = "DatadogApmStatsEncoderConfiguration";
    /// Identifier for `MrfConfiguration`.
    pub const MRF_CONFIGURATION: &str = "MrfConfiguration";
    /// Identifier for `TraceObfuscationConfiguration`.
    pub const TRACE_OBFUSCATION_CONFIGURATION: &str = "TraceObfuscationConfiguration";
    /// Identifier for `RemoteAgentClientConfiguration`.
    pub const REMOTE_AGENT_CLIENT_CONFIGURATION: &str = "RemoteAgentClientConfiguration";
    /// Identifier for `TagFilterlistConfiguration`.
    pub const TAG_FILTERLIST_CONFIGURATION: &str = "TagFilterlistConfiguration";
    /// Keys consumed through the typed configuration translation system.
    pub const TYPED_CONFIG_SYSTEM: &str = "TypedConfigSystem";
    /// Keys read via `get_typed` / `try_get_typed` rather than struct deserialization.
    pub const GET_TYPED: &str = "get_typed";
}

/// The ADP pipeline a config key affects.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Pipeline {
    /// DogStatsD metrics pipeline.
    DogStatsD,
    /// Agent checks pipeline.
    Checks,
    /// OTLP ingestion frontend.
    Otlp,
    /// Internal trace processing. Active when OTLP is enabled and proxy/relay mode (which uses the
    /// core Agent for transport) is off.
    Traces,
}

/// Which pipelines a config key affects.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PipelineAffinity {
    /// The list of pipelines affected by the key.
    ///
    /// This list must be non-empty, enforced by test.
    Pipelines(&'static [Pipeline]),
    /// The key affects all pipelines or ADP behavior as a whole.
    CrossCutting,
}

/// The `Severity` level of a config key that Saluki doesn't support.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Severity {
    /// Saluki's incompatibility with the key is considered minor.
    Low,

    /// Saluki's incompatibility with the key is considered potentially impactful.
    Medium,

    /// Saluki's incompatibility with the key is considered problematic.
    High,
}

/// The support level for a given configuration key.
///
/// Full support is omitted from the enum and those keys are not classified since there is nothing
/// to be done about them downstream.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SupportLevel {
    /// Partially supported.
    Partial,
    /// Explicitly incompatible.
    Incompatible(Severity),
    /// Intentionally ignored.
    #[allow(unused)]
    Ignored,
    /// Unrecognized.
    #[allow(unused)]
    Unrecognized,
}

/// The default value for a config key, as resolved at build time from the Agent schema.
///
/// Durations are normalized to nanoseconds during codegen (the build fails if a `format:
/// duration` default isn't a valid Go duration), so the runtime default check never has to parse a
/// schema default. Other keys keep their JSON-literal default and are compared structurally.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DefaultValue {
    /// The schema declares no default for this key.
    Missing,
    /// A JSON-encoded default value (for example, `"\"tlsv1.2\""` or `"1"`).
    Json(&'static str),
    /// A `format: duration` default, already parsed to nanoseconds. The Agent transmits durations
    /// as integer nanoseconds, so the incoming value is normalized the same way before comparing.
    DurationNanos(u64),
}

/// Slim per-key data generated at build time for the classifier.
///
/// Carries only what the classifier needs: enough to look up a key, determine its support level,
/// check whether a value is the default, and report which pipelines are affected.
pub struct ClassifierEntry {
    /// Canonical dot-separated YAML path.
    pub yaml_path: &'static str,
    /// Additional YAML paths (aliases) that resolve to this key.
    pub aliases: &'static [&'static str],
    /// How well saluki supports this key.
    pub support_level: SupportLevel,
    /// Which pipelines this key affects.
    pub pipeline_affinity: PipelineAffinity,
    /// Default value from the Agent schema (normalized at build time).
    pub default: DefaultValue,
}

use crate::generated::classifier_data::CLASSIFIER_ENTRIES;