From ccefdf30995b199d98e9f47926697da973f12148 Mon Sep 17 00:00:00 2001
From: Nicola Coretti <nicola.coretti@exasol.com>
Date: Wed, 13 Mar 2024 09:41:39 +0100
Subject: [PATCH] Update documentation and release notes

---
 doc/changes/unreleased.md   | 22 ++++++++++++++++++++++
 doc/examples/logger.py      | 26 ++++++++++++++++++++++++++
 doc/user_guide/advanced.rst |  7 +++++++
 doc/user_guide/basics.rst   |  7 +++++++
 4 files changed, 62 insertions(+)
 create mode 100644 doc/examples/logger.py

diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md
index 77b50d2f..c68c1bbd 100644
--- a/doc/changes/unreleased.md
+++ b/doc/changes/unreleased.md
@@ -1,5 +1,27 @@
 # Unreleased
 
+## Added 
+- Added logging support
+    **Overview**
+
+    The bucketfs logger can be referenced via `exasol.bucketfs`
+
+    ```python
+    import logging
+    # Get the logger for 'exasol.bucketfs'
+    logger = logging.getLogger('exasol.bucketfs')
+    ```
+
+    For most use cases it should be sufficient to just configure the root logger, in order
+    to retrieve the logs from bucketfs.
+
+    ```python
+    import logging
+
+    logging.basicConfig(level=logging.INFO)
+    ```
+
+
 ## Internal
 - Relock dependencies
 - Update abatilo/actions-poetry from `v2.1.4` to `v3.0.0`
diff --git a/doc/examples/logger.py b/doc/examples/logger.py
new file mode 100644
index 00000000..b44bb078
--- /dev/null
+++ b/doc/examples/logger.py
@@ -0,0 +1,26 @@
+import logging
+from exasol.bucketfs import Service
+
+logging.basicConfig(level=logging.INFO)
+
+# Advanced Logging
+import logging
+from exasol.bucketfs import Service
+
+# Attention:
+# It is essential to configure the root logger at the beginning of your script.
+# This ensures that log messages, including those from the bucketfs are handled correctly.
+# Without proper configuration, log messages might not appear as expected.
+logging.basicConfig(level=logging.INFO)
+
+# Explicityly Configure the bucketfs logger if you need to.
+#
+# 1. Get a reference to the bucketfs logger
+bucketfs_logger = logging.getLogger('exasol.bucketfs')
+
+# 2. Configure the bucketfs logger as needed
+# Note:
+#   By default bucketfs logger is set to NOTSET (https://docs.python.org/3.11/library/logging.html#logging.NOTSET)
+#   which should be sufficient in lots of cases where the root logger is configured approriately.
+bucketfs_logger.setLevel(logging.DEBUG)
+...
diff --git a/doc/user_guide/advanced.rst b/doc/user_guide/advanced.rst
index 4c1316e8..25f4e2bc 100644
--- a/doc/user_guide/advanced.rst
+++ b/doc/user_guide/advanced.rst
@@ -39,3 +39,10 @@ Delete files from Bucket
    :start-after: # Expert/Mapped bucket API
 
 
+Configure logging
++++++++++++++++++
+
+.. literalinclude:: /examples/logger.py
+   :language: python3
+   :start-after: # Advanced Logging
+
diff --git a/doc/user_guide/basics.rst b/doc/user_guide/basics.rst
index f80c5160..04725195 100644
--- a/doc/user_guide/basics.rst
+++ b/doc/user_guide/basics.rst
@@ -74,3 +74,10 @@ Delete files from Bucket
    :end-before: # Expert/Mapped bucket API
 
 
+Configure logging
++++++++++++++++++
+
+.. literalinclude:: /examples/logger.py
+   :language: python3
+   :end-before: # Advanced Logging
+