1	<?php
2	/**
3	* @license GPL-2.0-or-later
4	* @file
5	*/
6
7	declare( strict_types=1 );
8
9	namespace Wikimedia\Stats\Metrics;
10
11	use Wikimedia\Stats\IBufferingStatsdDataFactory;
12	use Wikimedia\Stats\Sample;
13
14	/**
15	* Base Metric Interface
16	*
17	* Interface for defining a Base Metric.
18	*
19	* @author Cole White
20	* @since 1.41
21	*/
22	interface BaseMetricInterface {
23
24	/**
25	* @param string $component The component this metric will track.
26	* @param string $name The Metric Name.
27	*/
28	public function __construct( string $component, string $name );
29
30	/**
31	* Records a Metric Sample.
32	*
33	* @param Sample $sample
34	* @return void
35	*/
36	public function addSample( Sample $sample ): void;
37
38	/**
39	* Returns the configured sample rate.
40	*
41	* @return float
42	*/
43	public function getSampleRate(): float;
44
45	public function setSampleRate( float $sampleRate ): void;
46
47	/**
48	* Returns subset of samples corresponding to sample rate setting.
49	*
50	* @return Sample[]
51	*/
52	public function getSamples(): array;
53
54	/**
55	* Returns a count of samples recorded by the metric.
56	*
57	* @return int
58	*/
59	public function getSampleCount(): int;
60
61	/**
62	* Returns the Metric Name
63	*
64	* @return string
65	*/
66	public function getName(): string;
67
68	/**
69	* Add a label with key => value.
70	* Note that the order in which labels are added is significant for StatsD output.
71	*
72	* Example:
73	* ```php
74	* $statsFactory->withComponent( 'demo' )
75	*     ->getCounter( 'testMetric_total' )
76	*     ->setLabel( 'first', 'foo' )
77	*     ->setLabel( 'second', 'bar' )
78	*     ->setLabel( 'third', 'baz' )
79	*     ->increment();
80	* ```
81	* statsd: "mediawiki.demo.testMetric_total.foo.bar.baz"
82	* prometheus: "mediawiki_demo_testMetric_total{first='foo',second='bar',third='baz'}
83	*
84	* @param string $key
85	* @param string $value
86	* @return void
87	*/
88	public function addLabel( string $key, string $value ): void;
89
90	/**
91	* Returns the defined labels as an associative array.
92	*
93	* @return array<string,string>
94	*/
95	public function getLabels(): array;
96
97	/**
98	* Returns array of label keys.
99	*
100	* @return string[]
101	*/
102	public function getLabelKeys(): array;
103
104	/**
105	* Returns an array of label values in the order of label keys.
106	*
107	* @return string[]
108	*/
109	public function getLabelValues(): array;
110
111	/**
112	* Returns the Metric Component
113	*
114	* @return string
115	*/
116	public function getComponent(): string;
117
118	/**
119	* Clears the working labels.
120	*
121	* @return void
122	*/
123	public function clearLabels(): void;
124
125	/**
126	* Gets StatsD Data Factory instance or null.
127	*/
128	public function getStatsdDataFactory();
129
130	/**
131	* Validates and sets legacy StatsD namespaces.
132	*
133	* @param string|string[] $statsdNamespaces
134	* @return void
135	*/
136	public function setStatsdNamespaces( $statsdNamespaces ): void;
137
138	/**
139	* Returns the configured legacy StatsD namespaces.
140	*
141	* @return string[]
142	*/
143	public function getStatsdNamespaces(): array;
144
145	/**
146	* StatsD Data Factory instance to copy metrics to.
147	*
148	* @param IBufferingStatsdDataFactory|null $statsdDataFactory
149	*
150	* @return self
151	*/
152	public function withStatsdDataFactory( ?IBufferingStatsdDataFactory $statsdDataFactory );
153	}