edgefirst-client 2.9.5

EdgeFirst Client Library and CLI
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
115
116

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025 Au-Zone Technologies. All Rights Reserved.

//! Conditional instrumentation support for profiling.
//!
//! This module provides tracing integration when the `profiling` feature is
//! enabled. When disabled, instrumentation compiles to zero-cost no-ops.
//!
//! # Features
//!
//! - `profiling` - Base feature enabling tracing spans (no backend)
//! - `trace-file` - Trace file output in Chrome JSON (.json) or Perfetto
//!   (.pftrace) format
//!
//! # Usage
//!
//! For method-level instrumentation, use the `#[cfg_attr]` pattern:
//!
//! ```rust,ignore
//! #[cfg_attr(feature = "profiling", tracing::instrument(skip(self)))]
//! pub async fn my_method(&self) -> Result<T, Error> {
//!     // ...
//! }
//! ```
//!
//! For manual span creation within functions:
//!
//! ```rust,ignore
//! #[cfg(feature = "profiling")]
//! let _span = tracing::info_span!("operation_name", field = value).entered();
//!
//! // ... code to profile
//!
//! #[cfg(feature = "profiling")]
//! drop(_span);  // Optional: explicitly end span early
//! ```
//!
//! # Trace Output
//!
//! When built with the `trace-file` feature, traces can be written to files:
//! - `.json` extension → Chrome JSON format (viewable in Perfetto UI)
//! - `.pftrace` extension → Native Perfetto format (viewable in Perfetto UI)
//!
//! Use `--trace-file path.json` or `--trace-file path.pftrace` to select
//! format.

#[cfg(feature = "profiling")]
pub use tracing::{
    Instrument, Level, Span, debug, debug_span, error, error_span, info, info_span, instrument,
    trace, trace_span, warn, warn_span,
};

/// Conditional span creation macro - compiles to no-op when profiling is
/// disabled.
///
/// # Example
///
/// ```rust,ignore
/// use edgefirst_client::span;
///
/// fn process_data() {
///     let _span = span!("process_data", items = 100);
///     // ... processing
/// }
/// ```
#[cfg(feature = "profiling")]
#[macro_export]
macro_rules! span {
    ($name:expr) => {
        tracing::info_span!($name)
    };
    ($name:expr, $($field:tt)*) => {
        tracing::info_span!($name, $($field)*)
    };
}

#[cfg(not(feature = "profiling"))]
#[macro_export]
macro_rules! span {
    ($name:expr) => {
        ()
    };
    ($name:expr, $($field:tt)*) => {
        ()
    };
}

/// Conditional event recording macro - compiles to no-op when profiling is
/// disabled.
///
/// Use this for recording events within spans without creating new spans.
///
/// # Example
///
/// ```rust,ignore
/// use edgefirst_client::trace_event;
///
/// fn download_file(url: &str) {
///     trace_event!("starting download", url = %url);
///     // ... download
///     trace_event!("download complete", bytes = 1024);
/// }
/// ```
#[cfg(feature = "profiling")]
#[macro_export]
macro_rules! trace_event {
    ($($arg:tt)*) => {
        tracing::info!($($arg)*)
    };
}

#[cfg(not(feature = "profiling"))]
#[macro_export]
macro_rules! trace_event {
    ($($arg:tt)*) => {};
}