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
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
//! Structured-diagnostics shims for the `observability` cargo feature.
//!
//! This crate's production diagnostics historically went to stderr via
//! `eprintln!`. With the `observability` feature ON they become structured
//! `tracing` events (fields instead of prose) that flow into whatever
//! subscriber the host installed — the native server already runs a
//! `tracing_subscriber::fmt` layer, so enabling the feature there is enough.
//! With the feature OFF (the default), zero tracing code is compiled into
//! this crate and behavior is byte-identical to before.
//!
//! Gating policy (documented decision):
//!
//! - WARN-level sites report genuine anomalies that operators currently see
//! on the server's stderr in default builds (failed layer slicing, degraded
//! fallbacks). Those messages must NOT silently disappear from default
//! builds, so [`diag_warn!`] keeps the legacy `eprintln!` as the
//! feature-OFF fallback and upgrades to `tracing::warn!` when ON.
//!
//! - DEBUG-level sites are high-volume trace/progress notes that were
//! already compile-time gated (`debug_assertions` or the `debug_geometry`
//! feature) or are pure success chatter. [`diag_debug!`] emits
//! `tracing::debug!` when ON; when OFF it expands to exactly the legacy
//! tokens the call site supplies (which may themselves carry the original
//! `#[cfg(...)]` gate, preserving today's behavior precisely).
//!
//! Both macros take the tracing form first and the legacy statements second,
//! so the feature-OFF expansion reproduces the OLD output byte-for-byte:
//!
//! ```ignore
//! diag_warn!(
//! { element_id = element.id, "material-layers: slicing errored" }
//! else {
//! eprintln!("[material-layers] #{}: sliceable but slicing errored", element.id);
//! }
//! );
//! ```
/// Anomaly-level diagnostic: `tracing::warn!` when the `observability`
/// feature is ON, the supplied legacy statements (normally the original
/// `eprintln!`) when OFF. See the module docs for the gating policy.
/// Trace/progress-level diagnostic: `tracing::debug!` when the
/// `observability` feature is ON, the supplied legacy statements when OFF
/// (pass an empty `else {}` to compile out entirely). See the module docs.
pub use diag_debug;
pub use diag_warn;