near_o11y/
lib.rs

1#![doc = include_str!("../README.md")]
2#![deny(clippy::arithmetic_side_effects)]
3
4pub use context::*;
5pub use env_filter::{BuildEnvFilterError, EnvFilterBuilder};
6pub use opentelemetry::OpenTelemetryLevel;
7pub use reload::{reload, reload_log_config};
8#[cfg(feature = "io_trace")]
9pub use subscriber::make_io_tracing_layer;
10pub use subscriber::{Options, default_subscriber, default_subscriber_with_opentelemetry};
11pub use tracing_opentelemetry::OpenTelemetrySpanExt;
12pub use {tracing, tracing_appender, tracing_subscriber};
13
14/// Custom tracing subscriber implementation that produces IO traces.
15pub mod context;
16pub mod env_filter;
17mod io_tracer;
18pub mod log_config;
19mod log_counter;
20pub mod macros;
21pub mod metrics;
22mod opentelemetry;
23mod reload;
24mod subscriber;
25pub mod testonly;
26
27/// Produce a tracing-event for target "io_tracer" that will be consumed by the
28/// IO-tracer, if the feature has been enabled.
29#[macro_export]
30#[cfg(feature = "io_trace")]
31macro_rules! io_trace {
32    (count: $name:expr) => { tracing::trace!( target: "io_tracer_count", counter = $name) };
33    ($($fields:tt)*) => { tracing::trace!( target: "io_tracer", $($fields)*) };
34}
35
36#[macro_export]
37#[cfg(not(feature = "io_trace"))]
38macro_rules! io_trace {
39    (count: $name:expr) => {};
40    ($($fields:tt)*) => {};
41}
42
43/// Asserts that the condition is true, logging an error otherwise.
44///
45/// This macro complements `assert!` and `debug_assert`. All three macros should
46/// only be used for conditions, whose violation signifies a programming error.
47/// All three macros are no-ops if the condition is true.
48///
49/// The behavior when the condition is false (i.e. when the assert fails) is
50/// different, and informs different usage patterns.
51///
52/// `assert!` panics. Use it for sanity-checking invariants, whose violation can
53/// compromise correctness of the protocol. For example, it's better to shut a
54/// node down via a panic than to admit potentially non-deterministic behavior.
55///
56/// `debug_assert!` panics if `cfg(debug_assertions)` is true, that is, only
57/// during development. In production, `debug_assert!` is compiled away (that
58/// is, the condition is not evaluated at all). Use `debug_assert!` if
59/// evaluating the condition is too slow. In other words, `debug_assert!` is a
60/// performance optimization.
61///
62/// Finally, `log_assert!` panics in debug mode, while in release mode it emits
63/// a `tracing::error!` log line. Use it for sanity-checking non-essential
64/// invariants, whose violation signals a bug in the code, where we'd rather
65/// avoid shutting the whole node down.
66///
67/// For example, `log_assert` is a great choice to use in some auxiliary code
68/// paths -- would be a shame if a bug in, eg, metrics collection code brought
69/// the whole network down.
70///
71/// Another use case is adding new asserts to the old code -- if you are only
72/// 99% sure that the assert is correct, and there's evidence that the old code
73/// is working fine in practice, `log_assert!` is the right choice!
74///
75/// References:
76///   * <https://www.sqlite.org/assert.html>
77#[macro_export]
78macro_rules! log_assert {
79    ($cond:expr) => {
80        $crate::log_assert!($cond, "assertion failed: {}", stringify!($cond))
81    };
82
83    ($cond:expr, $fmt:literal $($arg:tt)*) => {
84        if cfg!(debug_assertions) {
85            assert!($cond, $fmt $($arg)*);
86        } else {
87            if !$cond {
88                $crate::tracing::error!($fmt $($arg)*);
89            }
90        }
91    };
92}
93
94/// The same as 'log_assert' but always fails.
95///
96/// `log_assert_fail!` panics in debug mode, while in release mode it emits
97/// a `tracing::error!` log line. Use it for sanity-checking non-essential
98/// invariants, whose violation signals a bug in the code, where we'd rather
99/// avoid shutting the whole node down.
100#[macro_export]
101macro_rules! log_assert_fail {
102    ($fmt:literal $($arg:tt)*) => {
103        $crate::log_assert!(false, $fmt $($arg)*);
104    };
105}
near_o11y/lib.rs

near_o11y/
lib.rs
