From dd76b0aabf0c17a1eb7d4b15cd09d737421e5641 Mon Sep 17 00:00:00 2001
From: Anurag Singh <dr.anuragkr@gmail.com>
Date: Sat, 19 Sep 2026 11:41:00 +0530
Subject: [PATCH] docs: document set_log_path() usage and hook examples

Explain how to access set_log_path() on LoggingPlugin and provide examples
for configuring dynamic log file paths in pytest_configure and
pytest_runtest_setup hooks.

Fixes #8086
---
 AUTHORS                   |  1 +
 changelog/8086.doc.rst    |  1 +
 doc/en/how-to/logging.rst | 50 +++++++++++++++++++++++++++++++++++++--
 3 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 changelog/8086.doc.rst

diff --git a/AUTHORS b/AUTHORS
index e2fad5e8364..d17624b25fd 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -52,6 +52,7 @@ Anton Grinevich
 Anton Lodder
 Anton Zhilin
 Antony Lee
+Anurag Singh
 Arel Cordero
 Arias Emmanuel
 Ariel Pillemer
diff --git a/changelog/8086.doc.rst b/changelog/8086.doc.rst
new file mode 100644
index 00000000000..97d8a377415
--- /dev/null
+++ b/changelog/8086.doc.rst
@@ -0,0 +1 @@
+Added documentation and hook usage examples for the experimental ``set_log_path()`` method in :ref:`logging` how-to.
diff --git a/doc/en/how-to/logging.rst b/doc/en/how-to/logging.rst
index 25b4e9017e2..3600b007a1a 100644
--- a/doc/en/how-to/logging.rst
+++ b/doc/en/how-to/logging.rst
@@ -239,8 +239,54 @@ option names are:
 * :confval:`log_file_format`
 * :confval:`log_file_date_format`
 
-You can call ``set_log_path()`` to customize the log_file path dynamically. This functionality
-is considered **experimental**. Note that ``set_log_path()`` respects the :confval:`log_file_mode` option.
+You can call ``set_log_path()`` to customize the ``log_file`` path dynamically. This functionality
+is considered **experimental**. Note that ``set_log_path()`` respects the :confval:`log_file_mode` option
+and creates parent directories automatically if they do not exist.
+
+``set_log_path()`` is a method of the ``LoggingPlugin`` instance. You can access it from hooks
+or fixtures by retrieving the plugin via ``config.pluginmanager.get_plugin("logging-plugin")``.
+
+For example, to configure a dynamic, timestamped log file per test session in a :file:`conftest.py`:
+
+.. code-block:: python
+
+    from datetime import datetime
+    from pathlib import Path
+    import pytest
+
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_configure(config: pytest.Config) -> None:
+        logging_plugin = config.pluginmanager.get_plugin("logging-plugin")
+        if logging_plugin is not None:
+            timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+            log_dir = Path(config.rootpath) / "logs"
+            logging_plugin.set_log_path(str(log_dir / f"pytest-{timestamp}.log"))
+
+.. note::
+
+    In ``pytest_configure``, mark the hook with ``@pytest.hookimpl(trylast=True)`` so that
+    ``logging-plugin`` is already registered and initialized when your hook runs.
+
+You can also call ``set_log_path()`` in ``pytest_runtest_setup`` to record separate log files for each test item:
+
+.. code-block:: python
+
+    from hashlib import sha256
+    from pathlib import Path
+    import pytest
+
+
+    @pytest.hookimpl(wrapper=True, tryfirst=True)
+    def pytest_runtest_setup(item: pytest.Item):
+        logging_plugin = item.config.pluginmanager.get_plugin("logging-plugin")
+        if logging_plugin is not None:
+            # item.nodeid uniquely identifies each test; hashing avoids
+            # filesystem-unsafe characters (such as "::" or parameters).
+            log_name = sha256(item.nodeid.encode()).hexdigest()
+            log_file = Path(item.config.rootpath) / "logs" / f"{log_name}.log"
+            logging_plugin.set_log_path(str(log_file))
+        return (yield)
 
 .. _log_colors: