Docs: Document log limitations

docs/source/logging/logging.md

@@ -45,4 +45,71 @@ To start this example execute:
 RUST_LOG=info cargo run
 ```
 
-The full [example](https://github.com/scylladb/scylla-rust-driver/tree/main/examples/logging.rs) is available in the `examples` folder
+The full [example](https://github.com/scylladb/scylla-rust-driver/tree/main/examples/logging.rs) is available in the `examples` folder
+
+## 'log' compatibility
+
+It may be surprising for some that viewing drivers logs using `log` ecosystem doesn't work out of the box despite `tracing` having a compatiblity layer
+behind `log` / `log-always` feature flags. 
+
+The problem is that this compatibility using `log` feature (which is recommended for libraries) seems to not work well with `.with_current_subscriber()` / Tokio tasks.
+For example, for the following program:
+```rust
+# extern crate env_logger;
+# extern crate log;
+# extern crate tokio;
+# extern crate tracing;
+// main.rs
+
+use tracing::instrument::WithSubscriber;
+
+#[tokio::main]
+async fn main() {
+    env_logger::init_from_env(env_logger::Env::new().default_filter_or("info"));
+
+    log::info!("info log");
+    tracing::info!("info tracing");
+
+    tokio::spawn(
+        async move {
+            log::info!("spawned info log");
+            tracing::info!("spawned info tracing")
+        }
+        .with_current_subscriber(),
+    )
+    .await
+    .unwrap();
+
+    log::info!("another info log");
+    tracing::info!("another info tracing");
+}
+
+```
+
+```toml
+# Cargo.toml
+
+[package]
+name = "reproducer"
+version = "1.0.0"
+edition = "2021"
+
+[dependencies]
+env_logger = "0.10"
+log = "0.4"
+tracing = { version = "0.1.36", features = [ "log" ] }
+tokio = { version = "1.27", features = [ "full" ] }
+```
+
+the output is:
+```bash
+[2024-01-26T00:51:06Z INFO  reproducer] info log
+[2024-01-26T00:51:06Z INFO  reproducer] info tracing
+[2024-01-26T00:51:06Z INFO  reproducer] spawned info log
+[2024-01-26T00:51:06Z INFO  reproducer] another info log
+```
+
+The other feature, `log-always`, works with the driver - but is not something we want to enable in this library.
+We recommend using tracing ecosystem, but if for some reason you need to stick with `log`, you can try
+enabling `log-always` feature in `tracing` by adding it to your direct dependencies (`tracing = { version = "0.1", features = [ "log-always" ] }`).
+This should enable driver log collection via `log` loggers.

examples/Cargo.toml

@@ -20,6 +20,7 @@ uuid = "1.0"
 tower = "0.4"
 stats_alloc = "0.1"
 clap = { version = "3.2.4", features = ["derive"] }
+env_logger = "0.10"
 
 [[example]]
 name = "auth"