added comments

Author: MattyWeee123

buildenv/jenkins/benchmarkMetric.py

@@ -14,6 +14,8 @@ def main():
         benchmarkMetricsTemplate = json.loads(benchmarkMetricsTemplate_json)
 
         tests = args.testNames.split(",") 
+        
+        #populate the template file with corresponding metrics extracted from console log
         for test in tests: 
                 for metric in benchmarkMetricsTemplate[test].values():
                         regex_parser = re.search(metric.get("regex"), console)

buildenv/jenkins/initBenchmarkMetrics.py

@@ -1,15 +1,18 @@
 import argparse, pathlib, json
 
+#extract necessary benchmark information from metricConfig based on test, and 
+#update benchmarkMetrics such that it is optimal for later processing 
 def initBenchmarkMetrics(metricConfig, test, benchmarkMetrics): 
         test_info = test.split("-")
-        benchmarkMap = metricConfig[test_info[0]]
+        benchmarkMap = metricConfig[test_info[0]] #index by general test category
         metricMap = benchmarkMap["metrics"]
-        if len(test_info) > 1:
+        if len(test_info) > 1: #if there is a variant, grab it directly 
                 variant = test_info[1]
                 if (metricMap.get(variant) != None): 
                         benchmarkMetrics.update({test : {variant : metricMap[variant]}})
                         return 
 
+        #if there is no variant, we take the metricMap to already contain the unique information needed for test
         benchmarkMetrics.update({test : metricMap})
 
 def main():
@@ -27,15 +30,15 @@ def main():
         tests = args.testNames.split(",")
         for test in tests: initBenchmarkMetrics(metricConfig, test, benchmarkMetrics)
         benchmarkMetrics_json = json.dumps(benchmarkMetrics)
-        pathlib.Path(f"{args.runBase}").write_text(benchmarkMetrics_json, encoding="utf-8")
+        pathlib.Path(f"{args.runBase}").write_text(benchmarkMetrics_json, encoding="utf-8") #serves as template populated by a single run
 
         for test in tests: 
                 for metric in benchmarkMetrics[test].values():
                         metric.update({"test" : {"values" : []}})
                         metric.update({"baseline" : {"values" : []}})
 
         benchmarkMetrics_json = json.dumps(benchmarkMetrics)
-        pathlib.Path(f"{args.aggrBase}").write_text(benchmarkMetrics_json, encoding="utf-8")
+        pathlib.Path(f"{args.aggrBase}").write_text(benchmarkMetrics_json, encoding="utf-8") #serves as aggregate file populated by all runs
 
 if __name__ == "__main__":
         main()

buildenv/jenkins/metricConfig2JSON.py

@@ -1,5 +1,6 @@
 import argparse, pathlib, json, re
 
