saluki_components/config_registry/

mod.rs

//! Configuration key registry.
//!
//! 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 config registry tests enforce uniqueness and completeness constraints similar to
//! primary-key and unique constraints in a relational database. Every key in the vendored
//! schema (`core_schema.yaml`) must appear in exactly one of two places: an annotation
//! ([`SalukiAnnotation`]) or the ignored-keys list (`etc/ignored_keys.yaml`). No key may
//! appear in both, and no key may appear twice within either list.
//!
//! If a test fails, it means one of these constraints was violated. Common scenarios:
//!
//! ### Adding a Configuration Key
//!
//! When Saluki gains support for a new key, add a [`SalukiAnnotation`] in the appropriate
//! `config_registry::datadog::*` submodule with [`SupportLevel::Full`] or
//! [`SupportLevel::Partial`] and a non-empty `used_by` list. If the key was previously in
//! `etc/ignored_keys.yaml`, remove it from there. If it was previously
//! [`SupportLevel::Incompatible`], move it from `datadog/unsupported.rs` to the
//! appropriate submodule and update its support level.
//!
//! ### Updating the Vendored Schema
//!
//! After updating `vendor/core_schema.yaml`, rebuild to regenerate the schema module
//! (the `build.rs` script handles this automatically). Any new keys will cause the
//! `all_schema_entries_are_annotated_or_ignored` test to fail. For each new key, decide:
//!
//! - **Irrelevant to ADP**: add to `etc/ignored_keys.yaml` with a reason.
//! - **Incompatible**: add to `datadog/unsupported.rs` with a [`Severity`] level.
//! - **Supported**: add to the appropriate `datadog/*.rs` submodule.
//!
//! If the update removed keys, the `no_stale_entries` test catches annotations or
//! ignored entries that reference keys no longer in the schema. Delete the stale entries.

mod classifier;
pub mod datadog;
/// Generated schema entries from the vendored Datadog Agent config schema.
pub mod generated;

pub use classifier::{Classification, ConfigClassifier};

pub(crate) use self::datadog::ALL_ANNOTATIONS;
#[cfg(any(test, feature = "config-test-support"))]
pub(crate) use self::datadog::SUPPORTED_ANNOTATIONS;
#[cfg(test)]
pub(crate) use self::generated::schema::ALL_SCHEMA_ENTRIES;
#[cfg(test)]
pub(crate) use self::generated::schema::IGNORED_ENTRIES;

