feat: move metadata labels to client level with per-instance merge (#164)

## Summary
Comprehensive metadata labels support across the UI, building on the
backend label infrastructure.

### Label Filtering
- Replace single-value label filters with multi-value chip UI (OR within
key, AND across keys) on the runs table, suite detail page, and suites
page — consistent Grafana-style filter chips everywhere
- URL format: `key1:val1|val2,key2:val3`

### Label Visibility
- **Run detail page**: show metadata labels as blue chips between stats
cards and GitHub section
- **Runs table**: expandable row via tag icon (rightmost column) with
label chips and instance ID; hover popover on the tag icon; suite hash
hover popover showing suite name, hash, filter, test count, and labels
- **Heatmap tooltip**: show instance ID and labels when hovering over
run squares

### Suite Detail — Group By
- Add group-by selector (label key or instance ID) to the suite detail
Runs tab
- **Heatmap**: renders grouped sections with headers, each containing
per-client rows with independent stats
- **Charts**: separate series per client+group combo via client name
suffixing
- **Chart filters**: client toggle badges and label chip filters for the
Run Charts section, using base client names so they work correctly with
group-by active
- Fix ECharts `notMerge` so filtered-out series actually disappear

### Suite Detail — Compare Buttons
- Per-group compare button in heatmap headers (compare latest successful
run per client within a group)
- Cross-group compare button per client badge (compare a client's latest
successful run across all groups)
- Cross-group compare defaults the compare page label mode to the
group-by key

### Compare Page
- Dynamic label mode options built from runs' metadata (in addition to
None and Instance ID)
- Label mode stored in URL as `label:{key}` for metadata labels

### Infrastructure
- Centralize client chart colors in `client-colors.ts` with
`getBaseClient()` extraction so grouped names like "geth / mainnet"
resolve to correct colors in badges, charts, and logos

## Test plan
- [x] Verify label filter chips work on /runs, suite detail runs tab,
and /suites pages
- [x] Verify labels show on run detail page, runs table (tag icon +
popover), and heatmap tooltip
- [x] Test group-by on suite detail: heatmap sections, chart series,
chart filters
- [x] Test per-group and cross-group compare buttons navigate correctly
- [x] Verify compare page shows dynamic label options and defaults from
group-by
- [x] Verify client colors are correct across all views when group-by is
active

Author: skylenet

cmd/benchmarkoor/run.go

@@ -64,11 +64,11 @@ func runBenchmark(cmd *cobra.Command, args []string) error {
 			return fmt.Errorf("invalid metadata label %q: must be key=value", entry)
 		}
 
-		if cfg.Runner.Metadata.Labels == nil {
-			cfg.Runner.Metadata.Labels = make(map[string]string, len(metadataLabels))
+		if cfg.Runner.Client.Config.Metadata.Labels == nil {
+			cfg.Runner.Client.Config.Metadata.Labels = make(map[string]string, len(metadataLabels))
 		}
 
-		cfg.Runner.Metadata.Labels[k] = v
+		cfg.Runner.Client.Config.Metadata.Labels[k] = v
 	}
 
 	// Parse results owner configuration.

config.example.yaml

@@ -20,13 +20,6 @@ runner:
   # Uses Go duration format (e.g., "1h", "30m", "2h30m").
   # Can also be set via BENCHMARKOOR_RUNNER_RUN_TIMEOUT environment variable.
   # run_timeout: 4h
-  # Optional: Arbitrary key-value labels attached to this benchmark run.
-  # Labels appear in the run's config.json and can be used for filtering/organization.
-  # Can also be set via CLI: --metadata.label=env=production --metadata.label=team=platform
-  # metadata:
-  #   labels:
-  #     env: production
-  #     team: platform
   # Optional directory configurations.
   # directories:
   #   # Directory for temporary datadir copies (defaults to system temp).
@@ -382,6 +375,14 @@ runner:
       #   # CPU frequency governor (common: performance, powersave, schedutil)
       #   # Defaults to "performance" when cpu_freq is set
       #   cpu_freq_governor: performance
+      # Optional: Default metadata labels for all instances.
+      # Labels appear in each run's config.json and can be used for filtering/organization.
+      # Can also be set via CLI: --metadata.label=env=production --metadata.label=team=platform
+      # Instance-level labels (see instances below) are merged and take precedence.
+      # metadata:
+      #   labels:
+      #     env: production
+      #     team: platform
       # Genesis file URLs per client type
       genesis:
         besu: https://github.com/nethermindeth/gas-benchmarks/raw/refs/heads/main/scripts/genesisfiles/besu/zkevmgenesis.json
