Basic filtering examples for users of the bevy_log. (#16455)
# Objective Give users a quick example on how to control logging so they can filter out library logs while reading their own This is intended to fix issue #15957. ## Solution Added some examples ## Testing I created project and tested the examples work ### This is purely a documentation change. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Andres O. Vela <andresovela@users.noreply.github.com> Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>
This commit is contained in:
parent
c8110f5f86
commit
1614b213f1
@ -134,7 +134,70 @@ pub(crate) struct FlushGuard(SyncCell<tracing_chrome::FlushGuard>);
|
|||||||
/// .run();
|
/// .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.
|
||||||
|
///
|
||||||
|
/// ```no_run
|
||||||
|
/// # use bevy_app::{App, NoopPluginGroup as DefaultPlugins, PluginGroup};
|
||||||
|
/// # use bevy_log::*;
|
||||||
|
/// 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.
|
||||||
|
/// ```no_run
|
||||||
|
/// # use bevy_log::*;
|
||||||
|
/// // 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`.
|
||||||
|
///
|
||||||
|
///
|
||||||
|
/// ```no_run
|
||||||
|
/// # use bevy_app::{App, NoopPluginGroup as DefaultPlugins, PluginGroup};
|
||||||
|
/// # use bevy_log::*;
|
||||||
|
/// 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
|
/// # Panics
|
||||||
///
|
///
|
||||||
/// This plugin should not be added multiple times in the same process. This plugin
|
/// This plugin should not be added multiple times in the same process. This plugin
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user