log_layers_ecs/
log_layers_ecs.rs

1//! This example illustrates how to transfer log events from the [`Layer`] to Bevy's ECS.
2//!
3//! The way we will do this is via a [`mpsc`] channel. [`mpsc`] channels allow 2 unrelated
4//! parts of the program to communicate (in this case, [`Layer`]s and Bevy's ECS).
5//!
6//! Inside the `custom_layer` function we will create a [`mpsc::Sender`] and a [`mpsc::Receiver`] from a
7//! [`mpsc::channel`]. The [`Sender`](mpsc::Sender) will go into the `AdvancedLayer` and the [`Receiver`](mpsc::Receiver) will
8//! go into a non-send resource called `LogEvents` (It has to be non-send because [`Receiver`](mpsc::Receiver) is [`!Sync`](Sync)).
9//! From there we will use [`transfer_log_messages`] to transfer log messages from [`CapturedLogMessages`] to an ECS message called [`LogMessage`].
10//!
11//! Finally, after all that we can access the [`LogMessage`] message from our systems and use it.
12//! In this example we build a simple log viewer.
13
14use std::sync::mpsc;
15
16use bevy::{
17    log::{
18        tracing::{self, Subscriber},
19        tracing_subscriber::{self, Layer},
20        BoxedLayer, Level,
21    },
22    prelude::*,
23};
24
25fn main() {
26    App::new()
27        .add_plugins(DefaultPlugins.set(bevy::log::LogPlugin {
28            // Show logs all the way up to the trace level, but only for logs
29            // produced by this example.
30            level: Level::TRACE,
31            filter: "warn,log_layers_ecs=trace".to_string(),
32            custom_layer,
33            ..default()
34        }))
35        .add_systems(Startup, (log_system, setup))
36        .add_systems(Update, print_logs)
37        .run();
38}
39
40/// A basic message. This is what we will be sending from the [`CaptureLayer`] to [`CapturedLogMessages`] non-send resource.
41#[derive(Debug, Message)]
42struct LogMessage {
43    message: String,
44    level: Level,
45}
46
47/// This non-send resource temporarily stores [`LogMessage`]s before they are
48/// written to [`Messages<LogEvent>`] by [`transfer_log_messages`].
49#[derive(Deref, DerefMut)]
50struct CapturedLogMessages(mpsc::Receiver<LogMessage>);
51
52/// Transfers information from the [`CapturedLogMessages`] resource to [`Messages<LogEvent>`](LogMessage).
53fn transfer_log_messages(
54    receiver: NonSend<CapturedLogMessages>,
55    mut message_writer: MessageWriter<LogMessage>,
56) {
57    // Make sure to use `try_iter()` and not `iter()` to prevent blocking.
58    message_writer.write_batch(receiver.try_iter());
59}
60
61/// This is the [`Layer`] that we will use to capture log messages and then send them to Bevy's
62/// ECS via its [`mpsc::Sender`].
63struct CaptureLayer {
64    sender: mpsc::Sender<LogMessage>,
65}
66
67impl<S: Subscriber> Layer<S> for CaptureLayer {
68    fn on_event(
69        &self,
70        event: &tracing::Event<'_>,
71        _ctx: tracing_subscriber::layer::Context<'_, S>,
72    ) {
73        // In order to obtain the log message, we have to create a struct that implements
74        // Visit and holds a reference to our string. Then we use the `record` method and
75        // the struct to modify the reference to hold the message string.
76        let mut message = None;
77        event.record(&mut CaptureLayerVisitor(&mut message));
78        if let Some(message) = message {
79            let metadata = event.metadata();
80
81            self.sender
82                .send(LogMessage {
83                    message,
84                    level: *metadata.level(),
85                })
86                .expect("LogEvents resource no longer exists!");
87        }
88    }
89}
90
91/// A [`Visit`](tracing::field::Visit)or that records log messages that are transferred to [`CaptureLayer`].
92struct CaptureLayerVisitor<'a>(&'a mut Option<String>);
93impl tracing::field::Visit for CaptureLayerVisitor<'_> {
94    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
95        // This if statement filters out unneeded events sometimes show up
96        if field.name() == "message" {
97            *self.0 = Some(format!("{value:?}"));
98        }
99    }
100}
101fn custom_layer(app: &mut App) -> Option<BoxedLayer> {
102    let (sender, receiver) = mpsc::channel();
103
104    let layer = CaptureLayer { sender };
105    let resource = CapturedLogMessages(receiver);
106
107    app.insert_non_send_resource(resource);
108    app.add_message::<LogMessage>();
109    app.add_systems(Update, transfer_log_messages);
110
111    Some(layer.boxed())
112}
113
114fn log_system() {
115    // Here is how you write new logs at each "log level" (in "most important" to
116    // "least important" order)
117    error!("Something failed");
118    warn!("Something bad happened that isn't a failure, but thats worth calling out");
119    info!("Helpful information that is worth printing by default");
120    debug!("Helpful for debugging");
121    trace!("Very noisy");
122}
123
124#[derive(Component)]
125struct LogViewerRoot;
126
127fn setup(mut commands: Commands) {
128    commands.spawn(Camera2d);
129
130    commands.spawn((
131        Node {
132            width: vw(100),
133            height: vh(100),
134            flex_direction: FlexDirection::Column,
135            padding: UiRect::all(px(12)),
136            ..default()
137        },
138        LogViewerRoot,
139    ));
140}
141
142// This is how we can read our LogMessages.
143// In this example we are reading the LogMessages and inserting them as text into our log viewer.
144fn print_logs(
145    mut log_message_reader: MessageReader<LogMessage>,
146    mut commands: Commands,
147    log_viewer_root: Single<Entity, With<LogViewerRoot>>,
148) {
149    let root_entity = *log_viewer_root;
150
151    commands.entity(root_entity).with_children(|child| {
152        for log_message in log_message_reader.read() {
153            child.spawn((
154                Text::default(),
155                children![
156                    (
157                        TextSpan::new(format!("{:5} ", log_message.level)),
158                        TextColor(level_color(&log_message.level)),
159                    ),
160                    TextSpan::new(&log_message.message),
161                ],
162            ));
163        }
164    });
165}
166
167fn level_color(level: &Level) -> Color {
168    use bevy::color::palettes::tailwind::*;
169    Color::from(match *level {
170        Level::WARN => ORANGE_400,
171        Level::ERROR => RED_400,
172        Level::INFO => GREEN_400,
173        Level::TRACE => PURPLE_400,
174        Level::DEBUG => BLUE_400,
175    })
176}
log_layers_ecs/log_layers_ecs.rs

log_layers_ecs/
log_layers_ecs.rs
