Logging
Write log messages with info!, warn! and the other macros, filter them with LogPlugin or RUST_LOG, log once, and where the log goes on each platform.
On this page
The engine logs through the tracing ecosystem. LogPlugin, part of DefaultPlugins, sets up where messages go; you write them with macros that are in neo::prelude.
Writing messages#
| Macro | Use it for |
|---|---|
error! | Something failed. |
warn! | Something is wrong but the game carries on. |
info! | Things worth seeing by default: a level loaded, a player joined. |
debug! | Detail for debugging. Hidden by default. |
trace! | Very noisy detail. Hidden by default. |
fn report(players: Query<&Name, Added<Player>>) {
for name in &players {
info!("{name} joined");
debug!(player = %name, "spawn details");
}
}They take format!-style arguments, and key = value fields before the message (% for Display, ? for Debug).
Logging once#
A system runs every frame, so a warning in it repeats every frame. The _once variants log a call site only the first time: info_once!, warn_once!, error_once!, debug_once!, trace_once!. once!({ .. }) runs any block once.
fn check(cameras: Query<&Camera>) {
if cameras.is_empty() {
warn_once!("no camera: nothing will be drawn");
}
}Choosing what's shown#
By default, info and above are shown, and a few noisy libraries (such as wgpu) are limited to warnings or errors. Change it with LogPlugin:
use neo::log::{Level, LogPlugin};
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins.set(LogPlugin {
level: Level::DEBUG,
filter: "wgpu=error,neo_render=info,my_game=trace".to_string(),
..default()
}))
.run();
}| Field | What it does |
|---|---|
level | The lowest level shown for everything. |
filter | Per-crate or per-module levels, as target=level pairs separated by commas. |
custom_layer | Adds your own tracing layer, for example to send logs to a file or to an in-game console. |
fmt_layer | Replaces the default formatter, for example to drop timestamps. |
RUST_LOG#
The RUST_LOG environment variable overrides both level and filter, so you can change logging without rebuilding:
RUST_LOG=info,neo_ecs=warn,my_game=debug cargo runSet NO_COLOR to any value to turn off coloured output.
Where the log goes#
| Platform | Output |
|---|---|
| Desktop | The terminal (standard output). In the Studio, the Console panel. |
| Web | The browser's developer console. Panics are also logged there. |
| Android | Android's log (adb logcat). |
| iOS | The system log (os_log). |
Your own layers#
custom_layer lets you capture log events in the app, such as showing errors in a debug panel. The log_layers example adds a layer, and log_layers_ecs sends log events into the ECS as messages.
use neo::log::{BoxedLayer, LogPlugin};
fn my_layer(_app: &mut App) -> Option<BoxedLayer> {
// build any tracing_subscriber layer here
None
}
App::new().add_plugins(DefaultPlugins.set(LogPlugin { custom_layer: my_layer, ..default() }));Examples: cargo run --example logs, log_layers and log_layers_ecs.