On Wed, Feb 11, 2015 at 6:02 PM, Gregory Farnum <greg@xxxxxxxxxxx> wrote: > On Wed, Feb 11, 2015 at 9:33 AM, Alyona Kiseleva > <akiselyova@xxxxxxxxxxxx> wrote: >> Hi, >> I would like to propose something. >> >> There are a lot of perf counters in different places in code, but the most >> of them are undocumented. I found only one commented counter in OSD.cc code, >> but not for all metrics. Name of counter is not very clear as it's >> description, sometimes isn't at all. >> >> So, I have an idea, that it would be great, if perf schema would contain not >> only the counter type, but some description too. It can be added in >> PerfCountersBuilder methods - at first as optional parameter with empty >> string by default, later, may be, as required parameter. This short >> description could be saved in perf_counter_data_any_d struct together with >> other counter properties and appear in perf schema as the second counter >> property. There will be lots of counters that aren't usefully describable in a single sentence. That doesn't excuse them from being documented, but we should be careful to avoid generating useless tautological strings like num_strays_delayed -> "Number of strays currently that are currently delayed". For lots of things, an understandable definition will require some level of introduction of terms and concepts -- in my example, what's a stray? what does it mean for it to be delayed? While we shouldn't hold up the descriptions waiting for documentation that explains all the needed concepts, we should think about how that will fit together. Perhaps, rather than having a single string in the code, we should look to create a separate metadata file that allows richer RST docs for each setting, and verify that all settings are described during the docs build (i.e. a gitbuilder fail will tell us if someone added a setting without the associated documentation). That way, the short perfcounter descriptions could include hyperlinks to related concepts elsewhere in the docs. John -- To unsubscribe from this list: send the line "unsubscribe ceph-devel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
