datadog_agent_config/classifier/
mod.rs

1//! Configuration key classifier.
2//!
3//! A programmatic registry of all recognized configuration keys. Each entry describes the key
4//! purely from the configuration system's perspective: its canonical YAML path, the environment
5//! variables that map to it, the shape of its value, and which internal config structs consume it.
6//!
7//! This registry is intentionally free of Rust field names and struct internals—it models the
8//! configuration surface as an operator would see it, and can be used at runtime to detect
9//! unknown or unsupported keys in a loaded configuration file.
10//!
11//! ## User Guide
12//!
13//! The registry is generated at build time from `schema_overlay.yaml`, which partitions every
14//! key in `core_schema.yaml` into exactly one of: supported, unsupported, or ignored. Data
15//! integrity (uniqueness, full coverage, sorted sections) is enforced by `SchemaOverlay::load()`
16//! during the build.
17//!
18//! ### Adding a Configuration Key
19//!
20//! Add a `supported` entry in `lib/datadog-agent/config/schema/schema_overlay.yaml` with
21//! `support_level`, `pipelines`, `used_by`, `description`, and `config_registry_filename`.
22//! The build generates the annotation constants automatically.
23//!
24//! ### Updating the Vendored Schema
25//!
26//! After updating `core_schema.yaml`, the build will fail if any new keys are not covered
27//! by the overlay. For each new key, add it to the appropriate section of
28//! `schema_overlay.yaml`.
29
30#[allow(clippy::module_inception)]
31mod classifier;
32
33pub use classifier::{Classification, ConfigClassifier};
34
35/// Identifiers for known configuration consumers.
36///
37/// Used as values in annotation `used_by` fields to declare which consumers incorporate a key.
38pub mod structs {
39    /// Identifier for `DogStatsDConfiguration`.
40    pub const DOGSTATSD_CONFIGURATION: &str = "DogStatsDConfiguration";
41    /// Identifier for `ContainerdConfiguration`.
42    pub const CONTAINERD_CONFIGURATION: &str = "ContainerdConfiguration";
43    /// Identifier for `AggregateConfiguration`.
44    pub const AGGREGATE_CONFIGURATION: &str = "AggregateConfiguration";
45    /// Identifier for `DogStatsDMapperConfiguration`.
46    pub const DOGSTATSD_MAPPER_CONFIGURATION: &str = "DogStatsDMapperConfiguration";
47    /// Identifier for `DogStatsDDebugLogConfiguration`.
48    pub const DOGSTATSD_DEBUG_LOG_CONFIGURATION: &str = "DogStatsDDebugLogConfiguration";
49    /// Identifier for `DogStatsDPrefixFilterConfiguration`.
50    pub const DOGSTATSD_PREFIX_FILTER_CONFIGURATION: &str = "DogStatsDPrefixFilterConfiguration";
51    /// Identifier for `DatadogLogsConfiguration`.
52    pub const DATADOG_LOGS_CONFIGURATION: &str = "DatadogLogsConfiguration";
53    /// Identifier for `DatadogEventsConfiguration`.
54    pub const DATADOG_EVENTS_CONFIGURATION: &str = "DatadogEventsConfiguration";
55    /// Identifier for `DatadogServiceChecksConfiguration`.
56    pub const DATADOG_SERVICE_CHECKS_CONFIGURATION: &str = "DatadogServiceChecksConfiguration";
57    /// Identifier for `RemoteAgentClientConfiguration`.
58    pub const REMOTE_AGENT_CLIENT_CONFIGURATION: &str = "RemoteAgentClientConfiguration";
59    /// Keys consumed through the typed configuration translation system.
60    pub const TYPED_CONFIG_SYSTEM: &str = "TypedConfigSystem";
61    /// Keys read via `get_typed` / `try_get_typed` rather than struct deserialization.
62    pub const GET_TYPED: &str = "get_typed";
63}
64
65/// The ADP pipeline a config key affects.
66#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
67pub enum Pipeline {
68    /// DogStatsD metrics pipeline.
69    DogStatsD,
70    /// Agent checks pipeline.
71    Checks,
72    /// OTLP ingestion frontend.
73    Otlp,
74    /// Internal trace processing. Active when OTLP is enabled and proxy/relay mode (which uses the
75    /// core Agent for transport) is off.
76    Traces,
77}
78
79/// Which pipelines a config key affects.
80#[derive(Clone, Copy, Debug, PartialEq, Eq)]
81pub enum PipelineAffinity {
82    /// The list of pipelines affected by the key.
83    ///
84    /// This list must be non-empty, enforced by test.
85    Pipelines(&'static [Pipeline]),
86    /// The key affects all pipelines or ADP behavior as a whole.
87    CrossCutting,
88}
89
90/// The `Severity` level of a config key that Saluki doesn't support.
91#[derive(Clone, Copy, Debug, PartialEq, Eq)]
92pub enum Severity {
93    /// Saluki's incompatibility with the key is considered minor.
94    Low,
95
96    /// Saluki's incompatibility with the key is considered potentially impactful.
97    Medium,
98
99    /// Saluki's incompatibility with the key is considered problematic.
100    High,
101}
102
103/// The support level for a given configuration key.
104///
105/// Full support is omitted from the enum and those keys are not classified since there is nothing
106/// to be done about them downstream.
107#[derive(Clone, Copy, Debug, PartialEq, Eq)]
108pub enum SupportLevel {
109    /// Partially supported.
110    Partial,
111    /// Explicitly incompatible.
112    Incompatible(Severity),
113    /// Intentionally ignored.
114    #[allow(unused)]
115    Ignored,
116    /// Unrecognized.
117    #[allow(unused)]
118    Unrecognized,
119}
120
121/// The default value for a config key, as resolved at build time from the Agent schema.
122///
123/// Durations are normalized to nanoseconds during codegen (the build fails if a `format:
124/// duration` default isn't a valid Go duration), so the runtime default check never has to parse a
125/// schema default. Other keys keep their JSON-literal default and are compared structurally.
126#[derive(Clone, Copy, Debug, PartialEq, Eq)]
127pub enum DefaultValue {
128    /// The schema declares no default for this key.
129    Missing,
130    /// A JSON-encoded default value (for example, `"\"tlsv1.2\""` or `"1"`).
131    Json(&'static str),
132    /// A `format: duration` default, already parsed to nanoseconds. The Agent transmits durations
133    /// as integer nanoseconds, so the incoming value is normalized the same way before comparing.
134    DurationNanos(u64),
135}
136
137/// Slim per-key data generated at build time for the classifier.
138///
139/// Carries only what the classifier needs: enough to look up a key, determine its support level,
140/// check whether a value is the default, and report which pipelines are affected.
141pub struct ClassifierEntry {
142    /// Canonical dot-separated YAML path.
143    pub yaml_path: &'static str,
144    /// Additional YAML paths (aliases) that resolve to this key.
145    pub aliases: &'static [&'static str],
146    /// How well saluki supports this key.
147    pub support_level: SupportLevel,
148    /// Which pipelines this key affects.
149    pub pipeline_affinity: PipelineAffinity,
150    /// Default value from the Agent schema (normalized at build time).
151    pub default: DefaultValue,
152}
153
154use crate::generated::classifier_data::CLASSIFIER_ENTRIES;
datadog_agent_config/classifier/mod.rs

datadog_agent_config/classifier/
mod.rs
