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 `AggregateConfiguration`.
40    pub const AGGREGATE_CONFIGURATION: &str = "AggregateConfiguration";
41    /// Identifier for `DogStatsDMapperConfiguration`.
42    pub const DOGSTATSD_MAPPER_CONFIGURATION: &str = "DogStatsDMapperConfiguration";
43    /// Identifier for `DogStatsDDebugLogConfiguration`.
44    pub const DOGSTATSD_DEBUG_LOG_CONFIGURATION: &str = "DogStatsDDebugLogConfiguration";
45    /// Identifier for `DogStatsDPrefixFilterConfiguration`.
46    pub const DOGSTATSD_PREFIX_FILTER_CONFIGURATION: &str = "DogStatsDPrefixFilterConfiguration";
47    /// Identifier for `DatadogLogsConfiguration`.
48    pub const DATADOG_LOGS_CONFIGURATION: &str = "DatadogLogsConfiguration";
49    /// Identifier for `DatadogEventsConfiguration`.
50    pub const DATADOG_EVENTS_CONFIGURATION: &str = "DatadogEventsConfiguration";
51    /// Identifier for `DatadogServiceChecksConfiguration`.
52    pub const DATADOG_SERVICE_CHECKS_CONFIGURATION: &str = "DatadogServiceChecksConfiguration";
53    /// Keys consumed through the typed configuration translation system.
54    pub const TYPED_CONFIG_SYSTEM: &str = "TypedConfigSystem";
55    /// Keys read via `get_typed` / `try_get_typed` rather than struct deserialization.
56    pub const GET_TYPED: &str = "get_typed";
57}
58
59/// The ADP pipeline a config key affects.
60#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
61pub enum Pipeline {
62    /// DogStatsD metrics pipeline.
63    DogStatsD,
64    /// Agent checks pipeline.
65    Checks,
66    /// OTLP ingestion frontend.
67    Otlp,
68    /// Internal trace processing. Active when OTLP is enabled and proxy/relay mode (which uses the
69    /// core Agent for transport) is off.
70    Traces,
71}
72
73/// Which pipelines a config key affects.
74#[derive(Clone, Copy, Debug, PartialEq, Eq)]
75pub enum PipelineAffinity {
76    /// The list of pipelines affected by the key.
77    ///
78    /// This list must be non-empty, enforced by test.
79    Pipelines(&'static [Pipeline]),
80    /// The key affects all pipelines or ADP behavior as a whole.
81    CrossCutting,
82}
83
84/// The `Severity` level of a config key that Saluki doesn't support.
85#[derive(Clone, Copy, Debug, PartialEq, Eq)]
86pub enum Severity {
87    /// Saluki's incompatibility with the key is considered minor.
88    Low,
89
90    /// Saluki's incompatibility with the key is considered potentially impactful.
91    Medium,
92
93    /// Saluki's incompatibility with the key is considered problematic.
94    High,
95}
96
97/// The support level for a given configuration key.
98///
99/// Full support is omitted from the enum and those keys are not classified since there is nothing
100/// to be done about them downstream.
101#[derive(Clone, Copy, Debug, PartialEq, Eq)]
102pub enum SupportLevel {
103    /// Partially supported.
104    Partial,
105    /// Explicitly incompatible.
106    Incompatible(Severity),
107    /// Intentionally ignored.
108    #[allow(unused)]
109    Ignored,
110    /// Unrecognized.
111    #[allow(unused)]
112    Unrecognized,
113}
114
115/// The default value for a config key, as resolved at build time from the Agent schema.
116///
117/// Durations are normalized to nanoseconds during codegen (the build fails if a `format:
118/// duration` default isn't a valid Go duration), so the runtime default check never has to parse a
119/// schema default. Other keys keep their JSON-literal default and are compared structurally.
120#[derive(Clone, Copy, Debug, PartialEq, Eq)]
121pub enum DefaultValue {
122    /// The schema declares no default for this key.
123    Missing,
124    /// A JSON-encoded default value (for example, `"\"tlsv1.2\""` or `"1"`).
125    Json(&'static str),
126    /// A `format: duration` default, already parsed to nanoseconds. The Agent transmits durations
127    /// as integer nanoseconds, so the incoming value is normalized the same way before comparing.
128    DurationNanos(u64),
129}
130
131/// Slim per-key data generated at build time for the classifier.
132///
133/// Carries only what the classifier needs: enough to look up a key, determine its support level,
134/// check whether a value is the default, and report which pipelines are affected.
135pub struct ClassifierEntry {
136    /// Canonical dot-separated YAML path.
137    pub yaml_path: &'static str,
138    /// Additional YAML paths (aliases) that resolve to this key.
139    pub aliases: &'static [&'static str],
140    /// How well saluki supports this key.
141    pub support_level: SupportLevel,
142    /// Which pipelines this key affects.
143    pub pipeline_affinity: PipelineAffinity,
144    /// Default value from the Agent schema (normalized at build time).
145    pub default: DefaultValue,
146}
147
148use crate::generated::classifier_data::CLASSIFIER_ENTRIES;
datadog_agent_config/classifier/mod.rs

datadog_agent_config/classifier/
mod.rs