@@ -470,6 +471,9 @@ runner:
       #       enabled: true
       #       filename: trace
       # bootstrap_fcu: true  # Instance-level override (optional)
+      # metadata:  # Instance-level labels (optional, merged with client defaults, instance wins)
+      #   labels:
+      #     variant: snap-sync
 
     # Example: running multiple clients
     # - id: nethermind-latest

docs/configuration.md

@@ -141,17 +141,30 @@ sudo systemctl start podman.socket
 
 #### Metadata Labels
 
-The `runner.metadata.labels` field attaches arbitrary key-value pairs to a benchmark run. Labels are included in the output `config.json` and can be used for filtering and organization (e.g., in the UI or CI pipelines).
+The `runner.client.config.metadata.labels` field attaches arbitrary key-value pairs to benchmark runs. Labels are included in each run's output `config.json` and can be used for filtering and organization (e.g., in the UI or CI pipelines).
+
+Labels can be set at the client level (defaults for all instances) and overridden per instance. Instance-level labels are merged with client-level labels, with instance values taking precedence on conflict.
 
 ```yaml
 runner:
-  metadata:
-    labels:
-      env: production
-      team: platform
+  client:
+    config:
+      metadata:
+        labels:
+          env: production
+          team: platform
+  instances:
+    - id: geth-latest
+      client: geth
+      metadata:
+        labels:
+          env: staging      # overrides client-level "env"
+          variant: snap-sync  # additional instance-specific label
 ```
 
-Labels can also be set (or overridden) via the CLI flag `--metadata.label`:
+In this example, `geth-latest` runs will have labels `env=staging`, `team=platform`, and `variant=snap-sync`.
+
+Labels can also be set (or overridden) at the client level via the CLI flag `--metadata.label`:
 
 ```bash
 benchmarkoor run --config config.yaml \

pkg/api/handlers_index.go

@@ -69,6 +69,13 @@ func (s *server) handleIndex(w http.ResponseWriter, r *http.Request) {
 			entry.Tests.Steps = &executor.IndexStepsStats{}
 		}
 
+		if run.MetadataJSON != "" {
+			var m map[string]string
+			if json.Unmarshal([]byte(run.MetadataJSON), &m) == nil {
+				entry.Metadata = m
+			}
+		}
+
 		entries = append(entries, indexEntryWithDP{
 			DiscoveryPath: run.DiscoveryPath,
 			IndexEntry:    entry,

pkg/api/indexer/indexer.go

@@ -430,6 +430,15 @@ func (idx *indexer) indexRun(
 		}
 	}
 
+	// Serialize metadata labels to JSON.
+	metadataJSON := ""
+	if len(entry.Metadata) > 0 {
+		b, mErr := json.Marshal(entry.Metadata)
+		if mErr == nil {
+			metadataJSON = string(b)
+		}
+	}
+
 	now := time.Now().UTC()
 
 	run := &indexstore.Run{
@@ -449,6 +458,7 @@ func (idx *indexer) indexRun(
 		TestsPassed:       entry.Tests.TestsPassed,
 		TestsFailed:       entry.Tests.TestsFailed,
 		StepsJSON:         stepsJSON,
+		MetadataJSON:      metadataJSON,
 		IndexedAt:         now,
 	}
 

pkg/api/indexstore/run.go

@@ -28,6 +28,9 @@ type Run struct {
 	// Per-step stats serialized as JSON.
 	StepsJSON string `gorm:"type:text"`
 
+	// Run metadata labels serialized as JSON.
+	MetadataJSON string `gorm:"type:text"`
+
 	IndexedAt   time.Time
 	ReindexedAt *time.Time
 }

pkg/api/openapi.yaml

@@ -1474,6 +1474,11 @@ components:
           type: string
         termination_reason:
           type: string
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+          description: Run metadata labels (key-value pairs)
         instance:
           type: object
           properties:

pkg/config/config.go

@@ -79,7 +79,6 @@ type RunnerConfig struct {
 	DropCachesPath     string            `yaml:"drop_caches_path,omitempty" mapstructure:"drop_caches_path"`
 	CPUSysfsPath       string            `yaml:"cpu_sysfs_path,omitempty" mapstructure:"cpu_sysfs_path"`
 	GitHubToken        string            `yaml:"github_token,omitempty" mapstructure:"github_token"`
-	Metadata           MetadataConfig    `yaml:"metadata,omitempty" mapstructure:"metadata"`
 	Benchmark          BenchmarkConfig   `yaml:"benchmark" mapstructure:"benchmark"`
 	Client             ClientConfig      `yaml:"client" mapstructure:"client"`
 	Instances          []ClientInstance  `yaml:"instances" mapstructure:"instances"`
@@ -599,6 +598,7 @@ type ClientDefaults struct {
 	PostTestSleepDuration            string                            `yaml:"post_test_sleep_duration,omitempty" mapstructure:"post_test_sleep_duration"`
 	BootstrapFCU                     *BootstrapFCUConfig               `yaml:"bootstrap_fcu,omitempty" mapstructure:"bootstrap_fcu"`
 	CheckpointRestoreStrategyOptions *CheckpointRestoreStrategyOptions `yaml:"checkpoint_restore_strategy_options,omitempty" mapstructure:"checkpoint_restore_strategy_options"`
+	Metadata                         MetadataConfig                    `yaml:"metadata,omitempty" mapstructure:"metadata"`
 }
 
 // ClientInstance defines a single client instance to benchmark.
@@ -624,6 +624,7 @@ type ClientInstance struct {
 	PostTestSleepDuration            string                            `yaml:"post_test_sleep_duration,omitempty" mapstructure:"post_test_sleep_duration"`
 	BootstrapFCU                     *BootstrapFCUConfig               `yaml:"bootstrap_fcu,omitempty" mapstructure:"bootstrap_fcu"`
 	CheckpointRestoreStrategyOptions *CheckpointRestoreStrategyOptions `yaml:"checkpoint_restore_strategy_options,omitempty" mapstructure:"checkpoint_restore_strategy_options"`
+	Metadata                         MetadataConfig                    `yaml:"metadata,omitempty" mapstructure:"metadata"`
 }
 
 // expandEnvWithDefaults is a mapping function for os.Expand that supports
@@ -1458,6 +1459,29 @@ func (c *Config) GetCheckpointRestartContainer(instance *ClientInstance) bool {
 	return opts.RestartContainer
 }
 
+// GetMetadataLabels returns the merged metadata labels for an instance.
+// Client-level metadata labels serve as defaults; instance-level labels
+// override specific keys.
+func (c *Config) GetMetadataLabels(instance *ClientInstance) map[string]string {
+	defaults := c.Runner.Client.Config.Metadata.Labels
+	overrides := instance.Metadata.Labels
+
+	if len(defaults) == 0 && len(overrides) == 0 {
+		return nil
+	}
+
+	merged := make(map[string]string, len(defaults)+len(overrides))
+	for k, v := range defaults {
+		merged[k] = v
+	}
+
+	for k, v := range overrides {
+		merged[k] = v
+	}
+
+	return merged
+}
+
 // ParseByteSize parses a human-readable byte size string into bytes.
 // Uses the same format as resource_limits.memory (Docker go-units):
 // e.g. "32g", "512m", "1024k", "1073741824".

pkg/config/config_test.go

@@ -1195,14 +1195,14 @@ func TestLoad_MetadataLabels(t *testing.T) {
 	t.Run("parses labels from yaml", func(t *testing.T) {
 		configContent := `
 runner:
