I'd like to propose we start documenting in some way the various statsd metrics we output from MediaWiki core.
Doing so would improve developer experience in various ways:
- Avoid conflicts with existing keys by being able to see them in one place.
- Easily figure out when rendering a metric (e.g. in Graphite) from which place (or places) it is generated from.
- Explicitly document the (intended) unit and further meaning of a metric's value.
I don't have a preference for how we do this, but a few ideas follow:
- Text file, somewhat akin to docs/hooks.txt we could have a docs/stats.txt or some such.
- Possibly integrated somehow with the existing Doxygen documentation, e.g. by writing a script that will generate a file using @page to make Doxygen add a page to https://doc.wikimedia.org/mediawiki-core/master/php/pages.html (similar to the one we use for the doc main page).