Stats: add static labels feature

Enables configuring static labels that apply to all metrics created by the StatsFactory instance.

Bug: T240685
Change-Id: I43baf6b84c5d17b69c851aaa1cc0955f6ded79b9

4 files changed, 51 insertions, 5 deletions

diff --git a/includes/libs/Stats/Exceptions/IllegalOperationException.php b/includes/libs/Stats/Exceptions/IllegalOperationException.php
index 95ae79890263..85c817f53aee 100644
--- a/includes/libs/Stats/Exceptions/IllegalOperationException.php
+++ b/includes/libs/Stats/Exceptions/IllegalOperationException.php
@@ -22,10 +22,7 @@ namespace Wikimedia\Stats\Exceptions;
 use RuntimeException;
 
 /**
- * IllegalOperationException
- *
- * This exception is raised when StatsFactory or Metric gets an associative
- * array as configuration that it cannot use to properly instantiate a Metric.
+ * Thrown when an unresolvable configuration condition has been requested.
  *
  * @author Cole White
  * @since 1.41
diff --git a/includes/libs/Stats/Metrics/BaseMetric.php b/includes/libs/Stats/Metrics/BaseMetric.php
index 3e60eb6db6ea..3f31ed58965c 100644
--- a/includes/libs/Stats/Metrics/BaseMetric.php
+++ b/includes/libs/Stats/Metrics/BaseMetric.php
@@ -98,6 +98,13 @@ class BaseMetric implements BaseMetricInterface {
 	}
 
 	/** @inheritDoc */
+	public function withStaticLabels( array $labelKeys, array $labelValues ): BaseMetricInterface {
+		$this->labelKeys = $labelKeys;
+		$this->staticLabels = array_combine( $labelKeys, $labelValues );
+		return $this;
+	}
+
+	/** @inheritDoc */
 	public function addLabel( string $key, string $value ): void {
 		StatsUtils::validateLabelValue( $value );
 		$key = StatsUtils::normalizeString( $key );
@@ -113,6 +120,11 @@ class BaseMetric implements BaseMetricInterface {
 	 * @return void
 	 */
 	private function addLabelKey( string $key ): void {
+		if ( array_key_exists( $key, $this->staticLabels ) ) {
+			throw new IllegalOperationException(
+				"Stats: Cannot add a label already declared as a static label for '" . $this->name . "'"
+			);
+		}
 		if ( in_array( $key, $this->labelKeys, true ) ) {
 			return;  // key already exists
 		}
diff --git a/includes/libs/Stats/Metrics/BaseMetricInterface.php b/includes/libs/Stats/Metrics/BaseMetricInterface.php
index 7deb18e4c0c9..01c11442d4db 100644
--- a/includes/libs/Stats/Metrics/BaseMetricInterface.php
+++ b/includes/libs/Stats/Metrics/BaseMetricInterface.php
@@ -76,6 +76,15 @@ interface BaseMetricInterface {
 	public function getName(): string;
 
 	/**
+	 * Configures the metric with static labels.
+	 *
+	 * @param string[] $labelKeys
+	 * @param string[] $labelValues
+	 * @return BaseMetricInterface
+	 */
+	public function withStaticLabels( array $labelKeys, array $labelValues ): BaseMetricInterface;
+
+	/**
 	 * Add a label with key => value
 	 *
 	 * @param string $key
diff --git a/includes/libs/Stats/StatsFactory.php b/includes/libs/Stats/StatsFactory.php
index f7104048a1f1..a6ebef45b047 100644
--- a/includes/libs/Stats/StatsFactory.php
+++ b/includes/libs/Stats/StatsFactory.php
@@ -25,6 +25,7 @@ use InvalidArgumentException;
 use Psr\Log\LoggerInterface;
 use TypeError;
 use Wikimedia\Stats\Emitters\EmitterInterface;
+use Wikimedia\Stats\Exceptions\IllegalOperationException;
 use Wikimedia\Stats\Exceptions\InvalidConfigurationException;
 use Wikimedia\Stats\Metrics\BaseMetric;
 use Wikimedia\Stats\Metrics\CounterMetric;
@@ -47,6 +48,12 @@ class StatsFactory {
 	/** @var string */
 	private string $component;
 
+	/** @var string[] */
+	private array $staticLabelKeys = [];
+
+	/** @var string[] */
+	private array $staticLabelValues = [];
+
 	/** @var StatsCache */
 	private StatsCache $cache;
 
@@ -89,6 +96,24 @@ class StatsFactory {
 	}
 
 	/**
+	 * Adds a label key-value pair to all metrics created by this StatsFactory instance.
+	 *
+	 * @param string $key
+	 * @param string $value
+	 * @return $this
+	 */
+	public function withStaticLabel( string $key, string $value ): StatsFactory {
+		if ( count( $this->cache->getAllMetrics() ) > 0 ) {
+			throw new IllegalOperationException( 'Stats: cannot set static labels when metrics are in the cache.' );
+		}
+		$key = StatsUtils::normalizeString( $key );
+		StatsUtils::validateLabelKey( $key );
+		$this->staticLabelKeys[] = $key;
+		$this->staticLabelValues[] = StatsUtils::normalizeString( $value );
+		return $this;
+	}
+
+	/**
 	 * Makes a new CounterMetric or fetches one from cache.
 	 *
 	 * If a collision occurs, returns a NullMetric to suppress exceptions.
@@ -153,7 +178,10 @@ class StatsFactory {
 		}
 		if ( $metric === null ) {
 			$baseMetric = new BaseMetric( $this->component, $name );
-			$metric = new $className( $baseMetric, $this->logger );
+			$metric = new $className(
+				$baseMetric->withStaticLabels( $this->staticLabelKeys, $this->staticLabelValues ),
+				$this->logger
+			);
 			$this->cache->set( $this->component, $name, $metric );
 		}
 		return $metric->fresh();