-  metadata:
-    labels:
-      env: production
-      team: platform
   client:
     config:
       genesis:
         geth: http://example.com/genesis.json
+      metadata:
+        labels:
+          env: production
+          team: platform
   instances:
     - id: test-instance
       client: geth
@@ -1214,9 +1214,9 @@ runner:
 		cfg, err := Load(configPath)
 		require.NoError(t, err)
 
-		require.Len(t, cfg.Runner.Metadata.Labels, 2)
-		assert.Equal(t, "production", cfg.Runner.Metadata.Labels["env"])
-		assert.Equal(t, "platform", cfg.Runner.Metadata.Labels["team"])
+		require.Len(t, cfg.Runner.Client.Config.Metadata.Labels, 2)
+		assert.Equal(t, "production", cfg.Runner.Client.Config.Metadata.Labels["env"])
+		assert.Equal(t, "platform", cfg.Runner.Client.Config.Metadata.Labels["team"])
 	})
 
 	t.Run("empty metadata produces no errors", func(t *testing.T) {
@@ -1237,18 +1237,18 @@ runner:
 		cfg, err := Load(configPath)
 		require.NoError(t, err)
 
-		assert.Nil(t, cfg.Runner.Metadata.Labels)
+		assert.Nil(t, cfg.Runner.Client.Config.Metadata.Labels)
 	})
 
 	t.Run("empty labels map produces no errors", func(t *testing.T) {
 		configContent := `
 runner:
-  metadata:
-    labels: {}
   client:
     config:
       genesis:
         geth: http://example.com/genesis.json
+      metadata:
+        labels: {}
   instances:
     - id: test-instance
       client: geth
@@ -1260,10 +1260,66 @@ runner:
 		cfg, err := Load(configPath)
 		require.NoError(t, err)
 
-		assert.Empty(t, cfg.Runner.Metadata.Labels)
+		assert.Empty(t, cfg.Runner.Client.Config.Metadata.Labels)
 	})
 }
 
+func TestGetMetadataLabels(t *testing.T) {
+	tests := []struct {
+		name           string
+		clientLabels   map[string]string
+		instanceLabels map[string]string
+		expected       map[string]string
+	}{
+		{
+			name:     "no labels at either level",
+			expected: nil,
+		},
+		{
+			name:         "only client-level labels",
+			clientLabels: map[string]string{"env": "production", "team": "platform"},
+			expected:     map[string]string{"env": "production", "team": "platform"},
+		},
+		{
+			name:           "only instance-level labels",
+			instanceLabels: map[string]string{"variant": "snap-sync"},
+			expected:       map[string]string{"variant": "snap-sync"},
+		},
+		{
+			name:           "both levels no overlap",
+			clientLabels:   map[string]string{"env": "production"},
+			instanceLabels: map[string]string{"variant": "snap-sync"},
+			expected:       map[string]string{"env": "production", "variant": "snap-sync"},
+		},
+		{
+			name:           "instance overrides client on conflict",
+			clientLabels:   map[string]string{"env": "production", "team": "platform"},
+			instanceLabels: map[string]string{"env": "staging"},
+			expected:       map[string]string{"env": "staging", "team": "platform"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &Config{
+				Runner: RunnerConfig{
+					Client: ClientConfig{
+						Config: ClientDefaults{
+							Metadata: MetadataConfig{Labels: tt.clientLabels},
+						},
+					},
+				},
+			}
+			instance := &ClientInstance{
+				Metadata: MetadataConfig{Labels: tt.instanceLabels},
+			}
+
+			result := cfg.GetMetadataLabels(instance)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
 func TestValidateAPIStorage(t *testing.T) {
 	// Helper to build a Config with API storage and minimal valid fields.
 	makeConfig := func(s3Cfg *APIS3Config) Config {

pkg/executor/index.go

@@ -23,14 +23,15 @@ type Index struct {
 
 // IndexEntry contains summary information for a single benchmark run.
 type IndexEntry struct {
-	RunID             string          `json:"run_id"`
-	Timestamp         int64           `json:"timestamp"`
-	TimestampEnd      int64           `json:"timestamp_end,omitempty"`
-	SuiteHash         string          `json:"suite_hash,omitempty"`
-	Instance          *IndexInstance  `json:"instance"`
-	Tests             *IndexTestStats `json:"tests"`
-	Status            string          `json:"status,omitempty"`
-	TerminationReason string          `json:"termination_reason,omitempty"`
+	RunID             string            `json:"run_id"`
+	Timestamp         int64             `json:"timestamp"`
+	TimestampEnd      int64             `json:"timestamp_end,omitempty"`
+	SuiteHash         string            `json:"suite_hash,omitempty"`
+	Instance          *IndexInstance    `json:"instance"`
+	Tests             *IndexTestStats   `json:"tests"`
+	Status            string            `json:"status,omitempty"`
+	TerminationReason string            `json:"termination_reason,omitempty"`
+	Metadata          map[string]string `json:"metadata,omitempty"`
 }
 
 // IndexInstance contains the client instance information for the index.
@@ -84,6 +85,9 @@ type runConfigJSON struct {
 		Passed int `json:"passed"`
 		Failed int `json:"failed"`
 	} `json:"test_counts,omitempty"`
+	Metadata *struct {
+		Labels map[string]string `json:"labels"`
+	} `json:"metadata,omitempty"`
 }
 
 // GenerateIndex scans the results directory and builds an index from all runs.
@@ -368,7 +372,7 @@ func BuildIndexEntryFromData(
 		testStats.TestsFailed = runConfig.TestCounts.Failed
 	}
 
-	return &IndexEntry{
+	entry := &IndexEntry{
 		RunID:             runID,
 		Timestamp:         runConfig.Timestamp,
 		TimestampEnd:      runConfig.TimestampEnd,
@@ -382,7 +386,13 @@ func BuildIndexEntryFromData(
 			RollbackStrategy: runConfig.Instance.RollbackStrategy,
 		},
 		Tests: testStats,
-	}, nil
+	}
+
+	if runConfig.Metadata != nil && len(runConfig.Metadata.Labels) > 0 {
+		entry.Metadata = runConfig.Metadata.Labels
+	}
+
+	return entry, nil
 }
 
 // WriteIndex writes the index to index.json in the runs subdirectory.