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.
- Inline doc blocks near the (main) code for the metric. Some kind of @ annotation that would be indexed and subsequently generated, aggregated and published to doc.wikimedia.org in some way. This would be somewhat similar in principle to how we document mw.hook events for JavaScript (doc).
- 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).