From 77e243f62650dabe908f3b7e4fcbd39c2cde211b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Karol=20Bary=C5=82a?= <karol.baryla@scylladb.com>
Date: Fri, 26 Jan 2024 02:11:37 +0100
Subject: [PATCH] Docs: Document `log` limitations

---
 docs/source/logging/logging.md | 70 +++++++++++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

diff --git a/docs/source/logging/logging.md b/docs/source/logging/logging.md
index 198b3291f4..3740d74a50 100644
--- a/docs/source/logging/logging.md
+++ b/docs/source/logging/logging.md
@@ -45,4 +45,72 @@ 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
\ No newline at end of file
+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 tokio;
+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:
+```
+[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.