netstack3_trace/
lib.rs

1// Copyright 2025 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Tracing abstractions for Netstack3.
6//!
7//! This crate provides a tracing frontend that can be compiled with and without
8//! fuchsia dependencies for netstack3-core. It encodes the common patterns and
9//! trace categories used by netstack3.
10
11#![no_std]
12#![warn(
13    missing_docs,
14    unreachable_patterns,
15    clippy::useless_conversion,
16    clippy::redundant_clone,
17    clippy::precedence
18)]
19
20mod id;
21
22/// The trace category used by netstack3.
23pub const CATEGORY: &'static core::ffi::CStr = c"net";
24
25/// Internal implementation.
26#[cfg(target_os = "fuchsia")]
27pub mod __inner {
28    use super::CATEGORY;
29
30    pub use fuchsia_trace::{ArgValue, AsTraceStrRef, Scope, duration, instant};
31    use fuchsia_trace::{TraceCategoryContext, trace_site_t};
32
33    /// A single trace site cache that is used in the macro expansions.
34    ///
35    /// Given this crate always forces the same category [`crate::CATEGORY`] for
36    /// trace points, we can have a single entry instead of one per call-site.
37    static CACHE: trace_site_t = trace_site_t::new(0);
38
39    /// Checks for [`CACHE`] to see if the trace category is enabled.
40    #[inline]
41    pub fn category_context() -> Option<TraceCategoryContext> {
42        TraceCategoryContext::acquire_cached(CATEGORY, &CACHE)
43    }
44
45    /// Equivalent of [`fuchsia_trace::duration!`].
46    ///
47    /// Always uses [`crate::CATEGORY`].
48    #[macro_export]
49    macro_rules! trace_duration {
50        ($name:expr $(, $key:expr => $val:expr)* $(,)?) => {
51            let mut args;
52            let _scope = {
53                if let Some(context) = $crate::__inner::category_context() {
54                    use $crate::__inner::AsTraceStrRef as _;
55
56                    args = [$($crate::__inner::ArgValue::of_registered(
57                        $key.as_trace_str_ref(&context),
58                        $val,
59                    )),*];
60
61                    Some($crate::__inner::duration($crate::CATEGORY, $name, &args))
62                } else {
63                    None
64                }
65            };
66        }
67    }
68
69    /// Equivalent of [`fuchsia_trace::instant!`].
70    ///
71    /// Always uses [`crate::CATEGORY`].
72    #[macro_export]
73    macro_rules! trace_instant {
74        ($name:expr $(, $key:expr => $val:expr)* $(,)?) => {
75            if let Some(context) = $crate::__inner::category_context() {
76                use $crate::__inner::AsTraceStrRef as _;
77
78                let args = [$($crate::__inner::ArgValue::of_registered(
79                    $key.as_trace_str_ref(&context),
80                    $val,
81                )),*];
82
83                $crate::__inner::instant(
84                    &context,
85                    $name,
86                    $crate::__inner::Scope::Thread,
87                    &args
88                );
89            }
90        }
91    }
92}
93
94/// Internal implementation.
95#[cfg(not(target_os = "fuchsia"))]
96#[allow(missing_docs)]
97pub mod __inner {
98    #[macro_export]
99    macro_rules! trace_duration {
100        ($name:expr $(, $key:expr => $val:expr)* $(,)?) => {
101            $(
102                let _ = $key;
103                let _ = $val;
104            )*
105        }
106    }
107
108    #[macro_export]
109    macro_rules! trace_instant {
110        ($name:expr $(, $key:expr => $val:expr)* $(,)?) => {
111            $(
112                let _ = $key;
113                let _ = $val;
114            )*
115        }
116    }
117}
118
119pub use id::TraceResourceId;
netstack3_trace/lib.rs

netstack3_trace/
lib.rs
