stats: add more detail about label order significance

Adds example code alongside expected output.
Adds test.

Change-Id: I5a73d931757fa9bba25963ddb6ee78040b942a60

3 files changed, 39 insertions, 3 deletions

diff --git a/includes/libs/Stats/Metrics/BaseMetricInterface.php b/includes/libs/Stats/Metrics/BaseMetricInterface.php
index 19efe23aa12c..cc1f31995f58 100644
--- a/includes/libs/Stats/Metrics/BaseMetricInterface.php
+++ b/includes/libs/Stats/Metrics/BaseMetricInterface.php
@@ -94,7 +94,21 @@ interface BaseMetricInterface {
 
 	/**
 	 * Add a label with key => value.
-	 * Note that the order in which labels are added is significant.
+	 * Note that the order in which labels are added is significant for StatsD output.
+	 *
+	 * Static Labels always appear first.
+	 *
+	 * Example:
+	 * ```php
+	 * $statsFactory->withComponent( 'demo' )
+	 *     ->addStaticLabel( 'first', 'foo' )
+	 *     ->addStaticLabel( 'second', 'bar' )
+	 *     ->getCounter( 'testMetric_total' )
+	 *     ->setLabel( 'third', 'baz' )
+	 *     ->increment();
+	 * ```
+	 * statsd: "mediawiki.demo.testMetric_total.foo.bar.baz"
+	 * prometheus: "mediawiki_demo_testMetric_total{first='foo',second='bar',third='baz'}
 	 *
 	 * @param string $key
 	 * @param string $value
diff --git a/includes/libs/Stats/Metrics/MetricInterface.php b/includes/libs/Stats/Metrics/MetricInterface.php
index d343a6cec122..96cc1179d1d8 100644
--- a/includes/libs/Stats/Metrics/MetricInterface.php
+++ b/includes/libs/Stats/Metrics/MetricInterface.php
@@ -78,7 +78,17 @@ interface MetricInterface {
 
 	/**
 	 * Adds a label $key with $value.
-	 * Note that the order in which labels are added is significant.
+	 * Note that the order in which labels are added is significant for StatsD output.
+	 *
+	 * Example:
+	 * ```php
+	 * $statsFactory->getCounter( 'testMetric_total' )
+	 *     ->setLabel( 'first', 'foo' )
+	 *     ->setLabel( 'second', 'bar' )
+	 *     ->increment();
+	 * ```
+	 * statsd: "mediawiki.testMetric_total.foo.bar"
+	 * prometheus: "mediawiki_testMetric_total{ first='foo', second='bar' }
 	 *
 	 * @param string $key
 	 * @param string $value
diff --git a/includes/libs/Stats/StatsFactory.php b/includes/libs/Stats/StatsFactory.php
index 45573584a816..e75246735136 100644
--- a/includes/libs/Stats/StatsFactory.php
+++ b/includes/libs/Stats/StatsFactory.php
@@ -99,7 +99,19 @@ class StatsFactory {
 
 	/**
 	 * Adds a label key-value pair to all metrics created by this StatsFactory instance.
-	 * Note that the order in which labels are added is significant.
+	 * Note that the order in which labels are added is significant for StatsD output.
+	 *
+	 * Example:
+	 * ```php
+	 * $statsFactory->withComponent( 'demo' )
+	 *     ->addStaticLabel( 'first', 'foo' )
+	 *     ->addStaticLabel( 'second', 'bar' )
+	 *     ->getCounter( 'testMetric_total' )
+	 *     ->setLabel( 'third', 'baz' )
+	 *     ->increment();
+	 * ```
+	 * outputs statsd: "mediawiki.demo.testMetric_total.foo.bar.baz"
+	 * outputs prometheus: "mediawiki_demo_testMetric_total{first='foo',second='bar',third='baz'}
 	 *
 	 * @param string $key
 	 * @param string $value