Manual:Stats

The Stats library (added in MW 1.41) attempts to better define the interface for generating metrics in MediaWiki.

API Docs on doc.wikimedia.org

Global Configuration
The global configuration is in  and can be overridden in.


 * is the output format all metrics will be rendered to.
 * Default  which disables metrics rendering.
 * Supported options are,  ,
 * See  for an up-to-date list of options.
 * is the URI the metrics will be forwarded to. E.g.
 * Default  which disables sending metrics.
 * is the prefix which will be applied to all generated metrics. Required. Default.

Metric Types
The supported metric types are:
 * CounterMetric
 * An only-ever-incrementing counter.
 * Great for tracking rates.
 * Implements  and
 * GaugeMetric
 * A settable value.
 * Implements
 * TimingMetric
 * Observes timing data.
 * When the backend is configured to do so, histograms of timing metrics are generated.
 * Implements,  , and

Requesting a Metric
Use a getter to get a metric from the.

A Simple Example
Let's create a counter for tracking each time a function is called:

StatsD Metric Namespace
Generated StatsD metrics follow a predictable pattern:

For example: would create a metric namespace:

mediawiki.function_calls.my_function.Draft

StatsFactory->withComponent
Returns a new StatsFactory instance with a component field appended to the globally-configured prefix. Intended for components and extensions, this feature isolates metrics generated by the component to their own namespace and enables StatsFactory to accept static labels. For example, a metric  without a component would look like: mediawiki.bar Adding a component  would make the same metric look like: mediawiki.foo.bar

StatsFactory->addStaticLabel
When the StatsFactory instance has a component configured, sets a static label that will be added to all metrics generated by the instance. Intended for components that want to track usage of a single resource across the entire request. For example,  would make all metrics generated by the factory instance set the wiki label to "en", e.g. mediawiki.wiki_language_component.en.metric_name mediawiki.wiki_language_component.en.other_metric

MetricInterface->copyToStatsdAt
When StatsFactory is configured with an IBufferingStatsdDataFactory instance, metrics will be copied to the legacy interface at the provided namespace. Intended to ease the transition to metrics generated by this library. For example:

would send to the : mediawiki.function_calls.my_function.Drafts

and to the mediawiki.legacy_namespace.my_function.calls

MetricInterface->setSampleRate
Configures the metric to emit a subset of samples recorded. Takes a float: 0.0 (sends 0% of samples) to 1.0 (sends 100% of samples). Note: sample rate must be configured prior to recording any samples otherwise an IllegalOperationException will be thrown. This can be encountered inadvertently because metrics pulled from cache may have samples already recorded.

Cardinality
High cardinality metrics present challenges for service operators and consumers of timeseries data. It is recommended to avoid using unbound values in labels or names.

Examples of high-cardinality data include:
 * IDs and UUIDs
 * Usernames
 * IP Addresses
 * User agents

Label Order
For StatsD output, declaration of label order matters. Take care to declare labels in the order you would like them to appear. Label setting order does not matter when the Metric instance is pulled from cache.

Metric Naming
The Observability team recommends following the guidance published by the Prometheus project.

Local Testing in Docker
Add statsd-exporter service to :

Configure :

Scrape the metrics endpoint: $ watch 'curl -s localhost:9112/metrics| grep mediawiki_'

Note that the production statsd-exporter configuration may differ from the default set and make the metrics render differently, especially timing metrics. Please refer to the production statsd-exporter configuration to get the most accurate Prometheus metrics representation.