agent_data_plane_config/domains/

traces.rs

//! Traces domain: APM trace processing, including environment, sampling, and obfuscation.

use std::collections::HashMap;

use serde::{Deserialize, Serialize, Serializer};

use crate::defaults::{
    DEFAULT_ERROR_SAMPLING_ENABLED, DEFAULT_MAX_RESOURCE_LEN, DEFAULT_RARE_SAMPLER_CARDINALITY,
    DEFAULT_RARE_SAMPLER_COOLDOWN_SECS, DEFAULT_RARE_SAMPLER_TPS,
};

/// A beta APM feature flag.
///
/// The feature inventory is not stable across agent versions: a flag may be promoted to a
/// dedicated setting or dropped. Unrecognized values are carried as `ApmFeature::Other` rather
/// than rejected, so configurations for newer or removed flags load unchanged.
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub enum ApmFeature {
    /// Switches the probabilistic sampler from hashing the low 64 bits of the trace ID to hashing
    /// the full 128-bit ID.
    ProbabilisticSamplerFullTraceId,

    /// An unrecognized feature ID, carried verbatim.
    Other(String),
}

impl ApmFeature {
    /// Returns the feature's configuration ID.
    pub fn as_str(&self) -> &str {
        match self {
            ApmFeature::ProbabilisticSamplerFullTraceId => "probabilistic_sampler_full_trace_id",
            ApmFeature::Other(feature) => feature,
        }
    }
}

impl From<&str> for ApmFeature {
    fn from(feature: &str) -> Self {
        match feature {
            "probabilistic_sampler_full_trace_id" => ApmFeature::ProbabilisticSamplerFullTraceId,
            other => ApmFeature::Other(other.to_owned()),
        }
    }
}

