Skip to main content

rustfs_storage_api/
observability.rs

1// Copyright 2024 RustFS Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::fmt::Debug;
16
17use serde::{Deserialize, Serialize};
18
19use crate::{CapabilitySnapshotError, CapabilityStatus};
20
21/// Snapshot of observability capabilities and state.
22#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct ObservabilitySnapshot {
25    /// Runtime telemetry capabilities.
26    pub runtime_telemetry: CapabilityStatus,
27    /// Userspace profiling capabilities.
28    pub userspace_profiling: UserspaceProfilingCapability,
29    /// Memory sampling state.
30    pub memory_sampling: MemorySamplingState,
31    /// Platform support information.
32    pub platform: PlatformSupport,
33}
34
35/// Capabilities for userspace profiling.
36#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
37#[serde(deny_unknown_fields)]
38pub struct UserspaceProfilingCapability {
39    /// CPU profiling capability.
40    pub cpu: CapabilityStatus,
41    /// Memory profiling capability.
42    pub memory: CapabilityStatus,
43    /// Continuous CPU profiling capability.
44    pub continuous_cpu: CapabilityStatus,
45    /// Periodic CPU profiling capability.
46    pub periodic_cpu: CapabilityStatus,
47}
48
49/// State of memory sampling capabilities.
50#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
51#[serde(deny_unknown_fields)]
52pub struct MemorySamplingState {
53    /// Process-level memory sampling.
54    pub process: CapabilityStatus,
55    /// System-level memory sampling.
56    pub system: CapabilityStatus,
57    /// Cgroup-level memory sampling.
58    pub cgroup: CapabilityStatus,
59}
60
61/// Platform support information.
62#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
63#[serde(deny_unknown_fields)]
64pub struct PlatformSupport {
65    /// Target triple (e.g., x86_64-unknown-linux-gnu).
66    pub target_triple: Option<String>,
67    /// Operating system.
68    pub os: Option<String>,
69    /// Architecture.
70    pub arch: Option<String>,
71    /// Memory allocator capability.
72    pub allocator: CapabilityStatus,
73    /// eBPF support.
74    pub ebpf: CapabilityStatus,
75    /// NUMA support.
76    pub numa: CapabilityStatus,
77}
78
79/// Provider for observability snapshots.
80#[async_trait::async_trait]
81pub trait ObservabilitySnapshotProvider: Send + Sync + Debug {
82    /// Get a snapshot of observability capabilities and state.
83    async fn observability_snapshot(&self) -> Result<ObservabilitySnapshot, CapabilitySnapshotError>;
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89    use crate::CapabilityState;
90
91    #[test]
92    fn observability_snapshot_preserves_unknown_and_unsupported_states() {
93        let snapshot = ObservabilitySnapshot {
94            runtime_telemetry: CapabilityStatus::unknown(),
95            userspace_profiling: UserspaceProfilingCapability {
96                cpu: CapabilityStatus::unsupported().with_reason("unsupported target"),
97                memory: CapabilityStatus::disabled(),
98                continuous_cpu: CapabilityStatus::unknown(),
99                periodic_cpu: CapabilityStatus::supported(),
100            },
101            memory_sampling: MemorySamplingState {
102                process: CapabilityStatus::supported(),
103                system: CapabilityStatus::supported(),
104                cgroup: CapabilityStatus::unknown(),
105            },
106            platform: PlatformSupport {
107                target_triple: Some("x86_64-unknown-linux-gnu".to_owned()),
108                os: Some("linux".to_owned()),
109                arch: Some("x86_64".to_owned()),
110                allocator: CapabilityStatus::supported(),
111                ebpf: CapabilityStatus::unknown(),
112                numa: CapabilityStatus::unsupported(),
113            },
114        };
115
116        let encoded = serde_json::to_string(&snapshot).expect("serialize observability snapshot");
117        let decoded: ObservabilitySnapshot = serde_json::from_str(&encoded).expect("deserialize observability snapshot");
118
119        assert_eq!(decoded.runtime_telemetry.state, CapabilityState::Unknown);
120        assert_eq!(decoded.userspace_profiling.cpu.state, CapabilityState::Unsupported);
121        assert_eq!(decoded.userspace_profiling.memory.state, CapabilityState::Disabled);
122        assert_eq!(decoded.platform.numa.state, CapabilityState::Unsupported);
123        assert_eq!(decoded.platform.ebpf.state, CapabilityState::Unknown);
124    }
125}