From 05e9e40745a0a9f14e87ee58d5c57cbaf3726fc8 Mon Sep 17 00:00:00 2001 From: Dave Wapstra Date: Fri, 10 May 2024 09:32:42 +1200 Subject: [PATCH 1/4] Add docs for automated log collection --- docs/aetest/debugging.rst | 64 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/docs/aetest/debugging.rst b/docs/aetest/debugging.rst index 93997a5..0f16a53 100644 --- a/docs/aetest/debugging.rst +++ b/docs/aetest/debugging.rst @@ -514,7 +514,7 @@ The pause will also dump the connection information, including which devices are .. note:: - + If it is required to connect to the device directly while the test is paused, the device connection must be disconnected from before it can be accessed directly. @@ -530,3 +530,65 @@ The pause will also dump the connection information, including which devices are >>> dev.connect() +Automated Log Collection +------------------------ + +The :ref:`aetest_pause_on_phase` feature works well for interactive debugging +and troubleshooting when you are running scripts manually. For automated runs, +we need a better way to collect information. The Automated Log Collection +feature builds on top of the Pause on Phrase functionality by adding two +additional actions: ``collect`` and ``custom``. + +``collect`` + pauses, collects information from devices using CLI commands and/or Genie + APIs and resumes the script execution. + +``custom`` + pauses, executes user provided, custom test code to collect information and + resumes script execution once completed. + +To enable this feature, provide the ``pause_on`` YAML file to your script run +with `collect` or `custom` actions as described below. + +The following schema describes the YAML pause file with the collect and custom options: + +.. code-block:: yaml + + # Pause On Phrase YAML Schema + # --------------------------- + + action: # action to be performed on pause (email/pdb/code/collect/custom) + # (required) + + patterns: # patterns to search & pause on (list) + # each list item needs to follow a particular structure as below + # (mandatory) + + - pattern: # pattern to pause on (str) + # this is internally compiled into a regex pattern used + # to match log messages with + # (mandatory) + + section: # section/uid to enable pattern searching (str) + # this is internally compiled into regex, used + # to match the current executing section uid + # note that you can use Testcase.setup to denote setup + # section of a testcase, etc. + # (if not provided, the pattern is used globally) + # (optional) + + collect: # For `collect` action, collection specific settings + devices: # collection for devices + : # device name + cmds: + - cmd: # List of CLI commands to collect + apis: + - api: # And/or List of Genie APIs to execute + + + custom: # For `custom` action, settings for custom log collection + + module: # package/module to load the method from + + method: # function to execute + From 5d5ac21174fbeceb7814cfc9ceda0ec80ae86535 Mon Sep 17 00:00:00 2001 From: Dave Wapstra Date: Wed, 15 May 2024 10:21:50 +1200 Subject: [PATCH 2/4] Update ALC docs --- docs/aetest/debugging.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/aetest/debugging.rst b/docs/aetest/debugging.rst index 0f16a53..c7f7ddc 100644 --- a/docs/aetest/debugging.rst +++ b/docs/aetest/debugging.rst @@ -550,6 +550,36 @@ additional actions: ``collect`` and ``custom``. To enable this feature, provide the ``pause_on`` YAML file to your script run with `collect` or `custom` actions as described below. +Example yaml configuration with custom handler: + +.. code-block:: yaml + + custom: + module: custom_action + method: myaction + additional_arguments: + key: value + +The function specified in the custom handler will be passed the following objects: + +* `section` object +* `Steps`` object +* Any data from the yaml under `custom` +* The log message that was matched +* The pattern match object + +Example custom log handler function: + +.. code-block:: python + + # custom_action.py + def myaction(section, steps, message=None, pattern_match=None, **kwargs): + logger.info(section) + logger.info(steps) + logger.info(message) + logger.info(pattern_match) + + The following schema describes the YAML pause file with the collect and custom options: .. code-block:: yaml @@ -592,3 +622,4 @@ The following schema describes the YAML pause file with the collect and custom o method: # function to execute + : From 8962a2ef98ac2537a0ad2092a3217d5c4dd5c444 Mon Sep 17 00:00:00 2001 From: Dave Wapstra Date: Wed, 15 May 2024 10:22:19 +1200 Subject: [PATCH 3/4] fix typo --- docs/aetest/debugging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/aetest/debugging.rst b/docs/aetest/debugging.rst index c7f7ddc..b09ee49 100644 --- a/docs/aetest/debugging.rst +++ b/docs/aetest/debugging.rst @@ -563,7 +563,7 @@ Example yaml configuration with custom handler: The function specified in the custom handler will be passed the following objects: * `section` object -* `Steps`` object +* `Steps` object * Any data from the yaml under `custom` * The log message that was matched * The pattern match object From 04875a568bf89ec45127ad799101e7d489e7a7c9 Mon Sep 17 00:00:00 2001 From: Dave Wapstra Date: Wed, 15 May 2024 10:24:01 +1200 Subject: [PATCH 4/4] Add action --- docs/aetest/debugging.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/aetest/debugging.rst b/docs/aetest/debugging.rst index b09ee49..7782105 100644 --- a/docs/aetest/debugging.rst +++ b/docs/aetest/debugging.rst @@ -554,6 +554,7 @@ Example yaml configuration with custom handler: .. code-block:: yaml + action: custom custom: module: custom_action method: myaction