/// Declares a set of [`SalukiAnnotation`] constants and generates a companion `ALL` slice.
///
/// Each entry declares one named `pub const` annotation. The macro also emits:
///
/// ```ignore
/// pub const ALL: &[&SalukiAnnotation] = &[&NAME1, &NAME2, ...];
/// ```
///
/// so that `datadog/mod.rs` can aggregate submodules with a single
/// `v.extend_from_slice(my_module::ALL)` line rather than listing every constant by name.
///
/// # Example
///
/// ```ignore
/// declare_annotations! {
///     /// Doc comment for PROXY_HTTP.
///     PROXY_HTTP = SalukiAnnotation { ... };
///     PROXY_HTTPS = SalukiAnnotation { ... };
/// }
/// ```
#[macro_export]
macro_rules! declare_annotations {
    ( $( $(#[$attr:meta])* $name:ident = $val:expr ;)+ ) => {
        $(
            $(#[$attr])*
            pub const $name: $crate::config_registry::SalukiAnnotation = $val;
        )+

        /// All annotations declared in this module, in declaration order.
        pub const ALL: &[$crate::config_registry::SalukiAnnotationRef] = &[
            $( &$name, )+
        ];
    };
}

/// Shared helpers for config smoke tests.
#[cfg(any(test, feature = "config-test-support"))]
pub mod test_support;

/// Identifiers for known configuration structs.
///
/// Used as values in [`SalukiAnnotation::used_by`] to declare which structs consume a given key.
/// Adding a new struct here is the first step when registering its configuration keys.
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 `OtlpConfiguration`.
    pub const OTLP_CONFIGURATION: &str = "OtlpConfiguration";
    /// 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 `OtlpDecoderConfiguration`.
    pub const OTLP_DECODER_CONFIGURATION: &str = "OtlpDecoderConfiguration";
    /// Identifier for `OtlpRelayConfiguration`.
    pub const OTLP_RELAY_CONFIGURATION: &str = "OtlpRelayConfiguration";
    /// Identifier for `TraceObfuscationConfiguration`.
    pub const TRACE_OBFUSCATION_CONFIGURATION: &str = "TraceObfuscationConfiguration";
    /// Identifier for `RemoteAgentClientConfiguration`.
    pub const REMOTE_AGENT_CLIENT_CONFIGURATION: &str = "RemoteAgentClientConfiguration";
    /// 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.
///
/// Primary user-controlled toggles are represented.
#[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 [`SalukiAnnotation`] affects.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PipelineAffinity {
    /// The list of pipelines affected by the `SalukiAnnotation`.
    ///
    /// This list must be non-empty, enforced by test.
    Pipelines(&'static [Pipeline]),
    /// The `SalukiAnnotation` 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,
}

/// How well saluki supports a given configuration key.
///
/// Used in [`SalukiAnnotation`] to classify each key from saluki's perspective. `Ignored` is
/// reserved for keys in the schema that have no annotation at all—it must not appear in any
/// handwritten annotation.
///
/// Invariants enforced at test time:
/// - `Full` and `Partial` require a non-empty `used_by` list.
/// - `Incompatible` requires an empty `used_by` list.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SupportLevel {
    /// Fully supported. The key is wired up end-to-end and must be consumed by at least one struct.
    Full,
    /// Partially supported. The key is consumed by at least one struct, but support is incomplete.
    Partial,
    /// Explicitly incompatible. Saluki doesn't support this key and may not behave as expected in
    /// its presence; `used_by` must be empty. Support for the key may be added in the future but
    /// tracking such intent isn't encoded here.
    Incompatible(Severity),
    /// Intentionally ignored. The key isn't relevant to Saluki. This assignment must be
    /// intentionally chosen and specified for a key. We never assume that a key is `Ignored` just
    /// because we're unaware of it.
    #[allow(unused)]
    Ignored,
    /// Unrecognized. The Saluki codebase is unaware of the existence of this key. It's not in our
    /// vendored datadog config schema, nor is it annotated.
    #[allow(unused)]
    Unrecognized,
}

/// The shape of a configuration value.
///
/// Describes how a value should be parsed from both YAML and environment variables.
/// `StringList` values are represented as a YAML sequence or a space-separated string in env vars.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ValueType {
    /// A boolean (`true` / `false`).
    Bool,
    /// A UTF-8 string.
    String,
    /// An unsigned integer.
    Integer,
    /// A floating-point number.
    Float,
    /// A list of strings (YAML sequence or space-separated env var string).
    StringList,
}

/// Which schema source of truth defined the `SchemaEntry`
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
#[repr(u8)]
pub(crate) enum Schema {
    /// Saluki defined the `SchemaEntry` and the key isn't expected to exist in the vendored Datadog config schema.
    Saluki,
    /// The vendored Datadog config schema defines the `SchemaEntry`.
    Datadog,
}

/// Schema-derived metadata for a single configuration key.
///
/// Generated from the vendored Datadog Agent config schema. Contains only what the schema
/// knows: the canonical YAML path, declared environment variables, and value type. Saluki-specific
/// fields (`used_by`, etc.) live in [`SalukiAnnotation`] instead.
///
/// Don't construct these manually—they're produced by `cargo xtask gen-config-schema` and
/// live in `config_registry::generated::schema`.
#[derive(Debug)]
pub struct SchemaEntry {
    /// The source of truth from which this entry was derived.
    #[allow(dead_code)]
    pub(crate) schema: Schema,

    /// Canonical dot-separated YAML path for this key (for example, `"proxy.http"`).
    pub yaml_path: &'static str,

    /// Environment variables that deliver this value, as declared in the schema.
    ///
    /// Empty when the schema marks the key `no-env` or lists no env vars. Annotations may
    /// override this with additional or corrected env vars.
    pub env_vars: &'static [&'static str],

    /// Shape of the value.
    pub value_type: ValueType,

    /// JSON-encoded default value from the Agent schema, if present.
    ///
    /// Examples: `Some("true")`, `Some("8125")`, `Some("\"datadoghq.com\"")`, `None`.
    /// Used by smoke tests to auto-detect when a generic test value matches the default
    /// and flip it so the test actually exercises the field.
    pub default: Option<&'static str>,
}

