From 6cc298f2870c918a191bde428f12f1d88bf84a44 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/.python-version           |  1 +
 docs/source/logging/logging.md | 69 +++++++++++++++++++++++++++++++++-
 scylla/Cargo.toml              |  1 +
 3 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 docs/.python-version

diff --git a/docs/.python-version b/docs/.python-version
new file mode 100644
index 0000000000..9919bf8c90
--- /dev/null
+++ b/docs/.python-version
@@ -0,0 +1 @@
+3.10.13
diff --git a/docs/source/logging/logging.md b/docs/source/logging/logging.md
index 198b3291f4..2a32f3a4d0 100644
--- a/docs/source/logging/logging.md
+++ b/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
\ 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 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.
diff --git a/scylla/Cargo.toml b/scylla/Cargo.toml
index 9f8654d985..5fbeafacc2 100644
--- a/scylla/Cargo.toml
+++ b/scylla/Cargo.toml
@@ -66,6 +66,7 @@ ntest = "0.9.0"
 criterion = "0.4" # Note: v0.5 needs at least rust 1.70.0
 tokio = { version = "1.27", features = ["test-util"] }
 tracing-subscriber = { version = "0.3.14", features = ["env-filter"] }
+env_logger = "0.11"
 assert_matches = "1.5.0"
 rand_chacha = "0.3.1"
 time = "0.3"