NEOLearn

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.

Updated October 20, 2026

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#

MacroUse 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.
Rust
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.

Rust
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:

src/main.rs
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();
}
FieldWhat it does
levelThe lowest level shown for everything.
filterPer-crate or per-module levels, as target=level pairs separated by commas.
custom_layerAdds your own tracing layer, for example to send logs to a file or to an in-game console.
fmt_layerReplaces 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:

Shell
RUST_LOG=info,neo_ecs=warn,my_game=debug cargo run

Set NO_COLOR to any value to turn off coloured output.

Where the log goes#

PlatformOutput
DesktopThe terminal (standard output). In the Studio, the Console panel.
WebThe browser's developer console. Panics are also logged there.
AndroidAndroid's log (adb logcat).
iOSThe 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.

Rust
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.

Next steps#