foundations 5.8.0

A Rust service foundations library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

use std::num::NonZeroUsize;

#[cfg(feature = "settings")]
use crate::settings::settings;

/// Distributed user tracing settings.
#[cfg_attr(feature = "settings", settings(crate_path = "crate"))]
#[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))]
pub struct UserTracingSettings {
    /// Enables user tracing.
    #[serde(default = "UserTracingSettings::default_enabled")]
    pub enabled: bool,

    /// Maximum number of spans to buffer for output. Any spans above
    /// this limit will be dropped until the queue regains capacity.
    ///
    /// The default is to buffer up to 1 million spans in memory. This protects
    /// services from out-of-memory errors when the output gets heavily backed up.
    /// To disable the limit entirely, set this setting to `None`.
    #[serde(default = "UserTracingSettings::default_max_queue_size")]
    pub max_queue_size: Option<NonZeroUsize>,

    /// The output for the collected user traces.
    pub output: UserTracesOutput,
}

#[cfg(not(feature = "settings"))]
impl Default for UserTracingSettings {
    fn default() -> Self {
        Self {
            enabled: UserTracingSettings::default_enabled(),
            max_queue_size: UserTracingSettings::default_max_queue_size(),
            output: Default::default(),
        }
    }
}

impl UserTracingSettings {
    fn default_enabled() -> bool {
        false
    }

    const fn default_max_queue_size() -> Option<NonZeroUsize> {
        Some(const { NonZeroUsize::new(1_000_000).expect("1_000_000 is not zero") })
    }
}

/// The output for the collected user traces.
#[cfg_attr(
    feature = "settings",
    settings(crate_path = "crate", impl_default = false)
)]
#[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))]
pub enum UserTracesOutput {
    /// Send user tracing spans as OTLP over a Unix domain socket to an OTLP endpoint.
    OtlpUds(OtlpUdsOutputSettings),
}

impl Default for UserTracesOutput {
    fn default() -> Self {
        Self::OtlpUds(Default::default())
    }
}

/// [OTLP over UDS] output settings for user tracing.
///
/// Sends trace data as protobuf-encoded OTLP over HTTP to a Unix domain socket.
#[cfg_attr(feature = "settings", settings(crate_path = "crate"))]
#[cfg_attr(not(feature = "settings"), derive(Clone, Debug, serde::Deserialize))]
pub struct OtlpUdsOutputSettings {
    /// Path to the Unix domain socket for the OTLP endpoint.
    pub socket_path: String,

    /// Name of the header carrying each span's encoded routing.
    pub routing_header_name: String,

    /// Number of concurrent worker tasks for user trace export.
    ///
    /// # Default
    ///
    /// Default value is `1`.
    #[serde(default = "OtlpUdsOutputSettings::default_num_tasks")]
    pub num_tasks: usize,

    /// Maximum number of spans to drain per batch.
    ///
    /// # Default
    ///
    /// Default value is `512`.
    #[serde(default = "OtlpUdsOutputSettings::default_max_batch_size")]
    pub max_batch_size: usize,
}

#[cfg(not(feature = "settings"))]
impl Default for OtlpUdsOutputSettings {
    fn default() -> Self {
        Self {
            socket_path: String::new(),
            routing_header_name: String::new(),
            num_tasks: OtlpUdsOutputSettings::default_num_tasks(),
            max_batch_size: OtlpUdsOutputSettings::default_max_batch_size(),
        }
    }
}

impl OtlpUdsOutputSettings {
    const fn default_num_tasks() -> usize {
        1
    }

    const fn default_max_batch_size() -> usize {
        512
    }
}