impl Serialize for ApmFeature {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

/// Resolved traces configuration.
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct Domain {
    /// Trace environment configured by `apm_config.env` (`DD_APM_ENV`).
    ///
    /// `None` when no input set the key. An explicit empty value is kept as `Some("")`, which is
    /// distinct from `None`: it still takes precedence over `env` and the `env:` global tags.
    ///
    /// Defaults to `None`. The value is not normalized; the trace pipeline resolves its environment
    /// from this, `env`, and the global tags.
    pub apm_env: Option<String>,

    /// Agent environment configured by the top-level `env` key (`DD_ENV`).
    ///
    /// `None` when no input set the key. An explicit empty value is kept as `Some("")`, which still
    /// takes precedence over the `env:` global tags.
    ///
    /// Defaults to `None`. The value is not normalized; the trace pipeline uses it when `apm_env` is
    /// `None`.
    pub env: Option<String>,

    /// Whether trace stats are computed separately per span kind.
    pub compute_stats_by_span_kind: bool,

    /// Span tags promoted to peer tags for peer-service aggregation.
    pub peer_tags: Vec<String>,

    /// Whether stats are aggregated by peer tags.
    pub peer_tags_aggregation: bool,

    /// Whether error spans are sampled independently of the base sampler. (not in Datadog Agent
    /// config schema)
    pub error_sampling_enabled: bool,

    /// Whether error tracking runs standalone, without full trace ingestion.
    pub error_tracking_standalone_enabled: bool,

    /// Target number of error traces sampled per second.
    pub errors_per_second: f64,

    /// Target number of traces sampled per second.
    pub target_traces_per_second: f64,

    /// Multiplier applied to every learned keep-rate of the adaptive samplers.
    ///
    /// Defaults to 1.0, leaving the computed rates unchanged; values above 1.0 keep
    /// proportionally more. A value of `0` drops every trace decided by a learned rate.
    /// Signatures without a learned rate—new, or freshly cleaned up—fall to the sampler's
    /// default rate, which this multiplier does not scale.
    ///
    /// Operators who want coarser or finer sampling than the adaptive target computes can set
    /// this once instead of re-planning the target: raise it temporarily for incident
    /// investigations, lower it to control ingestion cost. The trade-off is coverage against
    /// volume—every adaptive sampler's output scales together, so the per-service distribution
    /// is preserved while the total scales.
    pub extra_sample_rate: f64,

    /// Event extraction rates by service, for the legacy analytics configuration.
    ///
    /// Empty by default, so no spans are nominated through this map. Rates apply only to
    /// top-level spans of the named service. Superseded by `analyzed_spans_by_service`; the
    /// legacy map is ignored when both are set.
    pub analyzed_rate_by_service: HashMap<String, f64>,

    /// Event extraction rates by service and operation name.
    ///
    /// Empty by default. Configured keys combine service and operation as
    /// `service|operation` with exactly one separator; malformed keys and non-numeric rates
    /// are dropped with a warning at translation. Takes precedence over
    /// `analyzed_rate_by_service` when non-empty.
    pub analyzed_spans_by_service: HashMap<String, HashMap<String, f64>>,

    /// Upper bound on the average number of extracted events sampled per second.
    ///
    /// Defaults to 200. A decaying rate estimate caps survivors at this budget; spans of
    /// manually kept traces bypass the budget entirely. Raise it when customers need more
    /// event volume than the default allows; in normal traffic it should sit high enough that
    /// the cap never engages, since capped events are dropped probabilistically.
    pub max_events_per_second: f64,

    /// Maximum number of service signatures the priority sampler tracks rates for.
    ///
    /// Defaults to 5000. If set to `0`, the default of 5000 applies. Distinct services beyond
    /// the cap evict the least recently used entries and lose their learned rates.
    ///
    /// Deployments with more distinct (service, environment) pairs than the default should
    /// raise this. The trade-off is memory—the catalog holds a map entry and an LRU entry
    /// per tracked signature—against rate fidelity, since evicted services re-learn their
    /// rates from cold.
    pub max_catalog_entries: usize,

    /// Beta APM feature flags enabled for traces.
    ///
    /// Empty by default. Unrecognized values are carried as `ApmFeature::Other` and ignored
    /// without a warning: the flag inventory is not stable across versions. Enable
    /// `ApmFeature::ProbabilisticSamplerFullTraceId` on every probabilistic sampler in the
    /// ingestion path so they keep the same traces.
    pub features: Vec<ApmFeature>,

    /// Whether the rare-span sampler is enabled.
    pub enable_rare_sampler: bool,

    /// Rare-span sampler settings.
    pub rare_sampler: RareSampler,

    /// Probabilistic sampler settings.
    pub probabilistic_sampler: ProbabilisticSampler,

    /// Per-subsystem trace obfuscation settings.
    pub obfuscation: Obfuscation,

    /// OTTL span-drop filter settings.
    pub ottl_filter: OttlFilter,

    /// OTTL span-transform settings.
    pub ottl_transform: OttlTransform,

    /// Maximum length of a span's resource name, in bytes; longer resources are truncated.
    ///
    /// Defaults to 5000 bytes. If set to `0`, all span resources are truncated to empty strings.
    /// Change this only if legitimate resources exceed the default.
    pub max_resource_len: usize,

    /// Regex-based trace tag replacement rules, used to scrub sensitive values the built-in
    /// obfuscation passes through. Defaults to no rules.
    ///
    /// Rules run in order after obfuscation and before stats and sampling. A `"*"` rule rewrites
    /// every non-`_`-prefixed tag, the resource, and span events; `"resource.name"` only the
    /// resource; any other name only that tag. Matched values are stored as strings, and a
    /// pattern that fails to compile prevents startup.
    pub replace_tags: Vec<ReplaceRule>,
}

impl Default for Domain {
    fn default() -> Self {
        Self {
            // Witnessed fields start as placeholders and are overwritten by Datadog `drive`.
            apm_env: None,
            env: None,
            compute_stats_by_span_kind: false,
            peer_tags: Vec::new(),
            peer_tags_aggregation: false,
            error_tracking_standalone_enabled: false,
            errors_per_second: 0.0,
            target_traces_per_second: 0.0,
            extra_sample_rate: 1.0,
            analyzed_rate_by_service: HashMap::new(),
            analyzed_spans_by_service: HashMap::new(),
            max_events_per_second: 0.0,
            max_catalog_entries: 0,
            features: Vec::new(),
            enable_rare_sampler: false,
            probabilistic_sampler: ProbabilisticSampler::default(),
            obfuscation: Obfuscation::default(),
            // Saluki-only fields own their absent-key behavior here.
            max_resource_len: DEFAULT_MAX_RESOURCE_LEN,
            replace_tags: Vec::new(),
            error_sampling_enabled: DEFAULT_ERROR_SAMPLING_ENABLED,
            rare_sampler: RareSampler::default(),
            ottl_filter: OttlFilter::default(),
            ottl_transform: OttlTransform::default(),
        }
    }
}

/// A regex-based trace tag replacement rule.
#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
pub struct ReplaceRule {
    /// Tag key the rule targets: `"*"`, `"resource.name"`, or a literal tag key.
    pub name: String,

    /// Regular expression matched against each targeted value.
    pub pattern: String,

    /// Text spliced in place of each match; `$1`-style group references are supported.
    pub repl: String,
}

/// Rare-span sampler.
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct RareSampler {
    /// Maximum number of distinct span signatures tracked. (not in Datadog Agent config schema)
    pub cardinality: usize,

    /// Cooldown, in seconds, before a signature may be sampled again. (not in Datadog Agent config
    /// schema)
    pub cooldown: f64,

    /// Target rare-span traces sampled per second. (not in Datadog Agent config schema)
    pub tps: f64,
}

impl Default for RareSampler {
    fn default() -> Self {
        Self {
            cardinality: DEFAULT_RARE_SAMPLER_CARDINALITY,
            cooldown: DEFAULT_RARE_SAMPLER_COOLDOWN_SECS,
            tps: DEFAULT_RARE_SAMPLER_TPS,
        }
    }
}

/// APM probabilistic sampler.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct ProbabilisticSampler {
    /// Whether the probabilistic sampler is enabled.
    pub enabled: bool,

