MediaWiki master
Static Public Member Functions | Public Attributes | List of all members
Wikimedia\Stats\StatsUtils Class Reference

Functionality common to all metric types. More...

Static Public Member Functions

static getFilteredSamples (float $sampleRate, array $samples)
 Returns a subset of samples based on configured sample rate.
 
static makeBucketsFromMean (float $mean, int $skip)
 Make a set of HistogramMetric buckets from a mean and skip value.
 
static normalizeArray (array $entities)
 Normalize an array of strings.
 
static normalizeString (string $entity)
 Normalize strings to a metrics-compatible format.
 
static validateLabelKey (string $key)
 Determines if provided string is a valid label key.
 
static validateLabelValue (string $value)
 
static validateMetricName (string $name)
 Determines if provided string is a valid name.
 
static validateNewSampleRate (float $newSampleRate)
 Validates the new sample rate.
 

Public Attributes

const DEFAULT_SAMPLE_RATE = 1.0
 
const RE_VALID_NAME_AND_LABEL_NAME = "/^[a-zA-Z_][a-zA-Z0-9_]*$/"
 

Detailed Description

Functionality common to all metric types.

Author
Cole White
Since
1.38

Definition at line 33 of file StatsUtils.php.

Member Function Documentation

◆ getFilteredSamples()

static Wikimedia\Stats\StatsUtils::getFilteredSamples ( float $sampleRate,
array $samples )
static

Returns a subset of samples based on configured sample rate.

Parameters
float$sampleRate
array$samples
Returns
array

Definition at line 57 of file StatsUtils.php.

◆ makeBucketsFromMean()

static Wikimedia\Stats\StatsUtils::makeBucketsFromMean ( float $mean,
int $skip )
static

Make a set of HistogramMetric buckets from a mean and skip value.

Beware: this is for storing non-time data in histograms, like byte sizes, or time data outside of the range [5ms, 60s].

Avoid changing the buckets once a metric has been deployed, as it may generate excessive churn.

That said, this method quantizes the mean so modest shifts should maintain most buckets, and multiplying or dividing the "skip" by a small factor should also maintain commonality.

The range of buckets for typical skips is roughly: 

$skip = 1: [0.5*mean, 2*mean]
$skip = 2: [0.2*mean, 5*mean]
$skip = 3: [0.1*mean, 10*mean]
$skip = 4: [0.05*mean, 20*mean]
$skip = 5: [0.02*mean, 50*mean]
$skip = 6: [0.01*mean, 100*mean]
...
$skip = 12: [0.001*mean, 10000*mean]
Parameters
float$meanThe mean value expected.
int$skipThe range of values expected. With $skip = 1, each bucket will be greater than the last by a factor of 10^(1/12), which means 12 buckets per decade of range. This is the E12 series. With $skip = 2 we take every other bucket (6 buckets per decade), $skip = 3 means every third bucket (4 buckets per decade), $skip = 4 means every fourth bucket (3 buckets per decade), etc. The ::getTiming() metric effectively uses $skip = 4, which corresponds roughly to the usual [0.1, 0.2, 0.5, 1] progression, and that is the default value. As mentioned above, take great care when changing $skip on metrics already in production.
Returns
float[] An array of 9 buckets, centered around the mean

Definition at line 189 of file StatsUtils.php.

◆ normalizeArray()

static Wikimedia\Stats\StatsUtils::normalizeArray ( array $entities)
static

Normalize an array of strings.

Parameters
string[]$entities
Returns
string[]

Definition at line 117 of file StatsUtils.php.

◆ normalizeString()

static Wikimedia\Stats\StatsUtils::normalizeString ( string $entity)
static

Normalize strings to a metrics-compatible format.

Replace all other non-alphanumeric characters with an underscore. Trim leading or trailing underscores.

Note: We are not using /i (case-insensitive flag) or \d (digit character class escape) here because their behavior changes with respect to locale settings.

Parameters
string$entity
Returns
string

Definition at line 138 of file StatsUtils.php.

Referenced by Wikimedia\Stats\StatsFactory\__construct(), and Wikimedia\Stats\Metrics\BaseMetric\__construct().

◆ validateLabelKey()

static Wikimedia\Stats\StatsUtils::validateLabelKey ( string $key)
static

Determines if provided string is a valid label key.

Parameters
string$key
Returns
void
Exceptions
InvalidArgumentException
InvalidConfigurationException

Definition at line 96 of file StatsUtils.php.

◆ validateLabelValue()

static Wikimedia\Stats\StatsUtils::validateLabelValue ( string $value)
static

Definition at line 105 of file StatsUtils.php.

◆ validateMetricName()

static Wikimedia\Stats\StatsUtils::validateMetricName ( string $name)
static

Determines if provided string is a valid name.

Parameters
string$name
Returns
void
Exceptions
InvalidArgumentException
InvalidConfigurationException

Definition at line 79 of file StatsUtils.php.

◆ validateNewSampleRate()

static Wikimedia\Stats\StatsUtils::validateNewSampleRate ( float $newSampleRate)
static

Validates the new sample rate.

Throws InvalidArgumentException if provided an invalid rate.

Parameters
float$newSampleRate
Exceptions
InvalidArgumentException

Definition at line 44 of file StatsUtils.php.

Member Data Documentation

◆ DEFAULT_SAMPLE_RATE

const Wikimedia\Stats\StatsUtils::DEFAULT_SAMPLE_RATE = 1.0

Definition at line 36 of file StatsUtils.php.

◆ RE_VALID_NAME_AND_LABEL_NAME

const Wikimedia\Stats\StatsUtils::RE_VALID_NAME_AND_LABEL_NAME = "/^[a-zA-Z_][a-zA-Z0-9_]*$/"

Definition at line 35 of file StatsUtils.php.

The documentation for this class was generated from the following file: