Page MenuHomePhabricator

Document MediaWiki statsd metrics
Open, Needs TriagePublic

Description

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:

  1. Text file, somewhat akin to docs/hooks.txt we could have a docs/stats.txt or some such.
  2. 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).

Event Timeline

Krinkle created this task.Dec 18 2017, 7:52 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptDec 18 2017, 7:52 PM
Krinkle updated the task description. (Show Details)Dec 18 2017, 7:54 PM
Krinkle added subscribers: bd808, Tgr, Legoktm and 2 others.
Addshore added a subscriber: Addshore.

Option 2 sounds like the nicest idea, keeping them inline will result in them being kept up to date and forgotten less I imagine!

Restricted Application added a project: Documentation. · View Herald TranscriptMay 29 2018, 12:46 PM
Krinkle added a subscriber: apaskulin.EditedJan 4 2020, 7:52 PM

@apaskulin Tagging you as this might be of interest.

The current motivation for this is to improve how we monitor stability of the site and respond to incidents in context of querying data from these metrics in Grafana. The idea being that from a Grafana dashboard (good example, not so good example) one could link to the generated doc page for the relevant metrics so that one may find out what they mean and how they work.

This also relates to T240685 which will likely involve migrating all our statsd metrics over the coming year. That's a good opportunity to work with teams on documenting metrics while at it.

Tgr added a comment.Jan 5 2020, 5:33 AM

I think hooks.txt is an antipattern: there's a clear need for accessing that information in a structured format (hook pages on mediawiki.org should be auto-generated and auto-maintained) and the format makes that unnecessarily hard. If a file is used, it should probably be in YAML and somewhat structured. (Yes, YAML has problems, but for slightly structured documentation it should be good enough.) See also T115388: Convert hooks.txt to YAML [Outreachy microtask].

I agree hooks.txt is an anti pattern.
I would like to see this documentation auto generated as part of the doxygen output.
I'm currently experimenting with improving out automatic doxygen output for wikibase

Addshore moved this task from Unsorted 💣 to Watching 👀 on the User-Addshore board.