PYCBC-1619: Enable use of C++ file logger

Motivation
==========
Allow users to output C++ core logging to file.

Modification
============
* IF PYCBC_LOG_FILE environment variable is set, use C++ core file
  logger.  NOTE: PYCBC_LOG_LEVEL must be set as well.

Results
=======
* C++ core logging outputs to file when PYCBC_LOG_LEVEL and
  PYCBC_LOG_FILE are set.

Change-Id: I59029bc36b233f8b783d97f3832b9e4e3d839ed1
Reviewed-on: https://review.couchbase.org/c/couchbase-python-client/+/217909
Reviewed-by: Michael Reiche <michael.reiche@couchbase.com>
Tested-by: Build Bot <build@couchbase.com>
Reviewed-by: Sergey Avseyev <sergey.avseyev@gmail.com>

Author: thejcfactor

couchbase/__init__.py

@@ -84,9 +84,11 @@
 def _pycbc_teardown(**kwargs):
     """**INTERNAL**"""
     global _PYCBC_LOGGER
-    # if using a console logger we let the nature course of shutdown happening, if using Python logging
+    # if using a console logger we let the natural course of shutdown happen, if using Python logging
     # we need a cleaner mechanism to shutdown the C++ logger prior to the Python interpreter starting to finalize
-    if _PYCBC_LOGGER and isinstance(_PYCBC_LOGGER, pycbc_logger) and not _PYCBC_LOGGER.is_console_logger():
+    if (_PYCBC_LOGGER
+        and isinstance(_PYCBC_LOGGER, pycbc_logger)
+            and not (_PYCBC_LOGGER.is_console_logger() or _PYCBC_LOGGER.is_file_logger())):
         shutdown_logger()
         _PYCBC_LOGGER = None
 
@@ -143,14 +145,22 @@ def configure_console_logger():
     import os
     log_level = os.getenv('PYCBC_LOG_LEVEL', None)
     if log_level:
-        _PYCBC_LOGGER.create_console_logger(log_level.lower())
+        log_file = os.getenv('PYCBC_LOG_FILE', None)
+        if log_file:
+            _PYCBC_LOGGER.create_logger(level=log_level.lower(), filename=log_file)
+        else:
+            _PYCBC_LOGGER.create_logger(level=log_level.lower())
         logging.getLogger().debug(get_metadata(as_str=True))
 
 
 def configure_logging(name, level=logging.INFO, parent_logger=None):
     if parent_logger:
         name = f'{parent_logger.name}.{name}'
     logger = logging.getLogger(name)
+    if _PYCBC_LOGGER.is_console_logger() or _PYCBC_LOGGER.is_file_logger():
+        raise RuntimeError(('Cannot create logger.  Another logger has already been '
+                            'initialized. Make sure the PYCBC_LOG_LEVEL and PYCBC_LOG_FILE env '
+                            'variable are not set if using configure_logging.'))
     _PYCBC_LOGGER.configure_logging_sink(logger, level)
     logger.debug(get_metadata(as_str=True))
 

src/logger.cxx

@@ -66,18 +66,19 @@ pycbc_logger__configure_logging_sink__(PyObject* self, PyObject* args, PyObject*
 }
 
 PyObject*
-pycbc_logger__create_console_logger__(PyObject* self, PyObject* args, PyObject* kwargs)
+pycbc_logger__create_logger__(PyObject* self, PyObject* args, PyObject* kwargs)
 {
   auto logger = reinterpret_cast<pycbc_logger*>(self);
   char* log_level = nullptr;
-  const char* kw_list[] = { "level", nullptr };
-  const char* kw_format = "s";
+  char* log_filename = nullptr;
+  const char* kw_list[] = { "level", "filename", nullptr };
+  const char* kw_format = "s|s";
   if (!PyArg_ParseTupleAndKeywords(
-        args, kwargs, kw_format, const_cast<char**>(kw_list), &log_level)) {
+        args, kwargs, kw_format, const_cast<char**>(kw_list), &log_level, &log_filename)) {
     pycbc_set_python_exception(PycbcError::InvalidArgument,
                                __FILE__,
                                __LINE__,
-                               "Cannot set create console logger.  Unable to parse args/kwargs.");
+                               "Cannot create logger.  Unable to parse args/kwargs.");
     return nullptr;
   }
 
