Improve documentation for connection pool logging

Also do a general pass for logging + doc formatting,
add more cross-linking and remove obsolete information such
as "echo_uow"/

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Fixes: #4571
Closes: #4583
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4583
Pull-request-sha: e98ad34eca7e9f59fb07cd8b7ec317c1cb989848

Change-Id: I03f7354a4ef55fd8b6a51d03a280579f36e8a06c

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index a22b7f22b351064359288169c1a668e4d3bd8366..7a01b6af85659ee89d0da2465b8c71d57ecbda57 100644 (file)
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -263,9 +263,11 @@ Python's standard `logging
 <http://docs.python.org/library/logging.html>`_ module is used to
 implement informational and debug log output with SQLAlchemy. This allows
 SQLAlchemy's logging to integrate in a standard way with other applications
-and libraries. The ``echo`` and ``echo_pool`` flags that are present on
-:func:`~sqlalchemy.create_engine`, as well as the ``echo_uow`` flag used on
-:class:`~sqlalchemy.orm.session.Session`, all interact with regular loggers.
+and libraries.   There are also two parameters
+:paramref:`.create_engine.echo` and :paramref:`.create_engine.echo_pool`
+present on :func:`.create_engine` which allow immediate logging to ``sys.stdout``
+for the purposes of local development; these parameters ultimately interact
+with the regular Python loggers described below.
 
 This section assumes familiarity with the above linked logging module. All
 logging performed by SQLAlchemy exists underneath the ``sqlalchemy``
@@ -273,12 +275,27 @@ namespace, as used by ``logging.getLogger('sqlalchemy')``. When logging has
 been configured (i.e. such as via ``logging.basicConfig()``), the general
 namespace of SA loggers that can be turned on is as follows:
 
-* ``sqlalchemy.engine`` - controls SQL echoing.  set to ``logging.INFO`` for SQL query output, ``logging.DEBUG`` for query + result set output.
-* ``sqlalchemy.dialects`` - controls custom logging for SQL dialects.  See the documentation of individual dialects for details.
-* ``sqlalchemy.pool`` - controls connection pool logging.  set to ``logging.INFO`` or lower to log connection pool checkouts/checkins.
-* ``sqlalchemy.orm`` - controls logging of various ORM functions.  set to ``logging.INFO`` for information on mapper configurations.
+* ``sqlalchemy.engine`` - controls SQL echoing.  set to ``logging.INFO`` for
+  SQL query output, ``logging.DEBUG`` for query + result set output.  These
+  settings are equivalent to ``echo=True`` and ``echo="debug"`` on
+  :paramref:`.create_engine.echo`, respectively.
 
-For example, to log SQL queries using Python logging instead of the ``echo=True`` flag::
+* ``sqlalchemy.pool`` - controls connection pool logging.  set to
+  ``logging.INFO`` to log connection invalidation and recycle events; set to
+  ``logging.DEBUG`` to additionally log all pool checkins and checkouts.
+  These settings are equivalent to ``pool_echo=True`` and ``pool_echo="debug"``
+  on :paramref:`.create_engine.echo_pool`, respectively.
+
+* ``sqlalchemy.dialects`` - controls custom logging for SQL dialects, to the
+  extend that logging is used within specific dialects, which is generally
+  minimal.
+
+* ``sqlalchemy.orm`` - controls logging of various ORM functions to the extent
+  that logging is used within the ORM, which is generally minimal.  Set to
+  ``logging.INFO`` to log some top-level information on mapper configurations.
+
+For example, to log SQL queries using Python logging instead of the
+``echo=True`` flag::
 
     import logging
 

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index a759d648ceb2fb3f9a415e8aacffe63e8646a09b..c7b4c1ce5d181bb959cc5b01a7506fd559d3b7f7 100644 (file)
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -161,19 +161,31 @@ def create_engine(*args, **kwargs):
         parameters specified in the URL argument to be bypassed.
 
     :param echo=False: if True, the Engine will log all statements
-        as well as a repr() of their parameter lists to the engines
-        logger, which defaults to sys.stdout. The ``echo`` attribute of
-        ``Engine`` can be modified at any time to turn logging on and
-        off. If set to the string ``"debug"``, result rows will be
-        printed to the standard output as well. This flag ultimately
-        controls a Python logger; see :ref:`dbengine_logging` for
-        information on how to configure logging directly.
+        as well as a ``repr()`` of their parameter lists to the default log
+        handler, which defaults to ``sys.stdout`` for output.   If set to the
+        string ``"debug"``, result rows will be printed to the standard output
+        as well. The ``echo`` attribute of ``Engine`` can be modified at any
+        time to turn logging on and off; direct control of logging is also
+        available using the standard Python ``logging`` module.
+
+        .. seealso::
+
+            :ref:`dbengine_logging` - further detail on how to configure
+            logging.
 
     :param echo_pool=False: if True, the connection pool will log
-        all checkouts/checkins to the logging stream, which defaults to
-        sys.stdout. This flag ultimately controls a Python logger; see
-        :ref:`dbengine_logging` for information on how to configure logging
-        directly.
+        informational output such as when connections are invalidated
+        as well as when connections are recycled to the default log handler,
+        which defaults to ``sys.stdout`` for output.   If set to the string
+        ``"debug"``, the logging will include pool checkouts and checkins.
+        Direct control of logging is also available using the standard Python
+        ``logging`` module.
+
+        .. seealso::
+
+            :ref:`dbengine_logging` - further detail on how to configure
+            logging.
+
 
     :param empty_in_strategy:  The SQL compilation strategy to use when
         rendering an IN or NOT IN expression for :meth:`.ColumnOperators.in_`

diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py
index ea73f08d44d582ba5a63193a1e5b0ccccc54c32b..f5585c6519eb9da1236565e0ef14fe80b0857a7b 100644 (file)
--- a/lib/sqlalchemy/pool/base.py
+++ b/lib/sqlalchemy/pool/base.py
@@ -105,11 +105,20 @@ class Pool(log.Identified):
           "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
           id.
 
-        :param echo: If True, connections being pulled and retrieved
-          from the pool will be logged to the standard output, as well
-          as pool sizing information.  Echoing can also be achieved by
-          enabling logging for the "sqlalchemy.pool"
-          namespace. Defaults to False.
+        :param echo: if True, the connection pool will log
+         informational output such as when connections are invalidated
+         as well as when connections are recycled to the default log handler,
+         which defaults to ``sys.stdout`` for output..   If set to the string
+         ``"debug"``, the logging will include pool checkouts and checkins.
+
+         The :paramref:`.Pool.echo` parameter can also be set from the
+         :func:`.create_engine` call by using the
+         :paramref:`.create_engine.echo_pool` parameter.
+
+         .. seealso::
+
+             :ref:`dbengine_logging` - further detail on how to configure
+             logging.
 
         :param use_threadlocal: If set to True, repeated calls to
           :meth:`connect` within the same application thread will be