1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	* @file
18	*/
19
20	declare( strict_types=1 );
21
22	namespace Wikimedia\Stats\Metrics;
23
24	use Wikimedia\Stats\IBufferingStatsdDataFactory;
25	use Wikimedia\Stats\Sample;
26
27	/**
28	* Base Metric Interface
29	*
30	* Interface for defining a Base Metric.
31	*
32	* @author Cole White
33	* @since 1.41
34	*/
35	interface BaseMetricInterface {
36
37	/**
38	* @param string $component The component this metric will track.
39	* @param string $name The Metric Name.
40	*/
41	public function __construct( string $component, string $name );
42
43	/**
44	* Records a Metric Sample.
45	*
46	* @param Sample $sample
47	* @return void
48	*/
49	public function addSample( Sample $sample ): void;
50
51	/**
52	* Returns the configured sample rate.
53	*
54	* @return float
55	*/
56	public function getSampleRate(): float;
57
58	public function setSampleRate( float $sampleRate ): void;
59
60	/**
61	* Returns subset of samples corresponding to sample rate setting.
62	*
63	* @return Sample[]
64	*/
65	public function getSamples(): array;
66
67	/**
68	* Returns a count of samples recorded by the metric.
69	*
70	* @return int
71	*/
72	public function getSampleCount(): int;
73
74	/**
75	* Returns the Metric Name
76	*
77	* @return string
78	*/
79	public function getName(): string;
80
81	/**
82	* Add a label with key => value.
83	* Note that the order in which labels are added is significant for StatsD output.
84	*
85	* Example:
86	* ```php
87	* $statsFactory->withComponent( 'demo' )
88	*     ->getCounter( 'testMetric_total' )
89	*     ->setLabel( 'first', 'foo' )
90	*     ->setLabel( 'second', 'bar' )
91	*     ->setLabel( 'third', 'baz' )
92	*     ->increment();
93	* ```
94	* statsd: "mediawiki.demo.testMetric_total.foo.bar.baz"
95	* prometheus: "mediawiki_demo_testMetric_total{first='foo',second='bar',third='baz'}
96	*
97	* @param string $key
98	* @param string $value
99	* @return void
100	*/
101	public function addLabel( string $key, string $value ): void;
102
103	/**
104	* Returns array of label keys.
105	*
106	* @return string[]
107	*/
108	public function getLabelKeys(): array;
109
110	/**
111	* Returns an array of label values in the order of label keys.
112	*
113	* @return string[]
114	*/
115	public function getLabelValues(): array;
116
117	/**
118	* Returns the Metric Component
119	*
120	* @return string
121	*/
122	public function getComponent(): string;
123
124	/**
125	* Clears the working labels.
126	*
127	* @return void
128	*/
129	public function clearLabels(): void;
130
131	/**
132	* Gets StatsD Data Factory instance or null.
133	*/
134	public function getStatsdDataFactory();
135
136	/**
137	* Validates and sets legacy StatsD namespaces.
138	*
139	* @param string|string[] $statsdNamespaces
140	* @return void
141	*/
142	public function setStatsdNamespaces( $statsdNamespaces ): void;
143
144	/**
145	* Returns the configured legacy StatsD namespaces.
146	*
147	* @return string[]
148	*/
149	public function getStatsdNamespaces(): array;
150
151	/**
152	* StatsD Data Factory instance to copy metrics to.
153	*
154	* @param IBufferingStatsdDataFactory|null $statsdDataFactory
155	*
156	* @return self
157	*/
158	public function withStatsdDataFactory( ?IBufferingStatsdDataFactory $statsdDataFactory );
159	}