@@ -86,21 +87,29 @@ pycbc_logger__create_console_logger__(PyObject* self, PyObject* args, PyObject*
       PycbcError::UnsuccessfulOperation,
       __FILE__,
       __LINE__,
-      "Cannot create console logger.  Another logger has already been initialized.");
+      "Cannot create logger.  Another logger has already been initialized.");
     return nullptr;
   }
 
   if (log_level == nullptr) {
     pycbc_set_python_exception(PycbcError::InvalidArgument,
                                __FILE__,
                                __LINE__,
-                               "Cannot create console logger.  Unable to determine log level.");
+                               "Cannot create logger.  Unable to determine log level.");
     return nullptr;
   }
-  couchbase::core::logger::create_console_logger();
   auto level = couchbase::core::logger::level_from_str(log_level);
-  couchbase::core::logger::set_log_levels(level);
-  logger->is_console_logger = true;
+  if (log_filename != nullptr) {
+    couchbase::core::logger::configuration configuration{};
+    configuration.filename = std::string{ log_filename };
+    configuration.log_level = level;
+    couchbase::core::logger::create_file_logger(configuration);
+    logger->is_file_logger = true;
+  } else {
+    couchbase::core::logger::create_console_logger();
+    couchbase::core::logger::set_log_levels(level);
+    logger->is_console_logger = true;
+  }
   Py_RETURN_NONE;
 }
 
@@ -137,24 +146,42 @@ pycbc_logger__is_console_logger__(PyObject* self, PyObject* Py_UNUSED(ignored))
   }
 }
 
-static PyMethodDef pycbc_logger_methods[] = { { "configure_logging_sink",
-                                                (PyCFunction)pycbc_logger__configure_logging_sink__,
-                                                METH_VARARGS | METH_KEYWORDS,
-                                                PyDoc_STR("Configure logger's logging sink") },
-                                              { "create_console_logger",
-                                                (PyCFunction)pycbc_logger__create_console_logger__,
-                                                METH_VARARGS | METH_KEYWORDS,
-                                                PyDoc_STR("Create a console logger") },
-                                              { "enable_protocol_logger",
-                                                (PyCFunction)pycbc_logger__enable_protocol_logger__,
-                                                METH_VARARGS | METH_KEYWORDS,
-                                                PyDoc_STR("Enables the protocol logger") },
-                                              { "is_console_logger",
-                                                (PyCFunction)pycbc_logger__is_console_logger__,
-                                                METH_NOARGS,
-                                                PyDoc_STR(
-                                                  "Check if logger is console logger or not") },
-                                              { NULL } };
+PyObject*
+pycbc_logger__is_file_logger__(PyObject* self, PyObject* Py_UNUSED(ignored))
+{
+  auto logger = reinterpret_cast<pycbc_logger*>(self);
+  if (logger->is_file_logger) {
+    Py_INCREF(Py_True);
+    return Py_True;
+  } else {
+    Py_INCREF(Py_False);
+    return Py_False;
+  }
+}
+
+static PyMethodDef pycbc_logger_methods[] = {
+  { "configure_logging_sink",
+    (PyCFunction)pycbc_logger__configure_logging_sink__,
+    METH_VARARGS | METH_KEYWORDS,
+    PyDoc_STR("Configure logger's logging sink") },
+  { "create_logger",
+    (PyCFunction)pycbc_logger__create_logger__,
+    METH_VARARGS | METH_KEYWORDS,
+    PyDoc_STR("Create a C++ core logger") },
+  { "enable_protocol_logger",
+    (PyCFunction)pycbc_logger__enable_protocol_logger__,
+    METH_VARARGS | METH_KEYWORDS,
+    PyDoc_STR("Enables the protocol logger") },
+  { "is_console_logger",
+    (PyCFunction)pycbc_logger__is_console_logger__,
+    METH_NOARGS,
+    PyDoc_STR("Check if logger is console logger or not") },
+  { "is_file_logger",
+    (PyCFunction)pycbc_logger__is_file_logger__,
+    METH_NOARGS,
+    PyDoc_STR("Check if logger is file logger or not") },
+  { NULL }
+};
 
 static PyObject*
 pycbc_logger_new(PyTypeObject* type, PyObject*, PyObject*)

src/logger.hxx

@@ -225,6 +225,7 @@ private:
 struct pycbc_logger {
   PyObject_HEAD std::shared_ptr<pycbc_logger_sink> logger_sink_;
   bool is_console_logger{ false };
+  bool is_file_logger{ false };
 };
 
 PyObject*