Updates the Logger interface to allow extensibility and type erasure (#273)

Removes all the logger::on_xxx functions
Removes the Logger template parameter to async_run
Adds a logger constructor that allows passing a std::function to customize logging behavior
Adds constructors to connection and basic_connection taking a logger
Deprecates config::logger_prefix
Deprecates the async_run overload taking a logger parameter
Deprecates the basic_connection::async_run overload not taking any config object
Deprecates the basic_connection::next_layer_type typedef
Makes the default log level logger::info
Makes the logging thread-safe
Cleans up deprecated functionality from examples
Adds docs on logging
Adds an example on how to integrate spdlog into Boost.Redis logging

close #213

Author: anarthal

README.md

@@ -407,6 +407,44 @@ imported in the global namespace by the user.  In the
 [Examples](#examples) section the reader can find examples showing how
 to serialize using json and [protobuf](https://protobuf.dev/).
 
+<a name="logging"></a>
+
+### Logging
+
+`connection::async_run` is a complex algorithm, with features like built-in reconnection.
+This can make configuration problems, like a misconfigured hostname, difficult to debug -
+Boost.Redis will keep retrying to connect to the same hostname over and over.
+For this reason, Boost.Redis incorporates a lightweight logging solution, and
+**will log some status messages to stderr by default**.
+
+Logging can be customized by passing a `logger` object to the `connection`'s constructor.
+
+For example, logging can be disabled by writing:
+
+```cpp
+asio::io_context ioc;
+redis::connection conn {ioc, redis::logger{redis::logger::level::disabled}};
+```
+
+Every message logged by the library is attached a
+[syslog-like severity](https://en.wikipedia.org/wiki/Syslog#Severity_level)
+tag (a `logger::level`).
+You can filter messages by severity by creating a `logger` with a specific level:
+
+```cpp
+asio::io_context ioc;
+
+// Logs to stderr messages with severity >= level::error.
+// This will hide all informational output.
+redis::connection conn {ioc, redis::logger{redis::logger::level::error}};
+```
+
+`logger`'s constructor accepts a `std::function<void(logger::level, std::string_view)>`
+as second argument. If supplied, Boost.Redis will call this function when logging
+instead of printing to stderr. This can be used to integrate third-party logging
+libraries. See our [spdlog integration example](example/cpp17_spdlog.cpp) for sample code.
+
+
 <a name="examples"></a>
 ## Examples
 
@@ -424,6 +462,7 @@ The examples below show how to use the features discussed so far
 * cpp20_chat_room.cpp: A command line chat built on Redis pubsub.
 * cpp17_intro.cpp: Uses callbacks and requires C++17.
 * cpp17_intro_sync.cpp: Runs `async_run` in a separate thread and performs synchronous calls to `async_exec`.
+* cpp17_spdlog.cpp: Shows how to use third-party logging libraries like `spdlog` with Boost.Redis.
 
 The main function used in some async examples has been factored out in
 the main.cpp file.

example/CMakeLists.txt

@@ -51,3 +51,12 @@ endif()
 if (NOT MSVC)
   make_example(cpp20_chat_room 20)
 endif()
+
+# We build and test the spdlog integration example only if the library is found
+find_package(spdlog)
+if (spdlog_FOUND)
+  make_testable_example(cpp17_spdlog 17)
+  target_link_libraries(cpp17_spdlog PRIVATE spdlog::spdlog)
+else()
+  message(STATUS "Skipping the spdlog example because the spdlog package couldn't be found")
+endif()

example/cpp17_intro.cpp

@@ -34,7 +34,7 @@ auto main(int argc, char* argv[]) -> int
       asio::io_context ioc;
       connection conn{ioc};
 
-      conn.async_run(cfg, {}, asio::detached);
+      conn.async_run(cfg, asio::detached);
 
       conn.async_exec(req, resp, [&](auto ec, auto) {
          if (!ec)

example/cpp17_spdlog.cpp

@@ -0,0 +1,102 @@
+//
+// Copyright (c) 2025 Marcelo Zimbres Silva ([email protected]),
+// Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#include <boost/redis/connection.hpp>
+#include <boost/redis/logger.hpp>
+
+#include <boost/asio/detached.hpp>
+#include <boost/system/error_code.hpp>
+
+#include <cstddef>
+#include <iostream>
+#include <spdlog/spdlog.h>
+#include <string_view>
+
+namespace asio = boost::asio;
+namespace redis = boost::redis;
+
+// Maps a Boost.Redis log level to a spdlog log level
+static spdlog::level::level_enum to_spdlog_level(redis::logger::level lvl)
+{
+   switch (lvl) {
+      // spdlog doesn't include the emerg and alert syslog levels,
+      // so we convert them to the highest supported level.
+      // Similarly, notice is similar to info
+      case redis::logger::level::emerg:
+      case redis::logger::level::alert:
+      case redis::logger::level::crit:    return spdlog::level::critical;
+      case redis::logger::level::err:     return spdlog::level::err;
+      case redis::logger::level::warning: return spdlog::level::warn;
+      case redis::logger::level::notice:
+      case redis::logger::level::info:    return spdlog::level::info;
+      case redis::logger::level::debug:
+      default:                            return spdlog::level::debug;
+   }
+}
+
+// This function glues Boost.Redis logging and spdlog.
+// It should have the signature shown here. It will be invoked
+// by Boost.Redis whenever a message is to be logged.
+static void do_log(redis::logger::level level, std::string_view msg)
+{
+   spdlog::log(to_spdlog_level(level), "(Boost.Redis) {}", msg);
+}
+
+auto main(int argc, char* argv[]) -> int
+{
+   if (argc != 3) {
+      std::cerr << "Usage: " << argv[0] << " <server-host> <server-port>\n";
+      exit(1);
+   }
+
+   try {
+      // Create an execution context, required to create any I/O objects
+      asio::io_context ioc;
+
+      // Create a connection to connect to Redis, and pass it a custom logger.
+      // Boost.Redis will call do_log whenever it needs to log a message.
+      // Note that the function will only be called for messages with level >= info
+      // (i.e. filtering is done by Boost.Redis).
+      redis::connection conn{
+         ioc,
+         redis::logger{redis::logger::level::info, do_log}
+      };
+
+      // Configuration to connect to the server
+      redis::config cfg;
+      cfg.addr.host = argv[1];
+      cfg.addr.port = argv[2];
+
+      // Run the connection with the specified configuration.
+      // This will establish the connection and keep it healthy
+      conn.async_run(cfg, asio::detached);
+
+      // Execute a request
+      redis::request req;
+      req.push("PING", "Hello world");
+
+      redis::response<std::string> resp;
+
+      conn.async_exec(req, resp, [&](boost::system::error_code ec, std::size_t /* bytes_read*/) {
+         if (ec) {
+            spdlog::error("Request failed: {}", ec.what());
+            exit(1);
+         } else {
+            spdlog::info("PING: {}", std::get<0>(resp).value());
+         }
+         conn.cancel();
+      });
+
+      // Actually run our example. Nothing will happen until we call run()
+      ioc.run();
+
+   } catch (std::exception const& e) {
+      spdlog::error("Error: {}", e.what());
+      return 1;
+   }
+}

example/cpp20_chat_room.cpp

@@ -86,7 +86,7 @@ auto co_main(config cfg) -> awaitable<void>
 
    co_spawn(ex, receiver(conn), detached);
    co_spawn(ex, publisher(stream, conn), detached);
-   conn->async_run(cfg, {}, consign(detached, conn));
+   conn->async_run(cfg, consign(detached, conn));
 
    signal_set sig_set{ex, SIGINT, SIGTERM};
    co_await sig_set.async_wait();

example/cpp20_containers.cpp

@@ -133,7 +133,7 @@ auto transaction(std::shared_ptr<connection> conn) -> awaitable<void>
 awaitable<void> co_main(config cfg)
 {
    auto conn = std::make_shared<connection>(co_await asio::this_coro::executor);
-   conn->async_run(cfg, {}, consign(detached, conn));
+   conn->async_run(cfg, consign(detached, conn));
 
    co_await store(conn);
    co_await transaction(conn);

example/cpp20_echo_server.cpp

@@ -60,7 +60,7 @@ auto co_main(config cfg) -> asio::awaitable<void>
    auto ex = co_await asio::this_coro::executor;
    auto conn = std::make_shared<connection>(ex);
    asio::co_spawn(ex, listener(conn), asio::detached);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    signal_set sig_set(ex, SIGINT, SIGTERM);
    co_await sig_set.async_wait();

example/cpp20_intro.cpp

@@ -24,7 +24,7 @@ using boost::redis::connection;
 auto co_main(config cfg) -> asio::awaitable<void>
 {
    auto conn = std::make_shared<connection>(co_await asio::this_coro::executor);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    // A request containing only a ping command.
    request req;

example/cpp20_intro_tls.cpp

@@ -8,6 +8,7 @@
 
 #include <boost/asio/consign.hpp>
 #include <boost/asio/detached.hpp>
+#include <boost/asio/ssl/context.hpp>
 #include <boost/asio/use_awaitable.hpp>
 
 #include <iostream>
@@ -35,17 +36,18 @@ auto co_main(config cfg) -> asio::awaitable<void>
    cfg.addr.host = "db.occase.de";
    cfg.addr.port = "6380";
 
-   auto conn = std::make_shared<connection>(co_await asio::this_coro::executor);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   asio::ssl::context ctx{asio::ssl::context::tlsv12_client};
+   ctx.set_verify_mode(asio::ssl::verify_peer);
+   ctx.set_verify_callback(verify_certificate);
+
+   auto conn = std::make_shared<connection>(co_await asio::this_coro::executor, std::move(ctx));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    request req;
    req.push("PING");
 
    response<std::string> resp;
 
-   conn->next_layer().set_verify_mode(asio::ssl::verify_peer);
-   conn->next_layer().set_verify_callback(verify_certificate);
-
    co_await conn->async_exec(req, resp);
    conn->cancel();
 

example/cpp20_json.cpp

@@ -58,7 +58,7 @@ auto co_main(config cfg) -> asio::awaitable<void>
 {
    auto ex = co_await asio::this_coro::executor;
    auto conn = std::make_shared<connection>(ex);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    // user object that will be stored in Redis in json format.
    user const u{"Joao", "58", "Brazil"};

example/cpp20_protobuf.cpp

@@ -64,7 +64,7 @@ asio::awaitable<void> co_main(config cfg)
 {
    auto ex = co_await asio::this_coro::executor;
    auto conn = std::make_shared<connection>(ex);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    person p;
    p.set_name("Louis");

example/cpp20_resolve_with_sentinel.cpp

@@ -44,10 +44,9 @@ auto resolve_master_address(std::vector<address> const& addresses) -> asio::awai
       // TODO: async_run and async_exec should be lauched in
       // parallel here so we can wait for async_run completion
       // before eventually calling it again.
-      conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+      conn->async_run(cfg, asio::consign(asio::detached, conn));
       co_await conn->async_exec(req, resp, redir(ec));
       conn->cancel();
-      conn->reset_stream();
       if (!ec && std::get<0>(resp))
          co_return address{
             std::get<0>(resp).value().value().at(0),

example/cpp20_streams.cpp

@@ -88,7 +88,7 @@ auto co_main(config cfg) -> net::awaitable<void>
 
    // Disable health checks.
    cfg.health_check_interval = std::chrono::seconds::zero();
-   conn->async_run(cfg, {}, net::consign(net::detached, conn));
+   conn->async_run(cfg, net::consign(net::detached, conn));
 
    signal_set sig_set(ex, SIGINT, SIGTERM);
    co_await sig_set.async_wait();

example/cpp20_subscriber.cpp

@@ -87,7 +87,7 @@ auto co_main(config cfg) -> asio::awaitable<void>
    auto ex = co_await asio::this_coro::executor;
    auto conn = std::make_shared<connection>(ex);
    asio::co_spawn(ex, receiver(conn), asio::detached);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    signal_set sig_set(ex, SIGINT, SIGTERM);
    co_await sig_set.async_wait();

example/cpp20_unix_sockets.cpp

@@ -34,7 +34,7 @@ auto co_main(config cfg) -> asio::awaitable<void>
    cfg.unix_socket = "/tmp/redis-socks/redis.sock";
 
    auto conn = std::make_shared<connection>(co_await asio::this_coro::executor);
-   conn->async_run(cfg, {}, asio::consign(asio::detached, conn));
+   conn->async_run(cfg, asio::consign(asio::detached, conn));
 
    request req;
    req.push("PING");

example/sync_connection.hpp

@@ -33,7 +33,7 @@ class sync_connection {
       // Starts a thread that will can io_context::run on which the
       // connection will run.
       thread_ = std::thread{[this, cfg]() {
-         conn_->async_run(cfg, {}, asio::detached);
+         conn_->async_run(cfg, asio::detached);
          ioc_.run();
       }};
    }

include/boost/redis/config.hpp

@@ -60,7 +60,13 @@ struct config {
    /// Message used by the health-checker in `boost::redis::connection::async_run`.
    std::string health_check_id = "Boost.Redis";
 
-   /// Logger prefix, see `boost::redis::logger`.
+   /**
+    * @brief (Deprecated) Sets the logger prefix, a string printed before log messages.
+    * 
+    * Setting a prefix in this struct is deprecated. If you need to change how log messages
+    * look like, please construct a logger object passing a formatting function, and use that
+    * logger in connection's constructor. This member will be removed in subsequent releases.
+    */
    std::string log_prefix = "(Boost.Redis) ";
 
    /// Time the resolve operation is allowed to last.