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
117
118
119
120
121
122
//! Structured logging for Astrelis using the `tracing` crate.
//!
//! This module provides initialization functions for structured logging throughout the engine.
//! All Astrelis crates use `tracing` macros for logging instead of `println!`.
//!
//! # Quick Start
//!
//! Call [`init()`] once at the start of your application:
//!
//! ```no_run
//! use astrelis_core::logging;
//!
//! fn main() {
//! logging::init();
//! tracing::info!("Application started");
//! // ... your code ...
//! }
//! ```
//!
//! # Logging Macros
//!
//! Use these macros throughout your code:
//!
//! ```no_run
//! use tracing::{trace, debug, info, warn, error};
//!
//! trace!("Very detailed information for debugging");
//! debug!("Debugging information");
//! info!("Informational messages");
//! warn!("Warning messages");
//! error!("Error messages");
//!
//! // With structured fields
//! info!(width = 800, height = 600, "Window created");
//! ```
//!
//! # Log Levels
//!
//! By default, [`init()`] filters logs as follows:
//! - **Astrelis crates**: `TRACE` level (all logs)
//! - **External crates** (`wgpu`, `winit`, etc.): `INFO` level (reduces noise)
//!
//! Override with the `RUST_LOG` environment variable:
//!
//! ```bash
//! # Show all debug logs
//! RUST_LOG=debug cargo run
//!
//! # Show only warnings and errors
//! RUST_LOG=warn cargo run
//!
//! # Custom filter for specific modules
//! RUST_LOG=astrelis_ui=trace,wgpu=warn cargo run
//! ```
//!
//! # Best Practices
//!
//! 1. **Use tracing, not println!**: Structured logs can be filtered and formatted
//! 2. **Choose appropriate levels**: Use `trace` for hot paths, `info` for important events
//! 3. **Add structured fields**: `info!(count = 42, "Counter updated")` is better than `info!("Counter: {}", 42)`
//! 4. **Avoid logging in hot loops**: Use `trace!` sparingly in per-frame code
//!
//! # Performance
//!
//! `tracing` is designed for high-performance logging:
//! - **Minimal overhead** when disabled via log levels
//! - **Zero-cost** if logs are compiled out
//! - **Structured data** without string formatting overhead
//!
//! For performance-critical code, use `trace!` and filter it out in release builds:
//!
//! ```bash
//! # Development: all logs
//! cargo run
//!
//! # Release: only info and above
//! RUST_LOG=info cargo run --release
//! ```
/// Initializes the tracing subscriber with default filters.
///
/// This function sets up structured logging for the entire application. It configures:
/// - **Output format**: Human-readable with timestamps
/// - **Log levels**: `TRACE` for Astrelis crates, `INFO` for external dependencies
/// - **Filters**: Reduces noise from WGPU, winit, naga, and cosmic-text
///
/// # Panics
///
/// This function will panic if called more than once. Call it exactly once at the start
/// of your `main()` function.
///
/// # Examples
///
/// ```no_run
/// use astrelis_core::logging;
///
/// fn main() {
/// // Initialize logging once
/// logging::init();
///
/// // Now you can use tracing macros
/// tracing::info!("Application started");
/// }
/// ```
///
/// # Environment Variables
///
/// Override the default log filter with `RUST_LOG`:
///
/// ```bash
/// RUST_LOG=debug cargo run
/// ```
///
/// # See Also
///
/// - [`tracing`](https://docs.rs/tracing) - Structured logging macros
/// - [`tracing-subscriber`](https://docs.rs/tracing-subscriber) - Subscriber implementation