python: initial TOML support for perfflow config

- update docs
- add test for toml config
- use verbose mode for running tests

.github/workflows/github-actions.yml

@@ -85,4 +85,5 @@ jobs:
       - name: Run Python Smoke Tests
         run: |
           cd src/python/test
-          ./t0001-pybinding-basic.t
+          python -m pip list
+          ./t0001-pybinding-basic.t --verbose

docs/QuickStart.rst

@@ -63,3 +63,39 @@ Details on these can be found at the links below:
 
 - **Chrome Tracing Tool:** https://www.chromium.org/developers/how-tos/trace-event-profiling-tool/
 - **Perfetto Visualizer:** https://perfetto.dev/
+
+Users are able to customize PerfFlowAspect at runtime by changing the following
+environment variable: ``export PERFFLOW_OPTIONS=``. Combining options are in
+the colon (:) delimited form:``<parameter>=<value>:<parameter>=<value>...``
+
+ ====================== =============== =================================================
+  parameter              default value   supported metadata
+ ====================== =============== =================================================
+  name                   generic
+  log-filename-include   hostname,pid    | name: workflow component name
+                                         | instance-path: hierarchical component path
+                                         | hostname: name of host where process is running
+                                         | pid: process ID
+  log-dir                ./
+ ====================== =============== =================================================
+
+Alternatively, PerfFlowOptions can be specified in a TOML config file.
+
+Create a TOML file named ``perfflowaspect_config.toml`` and paste the following content into the file:
+
+.. code-block:: toml
+
+    title = "PerfFlowAspect TOML Config"
+
+    [perfflow-options]
+    log-dir = "output-dir"
+    log-filename-include = "name,hostname,pid"
+    name = "helloworld"
+
+Running the test example can be done as follows:
+
+.. code:: bash
+
+    PERFFLOW_TOML_FILE="perfflowaspect_config.toml" ./smoketest.py
+
+This will create a directory called ``output-dir`` where all PerfFlowAspect output files (``*.pfw``) will be located. The PerfFlowAspect output files will be in the form of ``perfflow.helloworld.<hostname>.<pid>.pfw``.

src/python/perfflowaspect/advice_chrome.py

@@ -18,6 +18,7 @@
 import logging
 import functools
 import hashlib
+import toml
 from urllib.parse import urlparse
 from .aspect_base import perfflowaspect
 
@@ -40,10 +41,32 @@ def cannonicalize_perfflow_options():
         perfflow_options["log-dir"] = "./"
 
 
+def load_perfflow_toml_config(toml_config):
+    config = toml.load(toml_config)
+    print("Loaded specification -- %s\n" % toml_config)
+
+    perfflow_opts = None
+    count = 0
+
+    for k,v in config["perfflow-options"].items():
+        if not perfflow_opts:
+            perfflow_opts = k + "=" + v
+        perfflow_opts += ":" + k + "=" + v
+    os.environ["PERFFLOW_OPTIONS"] = perfflow_opts
+
+
 def parse_perfflow_options():
     options_list = []
     options = os.getenv("PERFFLOW_OPTIONS")
-    if options is not None:
+
+    toml_config = os.getenv("PERFFLOW_TOML_FILE")
+
+    # set PERFFLOW_OPTIONS from TOML config file
+    if options is None and toml_config:
+        load_perfflow_toml_config(toml_config)
+        options = os.getenv("PERFFLOW_OPTIONS")
+
+    if options:
         options_list = options.split(":")
     for opt in options_list:
         kv = opt.split("=")
@@ -52,6 +75,9 @@ def parse_perfflow_options():
         else:
             print("Ill-formed option: {}".format(opt), file=sys.stderr)
     cannonicalize_perfflow_options()
+    print("PerfFlow Config:")
+    for k, v in perfflow_options.items():
+        print("  ", k, "=", v)
 
 
 def get_foreign_wm():

src/python/setup.py

@@ -34,7 +34,7 @@ def load_readme():
     author_email="[email protected], [email protected], [email protected], [email protected]",
     packages=["perfflowaspect"],
     entry_points={},
-    install_requires=[],
+    install_requires=["toml"],
     extras_require={},
     long_description=load_readme(),
     long_description_content_type="text/markdown",

src/python/test/t0001-pybinding-basic.t

@@ -137,4 +137,10 @@ PERFFLOW_OPTIONS="log-filename-include=instance-path" ../smoketest.py &&
     rm perfflow.{fffffff.444444.123456}.pfw
 '
 
+test_expect_success 'PERFFLOW_OPTIONS: TOML config works' '
+    PERFFLOW_TOML_FILE="../perfflowaspect_config.toml" ../smoketest.py
+    sanity_check ./logdir-test/perfflow.helloworld.$(hostname).[0-9]*.pfw
+    rm -rf ./logdir-test
+'
+
 test_done