Struct LogPlugin

pub struct LogPlugin {
    pub filter: String,
    pub level: Level,
    pub custom_layer: fn(_: &mut App) -> Option<Box<dyn Layer<Registry> + Send + Sync>>,
}

Adds logging to Apps. This plugin is part of the DefaultPlugins. Adding this plugin will setup a collector appropriate to your target platform:

• Using tracing-subscriber by default, logging to stdout.
• Using android_log-sys on Android, logging to Android logs.
• Using tracing-wasm in Wasm, logging to the browser console.

You can configure this plugin.

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(LogPlugin {
            level: Level::DEBUG,
            filter: "wgpu=error,bevy_render=info,bevy_ecs=trace".to_string(),
            custom_layer: |_| None,
        }))
        .run();
}

Log level can also be changed using the RUST_LOG environment variable. For example, using RUST_LOG=wgpu=error,bevy_render=info,bevy_ecs=trace cargo run ..

It has the same syntax as the field LogPlugin::filter, see EnvFilter. If you define the RUST_LOG environment variable, the LogPlugin settings will be ignored.

Also, to disable color terminal output (ANSI escape codes), you can set the environment variable NO_COLOR to any value. This common convention is documented at no-color.org. For example:

fn main() {
    std::env::set_var("NO_COLOR", "1");
    App::new()
       .add_plugins(DefaultPlugins)
       .run();
}

If you want to setup your own tracing collector, you should disable this plugin from DefaultPlugins:

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.build().disable::<LogPlugin>())
        .run();
}

Example Setup

For a quick setup that enables all first-party logging while not showing any of your dependencies’ log data, you can configure the plugin as shown below.

App::new()
    .add_plugins(DefaultPlugins.set(LogPlugin {
        filter: "warn,my_crate=trace".to_string(), //specific filters
        level: Level::TRACE,//Change this to be globally change levels
        ..Default::default()
        }))
    .run();

The filter (in this case an EnvFilter) chooses whether to print the log. The most specific filters apply with higher priority. Let’s start with an example: filter: "warn".to_string() will only print logs with level warn level or greater. From here, we can change to filter: "warn,my_crate=trace".to_string(). Logs will print at level warn unless it’s in mycrate, which will instead print at trace level because my_crate=trace is more specific.

Log levels

Events can be logged at various levels of importance. Only events at your configured log level and higher will be shown.

// here is how you write new logs at each "log level" (in "most important" to
// "least important" order)
error!("something failed");
warn!("something bad happened that isn't a failure, but that's worth calling out");
info!("helpful information that is worth printing by default");
debug!("helpful for debugging");
trace!("very noisy");

In addition to format! style arguments, you can print a variable’s debug value by using syntax like: trace(?my_value).

Per module logging levels

Modules can have different logging levels using syntax like crate_name::module_name=debug.

App::new()
    .add_plugins(DefaultPlugins.set(LogPlugin {
        filter: "warn,my_crate=trace,my_crate::my_module=debug".to_string(), // Specific filters
        level: Level::TRACE, // Change this to be globally change levels
        ..Default::default()
    }))
    .run();

The idea is that instead of deleting logs when they are no longer immediately applicable, you just disable them. If you do need to log in the future, then you can enable the logs instead of having to rewrite them.

Further reading

The tracing crate has much more functionality than these examples can show. Much of this configuration can be done with “layers” in the log crate. Check out:

• Using spans to add more fine grained filters to logs
• Adding instruments to capture more function information
• Creating layers to add additional context such as line numbers

Panics

This plugin should not be added multiple times in the same process. This plugin sets up global logging configuration for all Apps in a given process, and rerunning the same initialization multiple times will lead to a panic.

Performance

Filters applied through this plugin are computed at runtime, which will have a non-zero impact on performance. To achieve maximum performance, consider using compile time filters provided by the log crate.

# cargo.toml
[dependencies]
log = { version = "0.4", features = ["max_level_debug", "release_max_level_warn"] }

Fields

filter: String

Filters logs using the EnvFilter format

level: Level

Filters out logs that are “less than” the given level. This can be further filtered using the filter setting.

custom_layer: fn(_: &mut App) -> Option<Box<dyn Layer<Registry> + Send + Sync>>

Optionally add an extra Layer to the tracing subscriber

This function is only called once, when the plugin is built.

Because BoxedLayer takes a dyn Layer, Vec<Layer> is also an acceptable return value.

Access to App is also provided to allow for communication between the Subscriber and the App.

Please see the examples/log_layers.rs for a complete example.

Trait Implementations

impl Default for LogPlugin

fn default() -> LogPlugin

Returns the “default value” for a type.

impl Plugin for LogPlugin

fn build(&self, app: &mut App)

Configures the App to which this plugin is added.

fn ready(&self, _app: &App) -> bool

Has the plugin finished its setup? This can be useful for plugins that need something asynchronous to happen before they can finish their setup, like the initialization of a renderer. Once the plugin is ready, finish should be called.

fn finish(&self, _app: &mut App)

Finish adding this plugin to the App, once all plugins registered are ready. This can be useful for plugins that depends on another plugin asynchronous setup, like the renderer.

fn cleanup(&self, _app: &mut App)

Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.

fn name(&self) -> &str

Configures a name for the Plugin which is primarily used for checking plugin uniqueness and debugging.

fn is_unique(&self) -> bool

If the plugin can be meaningfully instantiated several times in an App, override this method to return false.