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:
Lyndon-Mackay 2024-12-30 11:56:40 +13:00 committed by GitHub
parent c8110f5f86
commit 1614b213f1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -134,7 +134,70 @@ pub(crate) struct FlushGuard(SyncCell<tracing_chrome::FlushGuard>);
/// .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
///
/// This plugin should not be added multiple times in the same process. This plugin