tracing_subscriber_init/
lib.rs

1// Copyright (c) 2023 tracing-subscriber-init developers
2//
3// Licensed under the Apache License, Version 2.0
4// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0> or the MIT
5// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. All files in the project carrying such notice may not be copied,
7// modified, or distributed except according to those terms.
8
9//! Convenience trait and functions to ease [`tracing-subscriber`][tracing-subscriber] initialization.
10//!
11//! Program configuration can come from multiple sources. This crate supplies the [`TracingConfig`] trait to allow the grouping
12//! of [`tracing-subscriber`][tracing-subscriber] initialization related items.
13//!
14//! For example, I often have some configuration from the command line (quiet and verbose flags),
15//! some configuration from a configuration file, and some configuration (secrets) loaded from external sources.  I implement this
16//! trait on a struct to collect the [`tracing-subscriber`][tracing-subscriber] related configuration, then use functions such as
17//! [`full_filtered`](crate::full_filtered) to configure layers as appropriate.
18//!
19//! There are also convenience functions such as [`set_default`](crate::set_default) that will
20//! setup a [`Registry`](tracing_subscriber::registry::Registry), add the given vector of [`Layer`](tracing_subscriber::Layer),
21//! and initialize per the upstream functions of the
22//! [same name](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/util/trait.SubscriberInitExt.html#method.set_default).
23//!
24//! [tracing-subscriber]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/
25//! # Example
26//! ```rust
27//! # use anyhow::Result;
28//! # use std::fs::File;
29//! # use tracing::{info, Level, span};
30//! # use tracing_subscriber::{Layer, fmt::format::FmtSpan};
31//! # use tracing_subscriber_init::{TracingConfig, full, full_filtered, set_default};
32//! #
33//! # pub fn main() -> Result<()> {
34//! #[derive(Clone, Debug, Default)]
35//! struct TomlConfig {
36//!     // ...other configuration
37//!     tracing: Tracing,
38//!     tracing_file: TracingFile,
39//!     // ...other configuration
40//! }
41//!
42//! #[derive(Clone, Debug, Default)]
43//! struct Tracing {
44//!     target: bool,
45//!     thread_ids: bool,
46//!     thread_names: bool,
47//!     line_numbers: bool,
48//! }
49//!
50//! impl TracingConfig for Tracing {
51//!     // Normally pulled from command line arguments, i.e. prog -qq
52//!     fn quiet(&self) -> u8 {
53//!         0
54//!     }
55//!
56//!     // Normally pulled from command line arguments, i.e. prog -vv
57//!     fn verbose(&self) -> u8 {
58//!         2
59//!     }
60//!
61//!     fn with_line_number(&self) -> bool {
62//!         self.line_numbers
63//!     }
64//!
65//!     fn with_target(&self) -> bool {
66//!         self.target
67//!     }
68//!
69//!     fn with_thread_ids(&self) -> bool {
70//!         self.thread_ids
71//!     }
72//!
73//!     fn with_thread_names(&self) -> bool {
74//!         self.thread_names
75//!     }
76//! }
77//!
78//! #[derive(Clone, Debug, Default)]
79//! struct TracingFile;
80//!
81//! impl TracingConfig for TracingFile {
82//!     fn quiet(&self) -> u8 {
83//!         0
84//!     }
85//!
86//!     fn verbose(&self) -> u8 {
87//!         3
88//!     }
89//!
90//!     fn with_ansi(&self) -> bool {
91//!         false
92//!     }
93//! }
94//!
95//! // Load configuration and pull out the tracing specific.
96//! let toml_config = TomlConfig::default();
97//! let tracing_config = toml_config.tracing;
98//! let tracing_file_config = toml_config.tracing_file;
99//!
100//! // Setup a full format, filtered layer.  The filtering is set based on the quiet
101//! // and verbose values from the configuration
102//! let layer = full_filtered(&tracing_config);
103//!
104//! // Setup a second full format layer to write to a file.  Use the non-filtered
105//! // version when you wish to modify items such as the writer, or the time format.
106//! // You can also chose to ignore the generated level filter and apply your own.
107//! let file = File::create("trace.log")?;
108//! let (file_layer, level_filter) = full(&tracing_file_config);
109//! let file_layer = file_layer.with_writer(file).with_filter(level_filter);
110//!
111//! // Create a Registry, add the layers, and set this subscriber as the default
112//! // for this scope
113//! let _unused = set_default(vec![layer.boxed(), file_layer.boxed()]);
114//!
115//! // Create a new span and enter it.
116//! let span = span!(Level::INFO, "a new span");
117//! let _enter = span.enter();
118//!
119//! // Trace away...
120//! info!("info level");
121//! #    Ok(())
122//! # }
123//! ```
124
125// rustc lints
126#![cfg_attr(
127    all(feature = "unstable", nightly),
128    feature(
129        multiple_supertrait_upcastable,
130        must_not_suspend,
131        non_exhaustive_omitted_patterns_lint,
132        rustdoc_missing_doc_code_examples,
133        strict_provenance_lints,
134        supertrait_item_shadowing,
135        unqualified_local_imports,
136    )
137)]
138#![cfg_attr(
139    nightly,
140    deny(
141        aarch64_softfloat_neon,
142        absolute_paths_not_starting_with_crate,
143        ambiguous_glob_reexports,
144        ambiguous_negative_literals,
145        ambiguous_wide_pointer_comparisons,
146        anonymous_parameters,
147        array_into_iter,
148        asm_sub_register,
149        async_fn_in_trait,
150        bad_asm_style,
151        bare_trait_objects,
152        boxed_slice_into_iter,
153        break_with_label_and_loop,
154        clashing_extern_declarations,
155        closure_returning_async_block,
156        coherence_leak_check,
157        confusable_idents,
158        const_evaluatable_unchecked,
159        const_item_mutation,
160        dangling_pointers_from_locals,
161        dangling_pointers_from_temporaries,
162        dead_code,
163        dependency_on_unit_never_type_fallback,
164        deprecated,
165        deprecated_in_future,
166        deprecated_safe_2024,
167        deprecated_where_clause_location,
168        deref_into_dyn_supertrait,
169        deref_nullptr,
170        double_negations,
171        drop_bounds,
172        dropping_copy_types,
173        dropping_references,
174        duplicate_macro_attributes,
175        dyn_drop,
176        edition_2024_expr_fragment_specifier,
177        elided_lifetimes_in_paths,
178        ellipsis_inclusive_range_patterns,
179        explicit_outlives_requirements,
180        exported_private_dependencies,
181        ffi_unwind_calls,
182        forbidden_lint_groups,
183        forgetting_copy_types,
184        forgetting_references,
185        for_loops_over_fallibles,
186        function_item_references,
187        hidden_glob_reexports,
188        if_let_rescope,
189        impl_trait_overcaptures,
190        impl_trait_redundant_captures,
191        improper_ctypes,
192        improper_ctypes_definitions,
193        inline_no_sanitize,
194        internal_features,
195        invalid_from_utf8,
196        invalid_macro_export_arguments,
197        invalid_nan_comparisons,
198        invalid_value,
199        irrefutable_let_patterns,
200        keyword_idents_2018,
201        keyword_idents_2024,
202        large_assignments,
203        late_bound_lifetime_arguments,
204        let_underscore_drop,
205        macro_use_extern_crate,
206        malformed_diagnostic_attributes,
207        malformed_diagnostic_format_literals,
208        map_unit_fn,
209        meta_variable_misuse,
210        mismatched_lifetime_syntaxes,
211        misplaced_diagnostic_attributes,
212        missing_abi,
213        missing_copy_implementations,
214        missing_debug_implementations,
215        missing_docs,
216        missing_unsafe_on_extern,
217        mixed_script_confusables,
218        named_arguments_used_positionally,
219        never_type_fallback_flowing_into_unsafe,
220        no_mangle_generic_items,
221        non_ascii_idents,
222        non_camel_case_types,
223        non_contiguous_range_endpoints,
224        non_fmt_panics,
225        non_local_definitions,
226        non_shorthand_field_patterns,
227        non_snake_case,
228        non_upper_case_globals,
229        noop_method_call,
230        opaque_hidden_inferred_bound,
231        overlapping_range_endpoints,
232        path_statements,
233        private_bounds,
234        private_interfaces,
235        ptr_to_integer_transmute_in_consts,
236        redundant_imports,
237        redundant_lifetimes,
238        redundant_semicolons,
239        refining_impl_trait_internal,
240        refining_impl_trait_reachable,
241        renamed_and_removed_lints,
242        repr_transparent_external_private_fields,
243        rust_2021_incompatible_closure_captures,
244        rust_2021_incompatible_or_patterns,
245        rust_2021_prefixes_incompatible_syntax,
246        rust_2021_prelude_collisions,
247        rust_2024_guarded_string_incompatible_syntax,
248        rust_2024_incompatible_pat,
249        rust_2024_prelude_collisions,
250        self_constructor_from_outer_item,
251        single_use_lifetimes,
252        special_module_name,
253        stable_features,
254        static_mut_refs,
255        suspicious_double_ref_op,
256        tail_expr_drop_order,
257        trivial_bounds,
258        trivial_casts,
259        trivial_numeric_casts,
260        type_alias_bounds,
261        tyvar_behind_raw_pointer,
262        uncommon_codepoints,
263        unconditional_recursion,
264        uncovered_param_in_projection,
265        unexpected_cfgs,
266        unfulfilled_lint_expectations,
267        ungated_async_fn_track_caller,
268        uninhabited_static,
269        unit_bindings,
270        unknown_diagnostic_attributes,
271        unknown_lints,
272        unnameable_test_items,
273        unnameable_types,
274        unnecessary_transmutes,
275        unpredictable_function_pointer_comparisons,
276        unreachable_code,
277        unreachable_patterns,
278        unreachable_pub,
279        unsafe_attr_outside_unsafe,
280        unsafe_code,
281        unsafe_op_in_unsafe_fn,
282        unstable_name_collisions,
283        unstable_syntax_pre_expansion,
284        unsupported_calling_conventions,
285        unused_allocation,
286        unused_assignments,
287        unused_associated_type_bounds,
288        unused_attributes,
289        unused_braces,
290        unused_comparisons,
291        unused_crate_dependencies,
292        unused_doc_comments,
293        unused_extern_crates,
294        unused_features,
295        unused_import_braces,
296        unused_imports,
297        unused_labels,
298        unused_lifetimes,
299        unused_macro_rules,
300        unused_macros,
301        unused_must_use,
302        unused_mut,
303        unused_parens,
304        unused_qualifications,
305        unused_results,
306        unused_unsafe,
307        unused_variables,
308        useless_ptr_null_checks,
309        uses_power_alignment,
310        variant_size_differences,
311        while_true,
312    )
313)]
314// If nightly and unstable, allow `incomplete_features` and `unstable_features`
315#![cfg_attr(
316    all(feature = "unstable", nightly),
317    allow(incomplete_features, unstable_features)
318)]
319// If nightly and not unstable, deny `incomplete_features` and `unstable_features`
320#![cfg_attr(
321    all(not(feature = "unstable"), nightly),
322    deny(incomplete_features, unstable_features)
323)]
324// The unstable lints
325#![cfg_attr(
326    all(feature = "unstable", nightly),
327    deny(
328        fuzzy_provenance_casts,
329        lossy_provenance_casts,
330        multiple_supertrait_upcastable,
331        must_not_suspend,
332        non_exhaustive_omitted_patterns,
333        supertrait_item_shadowing_definition,
334        supertrait_item_shadowing_usage,
335        unqualified_local_imports,
336    )
337)]
338// clippy lints
339#![cfg_attr(nightly, deny(clippy::all, clippy::pedantic))]
340// rustdoc lints
341#![cfg_attr(
342    nightly,
343    deny(
344        rustdoc::bare_urls,
345        rustdoc::broken_intra_doc_links,
346        rustdoc::invalid_codeblock_attributes,
347        rustdoc::invalid_html_tags,
348        rustdoc::missing_crate_level_docs,
349        rustdoc::private_doc_tests,
350        rustdoc::private_intra_doc_links,
351    )
352)]
353#![cfg_attr(
354    all(feature = "unstable", nightly),
355    deny(rustdoc::missing_doc_code_examples)
356)]
357#![cfg_attr(all(doc, nightly), feature(doc_auto_cfg))]
358#![cfg_attr(all(docsrs, nightly), feature(doc_cfg))]
359
360mod config;
361mod format;
362mod initialize;
363mod utils;
364
365pub use self::config::Config as TracingConfig;
366pub use self::format::compact::compact;
367pub use self::format::compact::filtered as compact_filtered;
368pub use self::format::full::filtered as full_filtered;
369pub use self::format::full::full;
370#[cfg(feature = "json")]
371pub use self::format::json::filtered as json_filtered;
372#[cfg(feature = "json")]
373pub use self::format::json::json;
374pub use self::format::pretty::filtered as pretty_filtered;
375pub use self::format::pretty::pretty;
376pub use self::initialize::init;
377pub use self::initialize::set_default;
378pub use self::initialize::try_init;
379pub use self::utils::TestAll;
380
381#[cfg(feature = "time")]
382#[doc(no_inline)]
383pub use time::format_description::well_known::Iso8601;
384#[cfg(feature = "time")]
385#[doc(no_inline)]
386pub use time::format_description::well_known::Rfc2822;
387#[cfg(feature = "time")]
388#[doc(no_inline)]
389pub use time::format_description::well_known::Rfc3339;
390#[cfg(feature = "tstime")]
391#[doc(no_inline)]
392pub use tracing_subscriber::Layer;
393#[cfg(feature = "tstime")]
394#[doc(no_inline)]
395pub use tracing_subscriber::fmt::time::OffsetTime;
396#[cfg(feature = "tstime")]
397#[doc(no_inline)]
398pub use tracing_subscriber::fmt::time::SystemTime;
399#[cfg(feature = "tstime")]
400#[doc(no_inline)]
401pub use tracing_subscriber::fmt::time::Uptime;
402#[cfg(feature = "tstime")]
403#[doc(no_inline)]
404pub use tracing_subscriber::fmt::time::UtcTime;
tracing_subscriber_init/lib.rs

tracing_subscriber_init/
lib.rs
