add documentation on LogPlugin and more log usage (#1973)

Fixes #1895 

Changed most `println` to `info` in examples, some to `warn` when it was useful to differentiate from other more noisy logs.

Added doc on `LogPlugin`, how to configure it, and why (and how) you may need to disable it

Author: mockersf

crates/bevy_internal/src/default_plugins.rs

@@ -1,55 +1,107 @@
 use bevy_app::{PluginGroup, PluginGroupBuilder};
 
+use bevy_app::ScheduleRunnerPlugin;
+use bevy_asset::AssetPlugin;
+#[cfg(feature = "bevy_audio")]
+use bevy_audio::AudioPlugin;
+use bevy_core::CorePlugin;
+use bevy_diagnostic::DiagnosticsPlugin;
+#[cfg(feature = "bevy_gilrs")]
+use bevy_gilrs::GilrsPlugin;
+#[cfg(feature = "bevy_gltf")]
+use bevy_gltf::GltfPlugin;
+use bevy_input::InputPlugin;
+use bevy_log::LogPlugin;
+#[cfg(feature = "bevy_pbr")]
+use bevy_pbr::PbrPlugin;
+#[cfg(feature = "bevy_render")]
+use bevy_render::RenderPlugin;
+use bevy_scene::ScenePlugin;
+#[cfg(feature = "bevy_sprite")]
+use bevy_sprite::SpritePlugin;
+#[cfg(feature = "bevy_text")]
+use bevy_text::TextPlugin;
+use bevy_transform::TransformPlugin;
+#[cfg(feature = "bevy_ui")]
+use bevy_ui::UiPlugin;
+#[cfg(feature = "bevy_wgpu")]
+use bevy_wgpu::WgpuPlugin;
+use bevy_window::WindowPlugin;
+#[cfg(feature = "bevy_winit")]
+use bevy_winit::WinitPlugin;
+
+/// This plugin group will add all the default plugins:
+/// * [`LogPlugin`]
+/// * [`CorePlugin`]
+/// * [`TransformPlugin`]
+/// * [`DiagnosticsPlugin`]
+/// * [`InputPlugin`]
+/// * [`WindowPlugin`]
+/// * [`AssetPlugin`]
+/// * [`ScenePlugin`]
+/// * [`RenderPlugin`] - with feature `bevy_render`
+/// * [`SpritePlugin`] - with feature `bevy_sprite`
+/// * [`PbrPlugin`] - with feature `bevy_pbr`
+/// * [`UiPlugin`] - with feature `bevy_ui`
+/// * [`TextPlugin`] - with feature `bevy_text`
+/// * [`AudioPlugin`] - with feature `bevy_audio`
+/// * [`GilrsPlugin`] - with feature `bevy_gilrs`
+/// * [`GltfPlugin`] - with feature `bevy_gltf`
+/// * [`WinitPlugin`] - with feature `bevy_winit`
+/// * [`WgpuPlugin`] - with feature `bevy_wgpu`
 pub struct DefaultPlugins;
 
 impl PluginGroup for DefaultPlugins {
     fn build(&mut self, group: &mut PluginGroupBuilder) {
-        group.add(bevy_log::LogPlugin::default());
-        group.add(bevy_core::CorePlugin::default());
-        group.add(bevy_transform::TransformPlugin::default());
-        group.add(bevy_diagnostic::DiagnosticsPlugin::default());
-        group.add(bevy_input::InputPlugin::default());
-        group.add(bevy_window::WindowPlugin::default());
-        group.add(bevy_asset::AssetPlugin::default());
-        group.add(bevy_scene::ScenePlugin::default());
+        group.add(LogPlugin::default());
+        group.add(CorePlugin::default());
+        group.add(TransformPlugin::default());
+        group.add(DiagnosticsPlugin::default());
+        group.add(InputPlugin::default());
+        group.add(WindowPlugin::default());
+        group.add(AssetPlugin::default());
+        group.add(ScenePlugin::default());
 
         #[cfg(feature = "bevy_render")]
-        group.add(bevy_render::RenderPlugin::default());
+        group.add(RenderPlugin::default());
 
         #[cfg(feature = "bevy_sprite")]
-        group.add(bevy_sprite::SpritePlugin::default());
+        group.add(SpritePlugin::default());
 
         #[cfg(feature = "bevy_pbr")]
-        group.add(bevy_pbr::PbrPlugin::default());
+        group.add(PbrPlugin::default());
 
         #[cfg(feature = "bevy_ui")]
-        group.add(bevy_ui::UiPlugin::default());
+        group.add(UiPlugin::default());
 
         #[cfg(feature = "bevy_text")]
-        group.add(bevy_text::TextPlugin::default());
+        group.add(TextPlugin::default());
 
         #[cfg(feature = "bevy_audio")]
-        group.add(bevy_audio::AudioPlugin::default());
+        group.add(AudioPlugin::default());
 
         #[cfg(feature = "bevy_gilrs")]
-        group.add(bevy_gilrs::GilrsPlugin::default());
+        group.add(GilrsPlugin::default());
 
         #[cfg(feature = "bevy_gltf")]
-        group.add(bevy_gltf::GltfPlugin::default());
+        group.add(GltfPlugin::default());
 
         #[cfg(feature = "bevy_winit")]
-        group.add(bevy_winit::WinitPlugin::default());
+        group.add(WinitPlugin::default());
 
         #[cfg(feature = "bevy_wgpu")]
-        group.add(bevy_wgpu::WgpuPlugin::default());
+        group.add(WgpuPlugin::default());
     }
 }
 
+/// Minimal plugin group that will add the following plugins:
+/// * [`CorePlugin`]
+/// * [`ScheduleRunnerPlugin`]
 pub struct MinimalPlugins;
 
 impl PluginGroup for MinimalPlugins {
     fn build(&mut self, group: &mut PluginGroupBuilder) {
-        group.add(bevy_core::CorePlugin::default());
-        group.add(bevy_app::ScheduleRunnerPlugin::default());
+        group.add(CorePlugin::default());
+        group.add(ScheduleRunnerPlugin::default());
     }
 }

crates/bevy_log/Cargo.toml

@@ -26,3 +26,6 @@ android_log-sys = "0.2.0"
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 console_error_panic_hook = "0.1.6"
 tracing-wasm = "0.2"
+
+[dev-dependencies]
+bevy_internal = { path = "../bevy_internal", version = "0.5.0" }

crates/bevy_log/src/lib.rs

@@ -16,13 +16,53 @@ use bevy_app::{AppBuilder, Plugin};
 use tracing_subscriber::fmt::{format::DefaultFields, FormattedFields};
 use tracing_subscriber::{prelude::*, registry::Registry, EnvFilter};
 
-/// Adds logging to Apps.
+/// 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`](https://crates.io/crates/tracing-subscriber) by default,
+/// logging to `stdout`.
+/// * Using [`android_log-sys`](https://crates.io/crates/android_log-sys) on Android,
+/// logging to Android logs.
+/// * Using [`tracing-wasm`](https://crates.io/crates/tracing-wasm) in WASM, logging
+/// to the browser console.
+///
+/// You can configure this plugin using the resource [`LogSettings`].
+/// ```no_run
+/// # use bevy_internal::DefaultPlugins;
+/// # use bevy_app::App;
+/// # use bevy_log::LogSettings;
+/// # use bevy_utils::tracing::Level;
+/// fn main() {
+///     App::build()
+///         .insert_resource(LogSettings {
+///             level: Level::DEBUG,
+///             filter: "wgpu=error,bevy_render=info".to_string(),
+///         })
+///         .add_plugins(DefaultPlugins)
+///         .run();
+/// }
+/// ```
+///
+/// Log level can also be changed using the `RUST_LOG` environment variable.
+/// It has the same syntax has the field [`LogSettings::filter`], see [`EnvFilter`].
+///
+/// If you want to setup your own tracing collector, you should disable this
+/// plugin from `DefaultPlugins` with [`AppBuilder::add_plugins_with`]:
+/// ```no_run
+/// # use bevy_internal::DefaultPlugins;
+/// # use bevy_app::App;
+/// # use bevy_log::LogPlugin;
+/// fn main() {
+///     App::build()
+///         .add_plugins_with(DefaultPlugins, |group| group.disable::<LogPlugin>())
+///         .run();
+/// }
+/// ```
 #[derive(Default)]
 pub struct LogPlugin;
 
 /// LogPlugin settings
 pub struct LogSettings {
-    /// Filters logs using the [EnvFilter] format
+    /// Filters logs using the [`EnvFilter`] format
     pub filter: String,
 
     /// Filters out logs that are "less than" the given level.

examples/2d/many_sprites.rs

@@ -90,7 +90,7 @@ fn tick(time: Res<Time>, sprites: Query<&Sprite>, mut query: Query<&mut PrintTim
         timer.0.tick(time.delta());
 
         if timer.0.just_finished() {
-            println!("Sprites: {}", sprites.iter().count(),);
+            info!("Sprites: {}", sprites.iter().count(),);
         }
     }
 }

examples/app/drag_and_drop.rs

@@ -9,6 +9,6 @@ fn main() {
 
 fn file_drag_and_drop_system(mut events: EventReader<FileDragAndDrop>) {
     for event in events.iter() {
-        println!("{:?}", event);
+        info!("{:?}", event);
     }
 }

examples/app/plugin.rs

@@ -40,6 +40,6 @@ struct PrintMessageState {
 
 fn print_message_system(mut state: ResMut<PrintMessageState>, time: Res<Time>) {
     if state.timer.tick(time.delta()).finished() {
-        println!("{}", state.message);
+        info!("{}", state.message);
     }
 }

examples/app/plugin_group.rs

@@ -34,7 +34,7 @@ impl Plugin for PrintHelloPlugin {
 }
 
 fn print_hello_system() {
-    println!("hello");
+    info!("hello");
 }
 
 pub struct PrintWorldPlugin;
@@ -46,5 +46,5 @@ impl Plugin for PrintWorldPlugin {
 }
 
 fn print_world_system() {
-    println!("world");
+    info!("world");
 }

examples/asset/asset_loading.rs

@@ -31,9 +31,9 @@ fn setup(
         // You might notice that this doesn't run! This is because assets load in parallel without
         // blocking. When an asset has loaded, it will appear in relevant Assets<T>
         // collection.
-        println!("{:?}", sphere.primitive_topology());
+        info!("{:?}", sphere.primitive_topology());
     } else {
-        println!("sphere hasn't loaded yet");
+        info!("sphere hasn't loaded yet");
     }
 
     // You can load all assets in a folder like this. They will be loaded in parallel without

examples/asset/custom_asset.rs

@@ -60,6 +60,6 @@ fn print_on_load(mut state: ResMut<State>, custom_assets: ResMut<Assets<CustomAs
         return;
     }
 
-    println!("Custom asset loaded: {:?}", custom_asset.unwrap());
+    info!("Custom asset loaded: {:?}", custom_asset.unwrap());
     state.printed = true;
 }

examples/asset/custom_asset_io.rs

@@ -14,30 +14,30 @@ struct CustomAssetIo(Box<dyn AssetIo>);
 
 impl AssetIo for CustomAssetIo {
     fn load_path<'a>(&'a self, path: &'a Path) -> BoxedFuture<'a, Result<Vec<u8>, AssetIoError>> {
-        println!("load_path({:?})", path);
+        info!("load_path({:?})", path);
         self.0.load_path(path)
     }
 
     fn read_directory(
         &self,
         path: &Path,
     ) -> Result<Box<dyn Iterator<Item = PathBuf>>, AssetIoError> {
-        println!("read_directory({:?})", path);
+        info!("read_directory({:?})", path);
         self.0.read_directory(path)
     }
 
     fn is_directory(&self, path: &Path) -> bool {
-        println!("is_directory({:?})", path);
+        info!("is_directory({:?})", path);
         self.0.is_directory(path)
     }
 
     fn watch_path_for_changes(&self, path: &Path) -> Result<(), AssetIoError> {
-        println!("watch_path_for_changes({:?})", path);
+        info!("watch_path_for_changes({:?})", path);
         self.0.watch_path_for_changes(path)
     }
 
     fn watch_for_changes(&self) -> Result<(), AssetIoError> {
-        println!("watch_for_changes()");
+        info!("watch_for_changes()");
         self.0.watch_for_changes()
     }
 }