This is the primary interface for validating metrics definitions, caching defined metrics, and returning metric instances from cache if previously defined. More...

Public Member Functions
	__construct (StatsCache $cache, EmitterInterface $emitter, LoggerInterface $logger, ?string $component=null)
	StatsFactory builds, configures, and caches Metrics.

	flush ()
	Send all buffered metrics to the target and destroy the cache.

	getCounter (string $name)
	Makes a new CounterMetric or fetches one from cache.

	getGauge (string $name)
	Makes a new GaugeMetric or fetches one from cache.

	getHistogram (string $name, array $buckets)
	Makes a new HistogramMetric from a list of buckets.

	getTiming (string $name)
	Makes a new TimingMetric or fetches one from cache.

	withComponent (string $component)
	Returns a new StatsFactory instance prefixed by component.

	withStatsdDataFactory (?IBufferingStatsdDataFactory $statsdDataFactory)
	This function existed to support the Graphite->Prometheus transition and is no longer needed.

Static Public Member Functions
static	newNull ()
	Create a no-op StatsFactory.

static	newUnitTestingHelper ()
	Create a stats helper for use in PHPUnit tests.

Detailed Description

This is the primary interface for validating metrics definitions, caching defined metrics, and returning metric instances from cache if previously defined.

Author: Cole White

Since: 1.41

Definition at line 33 of file StatsFactory.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Stats\StatsFactory::__construct	(	StatsCache	$cache,
		EmitterInterface	$emitter,
		LoggerInterface	$logger,
		?string	$component = null )

StatsFactory builds, configures, and caches Metrics.

Definition at line 45 of file StatsFactory.php.

References Wikimedia\Stats\StatsUtils\normalizeString().

Member Function Documentation

◆ flush()

Wikimedia\Stats\StatsFactory::flush ( )

Send all buffered metrics to the target and destroy the cache.

Definition at line 147 of file StatsFactory.php.

Referenced by MediaWiki\MediaWikiEntryPoint\emitBufferedStats().

◆ getCounter()

Wikimedia\Stats\StatsFactory::getCounter ( string $name )

Makes a new CounterMetric or fetches one from cache.

If a collision occurs, returns a NullMetric to suppress exceptions.

Parameters

string $name

Returns: CounterMetric|NullMetric

Definition at line 88 of file StatsFactory.php.

◆ getGauge()

Wikimedia\Stats\StatsFactory::getGauge ( string $name )

Makes a new GaugeMetric or fetches one from cache.

If a collision occurs, returns a NullMetric to suppress exceptions.

Parameters

string $name

Returns: GaugeMetric|NullMetric

Definition at line 100 of file StatsFactory.php.

◆ getHistogram()

Wikimedia\Stats\StatsFactory::getHistogram	(	string	$name,
		array	$buckets )

Makes a new HistogramMetric from a list of buckets.

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 bucket list once a metric has been deployed. When bucket list changes are unavoidable, change the metric name and handle the transition in PromQL.

Parameters

string	$name
	array<int\|float>	$buckets

Returns: HistogramMetric

Definition at line 138 of file StatsFactory.php.

◆ getTiming()

Wikimedia\Stats\StatsFactory::getTiming ( string $name )

Makes a new TimingMetric or fetches one from cache.

The timing data should be in the range [5ms, 60s]; use ::getHistogram() if you need a different range.

This range limitation is a consequence of the recommended setup with prometheus/statsd_exporter (as dogstatsd target) and Prometheus (as time series database), with statsd_exporter::histogram_buckets set to a 5ms-60s range.

If a collision occurs, returns a NullMetric to suppress exceptions.

Parameters

string $name

Returns: TimingMetric|NullMetric

Definition at line 120 of file StatsFactory.php.

◆ newNull()

static Wikimedia\Stats\StatsFactory::newNull ( )

static

Create a no-op StatsFactory.

Use this as the default in a service that takes an optional StatsFactory, or as null implementation in PHPUnit tests, where we don't need to send output to an actual network service.

Since: 1.42

Returns: self

Definition at line 210 of file StatsFactory.php.

◆ newUnitTestingHelper()

static Wikimedia\Stats\StatsFactory::newUnitTestingHelper ( )

static

Create a stats helper for use in PHPUnit tests.

Example:

$statsHelper = StatsFactory::newUnitTestingHelper();
 
$x = new MySubject( $statsHelper->getStatsFactory() );
$x->execute();
 
// Assert full (emitting more is unexpected)
$this->assertSame(
    [
        'example_executions_total:1|c|#foo:bar'
    ],
    $statsHelper->consumeAllFormatted()
);
 
// Assert partially (at least this should be emitted)
$this->assertSame( 1, $statsHelper->count( 'example_executions_total{foo="bar"}' ) );

Since: 1.44

Returns: UnitTestingHelper

Definition at line 240 of file StatsFactory.php.

◆ withComponent()

Wikimedia\Stats\StatsFactory::withComponent ( string $component )

Returns a new StatsFactory instance prefixed by component.

Parameters

string $component

Returns: StatsFactory

Definition at line 65 of file StatsFactory.php.

◆ withStatsdDataFactory()

Wikimedia\Stats\StatsFactory::withStatsdDataFactory ( ?IBufferingStatsdDataFactory $statsdDataFactory )

This function existed to support the Graphite->Prometheus transition and is no longer needed.

Deprecated: since 1.45, see: https://www.mediawiki.org/wiki/Manual:Stats

Definition at line 74 of file StatsFactory.php.

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

includes/libs/Stats/StatsFactory.php

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ flush()

◆ getCounter()

◆ getGauge()

◆ getHistogram()

◆ getTiming()

◆ newNull()

◆ newUnitTestingHelper()

◆ withComponent()

◆ withStatsdDataFactory()