From: jaskiratsingh Date: Fri, 5 Apr 2019 13:51:12 +0000 (-0400) Subject: Improve documentation for connection pool logging X-Git-Tag: rel_1_3_3~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2b25827b8455aaaa8c73180d0c26afb3e3187adc;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 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 a22b7f22b3..7a01b6af85 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -263,9 +263,11 @@ Python's standard `logging `_ 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 a759d648ce..c7b4c1ce5d 100644 --- 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 ea73f08d44..f5585c6519 100644 --- 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