/// Saluki-specific annotation for a single configuration key.
///
/// Pairs a [`SchemaEntry`] (generated from the vendored schema) with the metadata that only
/// saluki knows: which internal config structs consume the key, and any corrections to the
/// schema's env var list.
///
/// These are hand-written constants, one per key saluki cares about, and live in
/// `config_registry::datadog::*` submodules. They're never overwritten by codegen.
#[derive(Debug)]
pub struct SalukiAnnotation {
    /// The schema entry this annotation enriches.
    pub schema: &'static SchemaEntry,

    /// How well saluki supports this key.
    ///
    /// Must not be [`SupportLevel::Ignored`] or [`SupportLevel::Unrecognized`] which are reserved
    /// for unannotated keys.
    pub support_level: SupportLevel,

    /// Additional YAML paths beyond the canonical one in the schema (aliases).
    ///
    /// Most keys have no aliases; leave this as `&[]` unless the config system recognises
    /// the key under more than one dot-separated path.
    pub additional_yaml_paths: &'static [&'static str],

    /// Overrides the schema's `env_vars` list entirely when `Some`.
    ///
    /// Use when the schema marks a key `no-env` but env vars are actually supported, or when
    /// the schema's list is incorrect or incomplete (for example, the proxy sub-keys).
    pub env_var_override: Option<&'static [&'static str]>,

    /// Config structs that incorporate this key, as [`structs`] constants.
    ///
    /// Must be non-empty for [`SupportLevel::Full`] and [`SupportLevel::Partial`].
    /// Must be empty for [`SupportLevel::Incompatible`].
    pub used_by: &'static [&'static str],

    /// Overrides the schema's `value_type` when `Some`.
    ///
    /// Use when the schema declares a key as `Float` but the consuming Rust field is `i32` (or
    /// similarly mismatched), so that smoke tests inject a value the struct can actually parse.
    pub value_type_override: Option<ValueType>,

    /// Overrides the smoke-test injected value entirely when `Some`.
    ///
    /// Must be a valid JSON literal (for example, `Some("[{\"name\":\"test\"}]")`). Use when the field
    /// requires a structured value that the generic `ValueType`-derived test values can't satisfy
    /// (for example, JSON-encoded arrays or objects).
    pub test_json: Option<&'static str>,

    /// Which pipelines this key affects.
    pub pipeline_affinity: PipelineAffinity,
}

/// A reference to a [`SalukiAnnotation`], used as the element type of `ALL` slices generated by
/// [`declare_annotations!`].
pub type SalukiAnnotationRef = &'static SalukiAnnotation;

impl SalukiAnnotation {
    /// The canonical YAML path for this key (from the schema).
    pub fn yaml_path(&self) -> &'static str {
        self.schema.yaml_path
    }

    /// All YAML paths for this key: canonical first, then any aliases.
    pub fn all_yaml_paths(&self) -> impl Iterator<Item = &'static str> {
        std::iter::once(self.schema.yaml_path).chain(self.additional_yaml_paths.iter().copied())
    }

    /// Effective env vars: the override list if set, otherwise the schema's list.
    pub fn effective_env_vars(&self) -> &'static [&'static str] {
        self.env_var_override.unwrap_or(self.schema.env_vars)
    }

    /// Shape of the value: override if set, otherwise from the schema.
    pub fn value_type(&self) -> ValueType {
        self.value_type_override.unwrap_or(self.schema.value_type)
    }
}

/// A fully resolved configuration key, derived from a [`SalukiAnnotation`] at registry init time.
///
/// Used for runtime unknown-key detection and anywhere a flattened, owned view of a key is
/// needed. For test infrastructure, prefer working with [`SalukiAnnotation`] directly.
#[derive(Debug)]
pub struct ConfigKey {
    /// All dot-separated YAML paths that deliver this value.
    pub yaml_paths: Vec<&'static str>,

    /// All environment variables that deliver this value.
    pub env_vars: Vec<&'static str>,

    /// Shape of the value.
    pub value_type: ValueType,

    /// Config structs that incorporate this key, as [`structs`] constants.
    pub used_by: &'static [&'static str],
}

impl From<&SalukiAnnotation> for ConfigKey {
    fn from(a: &SalukiAnnotation) -> Self {
        ConfigKey {
            yaml_paths: a.all_yaml_paths().collect(),
            env_vars: a.effective_env_vars().to_vec(),
            value_type: a.value_type(),
            used_by: a.used_by,
        }
    }
}