    /// Seed mixed into the trace-ID hash before sampling, from 0 to 4,294,967,295.
    ///
    /// Defaults to `0`. Samplers in the same ingestion path keep the same traces only when their
    /// seeds match, so align this with every other probabilistic sampler that sees the traffic.
    /// Values outside the range fail configuration.
    pub hash_seed: u32,

    /// Percentage of traces the probabilistic sampler keeps.
    pub sampling_percentage: f64,
}

/// Trace obfuscation, one group per supported subsystem.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct Obfuscation {
    /// Credit-card obfuscation in span metadata.
    pub credit_cards: CreditCardObfuscation,

    /// Elasticsearch query obfuscation.
    pub elasticsearch: JsonQueryObfuscation,

    /// HTTP path and query obfuscation.
    pub http: HttpObfuscation,

    /// Memcached command obfuscation.
    pub memcached: MemcachedObfuscation,

    /// MongoDB query obfuscation.
    pub mongodb: JsonQueryObfuscation,

    /// OpenSearch query obfuscation.
    pub opensearch: JsonQueryObfuscation,

    /// Redis command obfuscation.
    pub redis: CacheObfuscation,

    /// Valkey command obfuscation.
    pub valkey: CacheObfuscation,

    /// SQL query obfuscation. (not in Datadog Agent config schema)
    pub sql: SqlObfuscation,
}

/// Credit-card obfuscation.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct CreditCardObfuscation {
    /// Whether credit-card numbers are obfuscated.
    pub enabled: bool,

    /// Tag or field names whose values are not obfuscated.
    pub keep_values: Vec<String>,

    /// Whether a Luhn check is applied before a value is treated as a card number.
    pub luhn: bool,
}

/// Obfuscation shape shared by the JSON-query engines (Elasticsearch, MongoDB, OpenSearch).
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct JsonQueryObfuscation {
    /// Whether queries are obfuscated.
    pub enabled: bool,

    /// JSON keys whose values are not obfuscated.
    pub keep_values: Vec<String>,

    /// JSON keys whose values are obfuscated as embedded SQL.
    pub obfuscate_sql_values: Vec<String>,
}

/// HTTP path/query obfuscation.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct HttpObfuscation {
    /// Whether path segments containing digits are removed.
    pub remove_paths_with_digits: bool,

    /// Whether the query string is removed.
    pub remove_query_string: bool,
}

/// Memcached command obfuscation.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct MemcachedObfuscation {
    /// Whether Memcached commands are obfuscated.
    pub enabled: bool,

    /// Whether the command verb is preserved.
    pub keep_command: bool,
}

/// Obfuscation shape shared by the key/value caches (redis, valkey).
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct CacheObfuscation {
    /// Whether cache commands are obfuscated.
    pub enabled: bool,

    /// Whether all command arguments are removed.
    pub remove_all_args: bool,
}

/// SQL obfuscation.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct SqlObfuscation {
    /// SQL dialect the obfuscator parses against.
    pub dbms: String,

    /// Whether dollar-quoted function bodies are preserved.
    pub dollar_quoted_func: bool,

    /// Whether column and table aliases are preserved.
    pub keep_sql_alias: bool,

    /// Whether digits in identifiers are replaced with a placeholder.
    pub replace_digits: bool,

    /// Whether table names are collected as metadata.
    pub table_names: bool,
}

/// Error-handling mode for OTTL condition/statement evaluation, shared by the OTTL filter and
/// transform processors.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
pub enum OttlErrorMode {
    /// Log evaluation errors and continue.
    Ignore,
    /// Swallow evaluation errors silently and continue.
    Silent,
    /// Propagate the error up the pipeline; the payload is dropped.
    #[default]
    Propagate,
}

/// OTTL filter processor: span-drop conditions applied during trace enrichment.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct OttlFilter {
    /// How evaluation errors in the filter conditions are handled. (not in Datadog Agent config
    /// schema)
    pub error_mode: OttlErrorMode,

    /// OTTL conditions; a span matching any of them is dropped. (not in Datadog Agent config
    /// schema)
    pub span_conditions: Vec<String>,
}

/// OTTL transform processor: span-mutating statements applied during trace enrichment.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct OttlTransform {
    /// How evaluation errors in the transform statements are handled. (not in Datadog Agent config
    /// schema)
    pub error_mode: OttlErrorMode,

    /// OTTL statements applied to each span. (not in Datadog Agent config schema)
    pub trace_statements: Vec<String>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn known_feature_ids_map_to_their_variants() {
        assert_eq!(
            ApmFeature::from("probabilistic_sampler_full_trace_id"),
            ApmFeature::ProbabilisticSamplerFullTraceId
        );
        assert_eq!(
            ApmFeature::from("error_rare_sample_tracer_drop"),
            ApmFeature::Other("error_rare_sample_tracer_drop".to_owned())
        );
    }

    #[test]
    fn feature_ids_round_trip_through_as_str() {
        for feature in [
            ApmFeature::ProbabilisticSamplerFullTraceId,
            ApmFeature::Other("table_names".to_owned()),
        ] {
            assert_eq!(ApmFeature::from(feature.as_str()), feature);
        }
    }
}