StatsUtils.php

Go to the documentation of this file.

<?php
declare( strict_types=1 );
 
namespace Wikimedia\Stats;
 
use InvalidArgumentException;
use Wikimedia\Stats\Exceptions\InvalidConfigurationException;
 
class StatsUtils {
 
    public const RE_VALID_NAME_AND_LABEL_NAME = "/^[a-zA-Z_][a-zA-Z0-9_]*$/";
    public const DEFAULT_SAMPLE_RATE = 1.0;
 
    public static function validateNewSampleRate( float $newSampleRate ): void {
        if ( $newSampleRate < 0.0 || $newSampleRate > 1.0 ) {
            throw new InvalidArgumentException( "Sample rate can only be between 0.0 and 1.0. Got: " . $newSampleRate );
        }
    }
 
    public static function getFilteredSamples( float $sampleRate, array $samples ): array {
        if ( $sampleRate === 1.0 ) {
            return $samples;
        }
        $output = [];
        $randMax = mt_getrandmax();
        foreach ( $samples as $sample ) {
            if ( mt_rand() / $randMax < $sampleRate ) {
                $output[] = $sample;
            }
        }
        return $output;
    }
 
    public static function validateMetricName( string $name ) {
        if ( $name === "" ) {
            throw new InvalidArgumentException( "Stats: Metric name cannot be empty." );
        }
        if ( !preg_match( self::RE_VALID_NAME_AND_LABEL_NAME, $name ) ) {
            throw new InvalidConfigurationException( "Invalid metric name: '" . $name . "'" );
        }
    }
 
    public static function validateLabelKey( string $key ) {
        if ( $key === "" ) {
            throw new InvalidArgumentException( "Stats: Label key cannot be empty." );
        }
        if ( !preg_match( self::RE_VALID_NAME_AND_LABEL_NAME, $key ) ) {
            throw new InvalidConfigurationException( "Invalid label key: '" . $key . "'" );
        }
    }
 
    public static function validateLabelValue( string $value ) {
        if ( $value === "" ) {
            throw new InvalidArgumentException( "Stats: Label value cannot be empty." );
        }
    }
 
    public static function normalizeArray( array $entities ): array {
        $normalizedEntities = [];
        foreach ( $entities as $entity ) {
            $normalizedEntities[] = self::normalizeString( $entity );
        }
        return $normalizedEntities;
    }
 
    public static function normalizeString( string $entity ): string {
        $entity = preg_replace( '/[^a-zA-Z0-9]+/', '_', $entity );
        return trim( $entity, '_' );
    }
 
    private const E12 = [
        1.0, 1.2, 1.5, 1.8, 2.2, 2.7, 3.3, 3.9, 4.7, 5.6, 6.8, 8.2, 10.0
    ];
 
    public static function makeBucketsFromMean( float $mean, int $skip ): array {
        // assert $mean > 0 and $skip > 0
        if ( $mean <= 0 ) {
            throw new InvalidArgumentException( 'mean must be positive' );
        }
        if ( $skip < 1 ) {
            throw new InvalidArgumentException( 'skip must be at least 1' );
        }
        // Find the appropriate starting location in the E12 series.
        $pos = (int)round( log10( $mean ) * 12 );
        // Further quantize $pos according to $skip, so changes in $mean
        // don't shift all the buckets
        $pos -= ( $pos % $skip );
        // Compute buckets around the quantized starting position
        // By using the E12 series and powers of ten our cutoffs will
        // be compact (not too many digits) and consistent.
        return array_map( static function ( int $x ) use ( $pos, $skip ) {
            $y = $pos + ( $x * $skip );
            $rem = $y % 12;
            if ( $rem < 0 ) {
                $rem += 12;
            }
            $decade = intdiv( $y - $rem, 12 ); // floor($y/12)
            // Use an explicit round() here to ensure float math doesn't create
            // extra tiny variances.
            return round( ( 10 ** $decade ) * self::E12[$rem], 1 - $decade );
        }, [
            // 9 buckets, centered around the (quantized) mean
            -4, -3, -2, -1, 0, 1, 2, 3, 4
        ] );
    }
}