Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
88.37% covered (warning)
88.37%
38 / 43
60.00% covered (warning)
60.00%
3 / 5
 CRAP
0.00% covered (danger)
0.00%
0 / 1
HistogramMetric
88.37% covered (warning)
88.37%
38 / 43
60.00% covered (warning)
60.00%
3 / 5
 16.40
0.00% covered (danger)
0.00%
0 / 1
 __construct
84.21% covered (warning)
84.21%
16 / 19
0.00% covered (danger)
0.00%
0 / 1
 7.19
 preloadBuckets
100.00% covered (success)
100.00%
5 / 5
100.00% covered (success)
100.00%
1 / 1
 2
 observe
100.00% covered (success)
100.00%
15 / 15
100.00% covered (success)
100.00%
1 / 1
 5
 setLabel
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 fresh
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
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
20declare( strict_types=1 );
21
22namespace Wikimedia\Stats\Metrics;
23
24use InvalidArgumentException;
25use Wikimedia\Stats\StatsFactory;
26
27/**
28 * Histogram Metric Implementation
29 *
30 * Histogram Metrics are a collection of CounterMetric arranged into buckets.
31 *
32 * @author Cole White
33 * @since 1.44
34 */
35class HistogramMetric {
36
37    /** @var int Maximum number of allowed buckets. */
38    private const MAX_BUCKETS = 10;
39
40    private StatsFactory $statsFactory;
41    private string $name;
42    private array $buckets;
43    private array $labels = [];
44
45    public function __construct( StatsFactory $statsFactory, string $name, array $buckets ) {
46        $this->statsFactory = $statsFactory;
47        $this->name = $name;
48        if ( !$buckets ) {
49            throw new InvalidArgumentException( "Stats: ({$name}) Histogram buckets cannot be an empty array." );
50        }
51        $bucketCount = count( $buckets );
52        if ( $bucketCount > self::MAX_BUCKETS ) {
53            throw new InvalidArgumentException(
54                "Stats: ({$name}) Too many buckets defined. Got:{$bucketCount}, Max:" . self::MAX_BUCKETS
55            );
56        }
57        foreach ( $buckets as $bucket ) {
58            if ( !( is_float( $bucket ) || is_int( $bucket ) ) ) {
59                throw new InvalidArgumentException( "Stats: ({$name}) Histogram buckets can only be float or int." );
60            }
61        }
62        $normalizedBuckets = array_unique( $buckets );
63        sort( $normalizedBuckets, SORT_NUMERIC );
64        if ( $buckets !== $normalizedBuckets ) {
65            throw new InvalidArgumentException(
66                "Stats: ({$name}) Histogram buckets must be unique and in order of least to greatest."
67            );
68        }
69        $this->buckets = $buckets;
70    }
71
72    /**
73     * Ensure every bucket has 0 as the first sample so that it is
74     * emitted for the exporter to report.
75     */
76    private function preloadBuckets( CounterMetric $metric ): void {
77        $metric->setBucket( '+Inf' );
78        $metric->incrementBy( 0 );
79        foreach ( $this->buckets as $bucket ) {
80            $metric->setBucket( $bucket );
81            $metric->incrementBy( 0 );
82        }
83    }
84
85    /**
86     * Increments bucket associated with the provided value.
87     */
88    public function observe( float $value ): void {
89        $count = $this->statsFactory->getCounter( "{$this->name}_count" );
90        $bucket = $this->statsFactory->getCounter( "{$this->name}_bucket" );
91        $sum = $this->statsFactory->getCounter( "{$this->name}_sum" );
92
93        foreach ( $this->labels as $k => $v ) {
94            $count->setLabel( $k, $v );
95            $bucket->setLabel( $k, $v );
96            $sum->setLabel( $k, $v );
97        }
98
99        if ( $bucket->getSampleCount() === 0 ) {
100            $this->preloadBuckets( $bucket );
101        }
102
103        $bucket->setBucket( '+Inf' )->increment();
104        foreach ( $this->buckets as $le ) {
105            if ( $value <= $le ) {
106                $bucket->setBucket( $le )->increment();
107            }
108        }
109
110        $count->increment();
111        $sum->incrementBy( $value );
112    }
113
114    /**
115     * Adds a label $key with $value.  No order is respected.
116     *
117     * @return HistogramMetric
118     */
119    public function setLabel( string $key, string $value ): self {
120        // each metric will run its own validation logic
121        $this->labels[$key] = $value;
122        return $this;
123    }
124
125    /**
126     * Returns metric with cleared labels.
127     *
128     * @return HistogramMetric
129     */
130    public function fresh(): self {
131        $this->labels = [];
132        return $this;
133    }
134}