EdColeman commented on PR #4518: URL: https://github.com/apache/accumulo/pull/4518#issuecomment-2091413754
This is a general observation - prompted by this PR, but is more general. What it the purpose of the html javadocs table? From the description it is only for mapping old metrics names to new, but there are entries in there now that were not present in the old metrics system. So, it seems to have also become a place to document new metrics. If the table is only for mapping changes, then this PR is correct to not add the new metrics to the table. If the table has morphed into a way to document the available metrics so that they show up in documentation for user reference., then the new metric names and descriptions should be added to the table. Also, the general description of the purpose of the table should be changed to state that it reflects all metrics and includes the mapping from old to new where appropriate. I do not know how we wish to document the metrics - the table is one way, but it is tedious for developers to keep in sync. The docs generated by the table do seem useful, I just don't know if this is the best way, or if we could find something that is easier to maintain. It does seem that we should provide documentation for the metric names. We should also determine how "public" as in public API are the metric names. Similar to Properties, they are internal, so subject to change. But, they are also used externally and changes could cause issues with scripts, or in the case of metrics tracking and post-processing. Currently I have been changing the metric names to be more consistent and hopefully follow a standard convention. Being that the 2.1 metrics are new and have not received a lot of scrutiny, changing non-public name seems like it would have minor impact now, but as the metrics are adopted more widely, changes, additions or deletions should at least be communicated - somehow. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@accumulo.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
