Refactor Logging Hierarchy (#997)

* Refactored logger names to adhere to a hierarchical structure for better log source tracing.

* API docs: add hierarchical logging + usage clarification

---------

Co-authored-by: Robsdedude <[email protected]>

Author: OliverFarren

CHANGELOG.md

@@ -4,6 +4,13 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
 
 ## NEXT RELEASE
 - No breaking or major changes.
+- Implemented a hierarchical logger structure to improve log source
+  identification and traceability.  
+  Introduced child loggers:
+  - `neo4j.io`: For socket and bolt protocol related logging.
+  - `neo4j.pool`: For logs pertaining to connection pooling and routing.
+  - `neo4j.auth_management`: For logging inside the provided AuthManager
+    implementations.
 
 
 ## Version 5.15

docs/source/api.rst

@@ -2080,9 +2080,30 @@ following code:
 Logging
 *******
 
-The driver offers logging for debugging purposes. It is not recommended to
-enable logging for anything other than debugging. For instance, if the driver is
-not able to connect to the database server or if undesired behavior is observed.
+The driver offers logging for debugging purposes.
+It is not recommended to enable logging for anything other than debugging.
+For instance, if the driver is not able to connect to the database server or if
+undesired behavior is observed.
+
+This includes messages logged on ``WARNING`` level or higher.
+They are logged to help understand what is going on *inside* the driver.
+All relevant information is passed through return values, raised exceptions,
+warnings, etc.
+The logs are not the right place to look for actionable information.
+
+The driver supports hierarchical logging.
+This means you can selectively configure all of the driver's logging or only
+parts of it.
+Currently available:
+
+* ``neo4j``: The root logger for the driver.
+  High-level code (e.g., Session, Transaction, Driver, etc.) logs here.
+
+  * ``neo4j.io``: Logs network activity and bolt protocol messages, handshakes,
+    etc.
+  * ``neo4j.pool``: Logs connection pool activity (including routing).
+  * ``neo4j.auth_management``: Logger for provided :class:`.AuthManager`
+    implementations.
 
 There are different ways of enabling logging as listed below.
 

src/neo4j/_async/auth_management.py

@@ -32,7 +32,7 @@
     from ..exceptions import Neo4jError
 
 
-log = getLogger("neo4j")
+log = getLogger("neo4j.auth_management")
 
 
 class AsyncStaticAuthManager(AsyncAuthManager):
@@ -67,7 +67,11 @@ def __init__(
         self._lock = AsyncLock()
 
     async def _refresh_auth(self):
-        self._current_auth = await self._provider()
+        try:
+            self._current_auth = await self._provider()
+        except BaseException as e:
+            log.error("[     ]  _: <AUTH MANAGER> provider failed: %r", e)
+            raise
         if self._current_auth is None:
             raise TypeError(
                 "Auth provider function passed to expiration_based "

src/neo4j/_async/io/_bolt.py

@@ -57,7 +57,7 @@
 
 
 # Set up logger
-log = getLogger("neo4j")
+log = getLogger("neo4j.io")
 
 
 class ServerStateManagerBase(abc.ABC):

src/neo4j/_async/io/_bolt3.py

@@ -49,7 +49,7 @@
 )
 
 
-log = getLogger("neo4j")
+log = getLogger("neo4j.io")
 
 
 class BoltStates(Enum):

src/neo4j/_async/io/_bolt4.py

@@ -51,7 +51,7 @@
 )
 
 
-log = getLogger("neo4j")
+log = getLogger("neo4j.io")
 
 
 class AsyncBolt4x0(AsyncBolt):

src/neo4j/_async/io/_bolt5.py

@@ -54,7 +54,7 @@
 )
 
 
-log = getLogger("neo4j")
+log = getLogger("neo4j.io")
 
 
 class AsyncBolt5x0(AsyncBolt):

src/neo4j/_async/io/_common.py

@@ -28,7 +28,7 @@
 )
 
 
-log = logging.getLogger("neo4j")
+log = logging.getLogger("neo4j.io")
 
 
 class AsyncInbox:

src/neo4j/_async/io/_pool.py

@@ -68,7 +68,7 @@
 
 
 # Set up logger
-log = getLogger("neo4j")
+log = getLogger("neo4j.pool")
 
 
 @dataclass

src/neo4j/_async/work/session.py

@@ -61,7 +61,7 @@
     _P = te.ParamSpec("_P")
 
 
-log = getLogger("neo4j")
+log = getLogger("neo4j.pool")
 
 
 class AsyncSession(AsyncWorkspace):