+#regex used to convert BenchmarkMetric.js into valid JSON file
 RE_COMMENT = re.compile(r"""
         //.*?$ |
         /\*.*?\*/
@@ -13,6 +14,8 @@
 
 RE_KEYS = re.compile(r"""([,{]\s*)([A-Za-z_]\w*)(\s*:)""")
 
+#parses the BenchmarkMetric.js file by grabbing the BenchmarkMetricRegex element, 
+#removing comments, and converting to proper JSON syntax 
 def js_to_json(metrics_js):
         benchmark_parser = re.search(r"const\s+BenchmarkMetricRegex\s*=\s*({[\s\S]*?});", metrics_js) 
         if not benchmark_parser:

buildenv/jenkins/perfPipeline.groovy

@@ -11,7 +11,7 @@ if (params.SETUP_LABEL) {
     SETUP_LABEL = params.SETUP_LABEL
 } else {
     if (PROCESS_METRICS && EXIT_EARLY) {
-       SETUP_LABEL = "test-rhibmcloud-rhel9-x64-1"
+       SETUP_LABEL = "test-rhibmcloud-rhel9-x64-1" //machine needs python
    } else {
        SETUP_LABEL = "ci.role.test&&hw.arch.x86&&sw.os.linux"
    }
@@ -62,7 +62,7 @@ node (SETUP_LABEL) {
                                 }
                         }
 
-                        if (PROCESS_METRICS) {
+                        if (PROCESS_METRICS) { //convert BenchmarkMetric.js to a JSON file optimized for metric processing 
                                 def owner = params.ADOPTOPENJDK_REPO.tokenize('/')[2]
                                 getPythonDependencies(owner, params.ADOPTOPENJDK_BRANCH) 
                                 sh "curl -Os  https://raw.githubusercontent.com/adoptium/aqa-test-tools/refs/heads/master/TestResultSummaryService/parsers/BenchmarkMetric.js"
@@ -71,7 +71,8 @@ node (SETUP_LABEL) {
                                 testList = params.TARGET.split("=")[1].tokenize(",")
                                 metrics = readJSON file: aggrBase
                         }
-                        else {
+                        
+                        if (!EXIT_EARLY) {
                                 testParams << string(name: "TARGET", value: params.TARGET) 
                                 baselineParams << string(name: "TARGET", value: params.TARGET)
                         }
@@ -82,8 +83,8 @@ node (SETUP_LABEL) {
                                         //clone to avoid mutation
                                         def thisTestParams = testParams.collect()
                                         def thisBaselineParams = baselineParams.collect()
-                                        if (PROCESS_METRICS) {     
-                                                //set the target, testlist should change if some metrics regress while others do not
+                                        if (EXIT_EARLY) {     
+                                                //update TARGET, testlist should hold metrics that were not exited early
                                                 testNames = testList.join(",")
                                                 def TARGET = params.TARGET.replaceFirst(/(?<=TESTLIST=)[^ ]+/, testNames)
                                                 thisTestParams << string(name: "TARGET", value: TARGET)
@@ -108,15 +109,17 @@ node (SETUP_LABEL) {
                                                 aggregateLogs(baseRun, testNames, testList, runBase, metrics, "baseline")
                                                 writeJSON file: "metrics.json", json: metrics, pretty: 4
                                                 archiveArtifacts artifacts: "metrics.json" 
+
+                                                //if we are on the final iteration, or we have executed enough iterations to decide likelihood of regression and have permission to exit early 
                                                 if (i == PERF_ITERATIONS-1 || (EXIT_EARLY && i >= PERF_ITERATIONS * 0.8)) {
                                                         if (i == PERF_ITERATIONS-1) {
                                                                 echo "All iterations completed"
                                                         } else {
                                                                 echo "Attempting early exit"
                                                         }
                                                         echo "checking for regressions"
-                                                        checkRegressions(metrics, testList)
-                                                        if (testList.size() == 0) break 
+                                                        checkRegressions(metrics, testList) //compute relevant performance stats, check for regression
+                                                        if (testList.size() == 0) break //if all tests have been exited early we can end testing
                                                 }
                                         }
                                 }

buildenv/jenkins/perfPipeline_root.groovy

@@ -59,7 +59,7 @@ node("worker || (ci.role.test&&hw.arch.x86&&sw.os.linux)") {
                 baseParams << string(name: "BENCHMARK", value: item.BENCHMARK)
                 baseParams << string(name: "TARGET", value: item.TARGET)
                 baseParams << string(name: "BUILD_LIST", value: item.BUILD_LIST)
-                baseParams << string(name: "PERF_ITERATIONS", value: item.PERF_ITERATIONS ? item.PERF_ITERATIONS.toString() : "4")
+                baseParams << string(name: "PERF_ITERATIONS", value: item.PERF_ITERATIONS ? item.PERF_ITERATIONS.toString() : "4") //by default, test 4 pairs of test,baseline runs
 
                 item.PLAT_MACHINE_MAP.each { kv -> 
                         kv.each {p, m ->