Introduce Loader interface to support alternative event and metric initialization methods

cmd/metrics/event_frame.go

@@ -118,12 +118,22 @@ func parseEvents(rawEvents [][]byte, eventGroupDefinitions []GroupDefinition) ([
 	previousEvent := ""
 	var eventsNotCounted []string
 	var eventsNotSupported []string
-	for _, rawEvent := range rawEvents {
+	for i, rawEvent := range rawEvents {
 		event, err := parseEventJSON(rawEvent) // nosemgrep
 		if err != nil {
-			slog.Error(err.Error(), slog.String("event", string(rawEvent)))
+			// if error log the current line and up to 5 more lines
+			out := string(rawEvent)
+			for j := i + 1; j < len(rawEvents) && j < i+5; j++ {
+				out += "\n" + string(rawEvents[j])
+			}
+			slog.Error(err.Error(), slog.String("perf output", out))
 			return nil, err
 		}
+		// sometimes perf will prepend "cpu/" to the topdown event names, e.g., cpu/topdown-retiring/, we clean it up here to match metric formulas
+		if strings.HasPrefix(event.Event, "cpu/") && strings.Contains(event.Event, "topdown") && strings.HasSuffix(event.Event, "/") {
+			event.Event = strings.TrimPrefix(event.Event, "cpu/")
+			event.Event = strings.TrimSuffix(event.Event, "/")
+		}
 		switch event.CounterValue {
 		case "<not counted>":
 			slog.Debug("event not counted", slog.String("event", string(rawEvent)))

cmd/metrics/loader.go

@@ -0,0 +1,75 @@
+package metrics
+
+// Copyright (C) 2021-2025 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+
+import (
+	"fmt"
+	"log/slog"
+	"strings"
+
+	"github.com/Knetic/govaluate"
+)
+
+type MetricDefinition struct {
+	Name        string                         `json:"name"`
+	Expression  string                         `json:"expression"`
+	Description string                         `json:"description"`
+	Variables   map[string]int                 // parsed from Expression for efficiency, int represents group index
+	Evaluable   *govaluate.EvaluableExpression // parse expression once, store here for use in metric evaluation
+}
+
+// EventDefinition represents a single perf event
+type EventDefinition struct {
+	Raw    string
+	Name   string
+	Device string
+}
+
+// GroupDefinition represents a group of perf events
+type GroupDefinition []EventDefinition
+
+type Loader interface {
+	Load(metricDefinitionOverridePath string, eventDefinitionOverridePath string, selectedMetrics []string, metadata Metadata) (metrics []MetricDefinition, groups []GroupDefinition, err error)
+}
+
+type BaseLoader struct {
+	microarchitecture string
+}
+
+type LegacyLoader struct {
+	BaseLoader
+}
+
+type PerfmonLoader struct {
+	BaseLoader
+}
+
+func NewLoader(uarch string) (Loader, error) {
+	switch strings.ToLower(uarch) {
+	case "clx", "skx", "bdx", "bergamo", "genoa", "turin":
+		slog.Debug("Using legacy loader for microarchitecture", slog.String("uarch", uarch))
+		return newLegacyLoader(strings.ToLower(uarch)), nil
+	case "gnr", "srf", "emr", "spr", "icx":
+		slog.Debug("Using perfmon loader for microarchitecture", slog.String("uarch", uarch))
+		return newPerfmonLoader(strings.ToLower(uarch)), nil
+	default:
+		return nil, fmt.Errorf("unsupported microarchitecture: %s", uarch)
+	}
+}
+
+func newLegacyLoader(uarch string) *LegacyLoader {
+	return &LegacyLoader{
+		BaseLoader: BaseLoader{
+			microarchitecture: uarch,
+		},
+	}
+}
+
+func newPerfmonLoader(uarch string) *PerfmonLoader {
+	return &PerfmonLoader{
+		BaseLoader: BaseLoader{
+			microarchitecture: uarch,
+		},
+	}
+}

cmd/metrics/event_defs.go → cmd/metrics/loader_legacy.go

@@ -3,10 +3,9 @@ package metrics
 // Copyright (C) 2021-2025 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 
-// helper functions for parsing and interpreting the architecture-specific perf event definition files
-
 import (
 	"bufio"
+	"encoding/json"
 	"fmt"
 	"io/fs"
 	"log/slog"
@@ -19,19 +18,73 @@ import (
 	mapset "github.com/deckarep/golang-set/v2"
 )
 
-// EventDefinition represents a single perf event
-type EventDefinition struct {
-	Raw    string
-	Name   string
-	Device string
+func (l *LegacyLoader) Load(metricDefinitionOverridePath string, eventDefinitionOverridePath string, selectedMetrics []string, metadata Metadata) ([]MetricDefinition, []GroupDefinition, error) {
+	loadedMetricDefinitions, err := loadMetricDefinitions(metricDefinitionOverridePath, selectedMetrics, metadata)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to load metric definitions: %w", err)
+	}
+	loadedEventGroups, uncollectableEvents, err := loadEventGroups(eventDefinitionOverridePath, metadata)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to load event group definitions: %w", err)
+	}
+	configuredMetricDefinitions, err := configureMetrics(loadedMetricDefinitions, uncollectableEvents, metadata)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to configure metrics: %w", err)
+	}
+	return configuredMetricDefinitions, loadedEventGroups, nil
 }
 
-// GroupDefinition represents a group of perf events
-type GroupDefinition []EventDefinition
+// loadMetricDefinitions reads and parses metric definitions from an architecture-specific metric
+// definition file. When the override path argument is empty, the function will load metrics from
+// the file associated with the platform's architecture found in the provided metadata. When
+// a list of metric names is provided, only those metric definitions will be loaded.
+func loadMetricDefinitions(metricDefinitionOverridePath string, selectedMetrics []string, metadata Metadata) (metrics []MetricDefinition, err error) {
+	var bytes []byte
+	if metricDefinitionOverridePath != "" {
+		bytes, err = os.ReadFile(metricDefinitionOverridePath) // #nosec G304
+		if err != nil {
+			return
+		}
+	} else {
+		uarch := strings.ToLower(strings.Split(metadata.Microarchitecture, "_")[0])
+		uarch = strings.Split(uarch, " ")[0]
+		metricFileName := fmt.Sprintf("%s.json", uarch)
+		if bytes, err = resources.ReadFile(filepath.Join("resources", "legacy", "metrics", metadata.Architecture, metadata.Vendor, metricFileName)); err != nil {
+			return
+		}
+	}
+	var metricsInFile []MetricDefinition
+	if err = json.Unmarshal(bytes, &metricsInFile); err != nil {
+		return
+	}
+	// if a list of metric names provided, reduce list to match
+	if len(selectedMetrics) > 0 {
+		// confirm provided metric names are valid (included in metrics defined in file)
+		// and build list of metrics based on provided list of metric names
+		metricMap := make(map[string]MetricDefinition)
+		for _, metric := range metricsInFile {
+			metricMap[metric.Name] = metric
+		}
+		for _, selectedMetricName := range selectedMetrics {
+			if _, ok := metricMap[selectedMetricName]; !ok {
+				err = fmt.Errorf("provided metric name not found: %s", selectedMetricName)
+				return
+			}
+			metrics = append(metrics, metricMap[selectedMetricName])
+		}
+	} else {
+		metrics = metricsInFile
+	}
+	// abbreviate event names in metrics to shorten the eventual perf stat command line
+	for i := range metrics {
+		metrics[i].Expression = abbreviateEventName(metrics[i].Expression)
+	}
+	return
+}
 
-// LoadEventGroups reads the events defined in the architecture specific event definition file, then
+// loadEventGroups reads the events defined in the architecture specific event definition file, then
 // expands them to include the per-device uncore events
-func LoadEventGroups(eventDefinitionOverridePath string, metadata Metadata) (groups []GroupDefinition, uncollectableEvents []string, err error) {
+func loadEventGroups(eventDefinitionOverridePath string, metadata Metadata) (groups []GroupDefinition, uncollectableEvents []string, err error) {
 	var file fs.File
 	if eventDefinitionOverridePath != "" {
 		file, err = os.Open(eventDefinitionOverridePath) // #nosec G304
@@ -41,22 +94,14 @@ func LoadEventGroups(eventDefinitionOverridePath string, metadata Metadata) (gro
 	} else {
 		uarch := strings.ToLower(strings.Split(metadata.Microarchitecture, "_")[0])
 		uarch = strings.Split(uarch, " ")[0]
-		// use alternate events/metrics when TMA fixed counters are not supported
-		alternate := ""
-		if (uarch == "icx" || uarch == "spr" || uarch == "emr" || uarch == "gnr") && !metadata.SupportsFixedTMA { // AWS/GCP VM instances
-			alternate = "_nofixedtma"
-		}
-		eventFileName := fmt.Sprintf("%s%s.txt", uarch, alternate)
-		if file, err = resources.Open(filepath.Join("resources", "events", metadata.Architecture, metadata.Vendor, eventFileName)); err != nil {
+		eventFileName := fmt.Sprintf("%s.txt", uarch)
+		if file, err = resources.Open(filepath.Join("resources", "legacy", "events", metadata.Architecture, metadata.Vendor, eventFileName)); err != nil {
 			return
 		}
 	}
 	defer file.Close()
 	scanner := bufio.NewScanner(file)
 	uncollectable := mapset.NewSet[string]()
-	if flagTransactionRate == 0 {
-		uncollectable.Add("TXN")
-	}
 	var group GroupDefinition
 	for scanner.Scan() {
 		line := strings.TrimSpace(scanner.Text())
@@ -104,65 +149,22 @@ func LoadEventGroups(eventDefinitionOverridePath string, metadata Metadata) (gro
 	return
 }
 
-// abbreviateEventName replaces long event names with abbreviations to reduce the length of the perf command.
-// focus is on uncore events because they are repeated for each uncore device
-func abbreviateEventName(event string) string {
-	// Abbreviations must be unique and in order. And, if replacing UNC_*, the abbreviation must begin with "UNC" because this is how we identify uncore events when collapsing them.
-	var abbreviations = [][]string{
-		{"UNC_CHA_TOR_INSERTS", "UNCCTI"},
-		{"UNC_CHA_TOR_OCCUPANCY", "UNCCTO"},
-		{"UNC_CHA_CLOCKTICKS", "UNCCCT"},
-		{"UNC_M_CAS_COUNT_SCH", "UNCMCC"},
-		{"IA_MISS_DRD_REMOTE", "IMDR"},
-		{"IA_MISS_DRD_LOCAL", "IMDL"},
-		{"IA_MISS_LLCPREFDATA", "IMLP"},
-		{"IA_MISS_LLCPREFRFO", "IMLR"},
-		{"IA_MISS_DRD_PREF_LOCAL", "IMDPL"},
-		{"IA_MISS_DRD_PREF_REMOTE", "IMDRP"},
-		{"IA_MISS_CRD_PREF", "IMCP"},
-		{"IA_MISS_RFO_PREF", "IMRP"},
-		{"IA_MISS_RFO", "IMRF"},
-		{"IA_MISS_CRD", "IMC"},
-		{"IA_MISS_DRD", "IMD"},
-		{"IO_PCIRDCUR", "IPCI"},
-		{"IO_ITOMCACHENEAR", "IITN"},
-		{"IO_ITOM", "IITO"},
-		{"IMD_OPT", "IMDO"},
-	}
-	// if an abbreviation key is found in the event, replace the matching portion of the event with the abbreviation
-	for _, abbr := range abbreviations {
-		event = strings.Replace(event, abbr[0], abbr[1], -1)
-	}
-	return event
-}
-
 // isCollectableEvent confirms if given event can be collected on the platform
 func isCollectableEvent(event EventDefinition, metadata Metadata) bool {
 	// fixed-counter TMA
 	if !metadata.SupportsFixedTMA && (event.Name == "TOPDOWN.SLOTS" || strings.HasPrefix(event.Name, "PERF_METRICS.")) {
 		slog.Debug("Fixed counter TMA not supported on target", slog.String("event", event.Name))
 		return false
 	}
-	// PEBS events (not supported on GCP c4 VMs)
-	pebsEventNames := []string{"INT_MISC.UNKNOWN_BRANCH_CYCLES", "UOPS_RETIRED.MS"}
-	if !metadata.SupportsPEBS {
-		for _, pebsEventName := range pebsEventNames {
-			if strings.Contains(event.Name, pebsEventName) {
-				slog.Debug("PEBS events not supported on target", slog.String("event", event.Name))
-				return false
-			}
-		}
-	}
 	// short-circuit for cpu events that aren't off-core response events
-	if event.Device == "cpu" && !(strings.HasPrefix(event.Name, "OCR") || strings.HasPrefix(event.Name, "OFFCORE_REQUESTS_OUTSTANDING")) {
+	if event.Device == "cpu" && !strings.HasPrefix(event.Name, "OCR") {
 		return true
 	}
-	// off-core response events
-	if event.Device == "cpu" && (strings.HasPrefix(event.Name, "OCR") || strings.HasPrefix(event.Name, "OFFCORE_REQUESTS_OUTSTANDING")) {
-		if !(metadata.SupportsOCR && metadata.SupportsUncore) {
-			slog.Debug("Off-core response events not supported on target", slog.String("event", event.Name))
-			return false
-		} else if flagScope == scopeProcess || flagScope == scopeCgroup {
+	// short-circuit off-core response events
+	if event.Device == "cpu" &&
+		strings.HasPrefix(event.Name, "OCR") &&
+		metadata.SupportsUncore {
+		if flagScope == scopeProcess || flagScope == scopeCgroup {
 			slog.Debug("Off-core response events not supported in process or cgroup scope", slog.String("event", event.Name))
 			return false
 		}
@@ -296,3 +298,35 @@ func expandUncoreGroups(groups []GroupDefinition, metadata Metadata) (expandedGr
 	}
 	return
 }
+
+// abbreviateEventName replaces long event names with abbreviations to reduce the length of the perf command.
+// focus is on uncore events because they are repeated for each uncore device
+func abbreviateEventName(event string) string {
+	// Abbreviations must be unique and in order. And, if replacing UNC_*, the abbreviation must begin with "UNC" because this is how we identify uncore events when collapsing them.
+	var abbreviations = [][]string{
+		{"UNC_CHA_TOR_INSERTS", "UNCCTI"},
+		{"UNC_CHA_TOR_OCCUPANCY", "UNCCTO"},
+		{"UNC_CHA_CLOCKTICKS", "UNCCCT"},
+		{"UNC_M_CAS_COUNT_SCH", "UNCMCC"},
+		{"IA_MISS_DRD_REMOTE", "IMDR"},
+		{"IA_MISS_DRD_LOCAL", "IMDL"},
+		{"IA_MISS_LLCPREFDATA", "IMLP"},
+		{"IA_MISS_LLCPREFRFO", "IMLR"},
+		{"IA_MISS_DRD_PREF_LOCAL", "IMDPL"},
+		{"IA_MISS_DRD_PREF_REMOTE", "IMDRP"},
+		{"IA_MISS_CRD_PREF", "IMCP"},
+		{"IA_MISS_RFO_PREF", "IMRP"},
+		{"IA_MISS_RFO", "IMRF"},
+		{"IA_MISS_CRD", "IMC"},
+		{"IA_MISS_DRD", "IMD"},
+		{"IO_PCIRDCUR", "IPCI"},
+		{"IO_ITOMCACHENEAR", "IITN"},
+		{"IO_ITOM", "IITO"},
+		{"IMD_OPT", "IMDO"},
+	}
+	// if an abbreviation key is found in the event, replace the matching portion of the event with the abbreviation
+	for _, abbr := range abbreviations {
+		event = strings.Replace(event, abbr[0], abbr[1], -1)
+	}
+	return event
+}