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	namespace Wikimedia\Stats\Metrics;
21
22	use Psr\Log\LoggerInterface;
23	use Wikimedia\Stats\Sample;
24
25	/**
26	* Metric Interface
27	*
28	* @author Cole White
29	* @since 1.41
30	*/
31	interface MetricInterface {
32
33	public function __construct( BaseMetricInterface $baseMetric, LoggerInterface $logger );
34
35	/** @return string */
36	public function getName(): string;
37
38	/** @return string */
39	public function getComponent(): string;
40
41	/** @return float */
42	public function getSampleRate(): float;
43
44	/** @return string */
45	public function getTypeIndicator(): string;
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	* Sets sample rate on a new metric instance.
63	*
64	* @param float $sampleRate
65	* @return self|NullMetric
66	*/
67	public function setSampleRate( float $sampleRate );
68
69	/**
70	* Returns the list of defined label keys.
71	*
72	* @return string[]
73	*/
74	public function getLabelKeys(): array;
75
76	/**
77	* Adds a label $key with $value.
78	* Note that the order in which labels are added is significant for StatsD output.
79	*
80	* Example:
81	* ```php
82	* $statsFactory->getCounter( 'testMetric_total' )
83	*     ->setLabel( 'first', 'foo' )
84	*     ->setLabel( 'second', 'bar' )
85	*     ->increment();
86	* ```
87	* statsd: "mediawiki.testMetric_total.foo.bar"
88	* prometheus: "mediawiki_testMetric_total{ first='foo', second='bar' }
89	*
90	* @param string $key
91	* @param string $value
92	* @return self|NullMetric
93	*/
94	public function setLabel( string $key, string $value );
95
96	/**
97	* Convenience function to set a number of labels at once.
98	* @see ::setLabel
99	* @param array<string,string> $labels
100	* @return self|NullMetric
101	*/
102	public function setLabels( array $labels );
103
104	/**
105	* Copies metric operation to StatsD at provided namespace.
106	*
107	* Takes a namespace or multiple namespaces.
108	*
109	* @param string|string[] $statsdNamespaces
110	* @return self|NullMetric
111	*/
112	public function copyToStatsdAt( $statsdNamespaces );
113
114	/**
115	* Returns metric with cleared labels.
116	*
117	* @return self|NullMetric
118	*/
119	public function fresh();
120
121	/**
122	* Indicates the metric instance is used in a Histogram
123	*
124	* @return bool
125	*/
126	public function isHistogram(): bool;
127	}