[jira] [Commented] (KAFKA-3480) Autogenerate metrics documentation

["James Cheng (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/KAFKA-3480?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15215294#comment-15215294 ] 

James Cheng commented on KAFKA-3480:
------------------------------------

I think I'd like to work on this, but I'm not what approach you had in mind.

I spoke to [~gwenshap] about it. She said that it would be a large effort to modify all the metrics code to do something similar to ConfigDef.java (constants containing names and descriptions), one reason being that the metrics code is partially split between Yammer Metrics and Kafka Metrics. Another reason I noticed was that some of the existing metrics are constructed via string concatenation.

The idea I had would be to start up an instance of Kafka, and run a JMX poller against it to extract out all the names of the JMX metrics. This autogenerated list would then be cross referenced with a file on disk that has the human-readable descriptions of the various metrics. The both of these together can then be used to generated a nice-looking table that be included in the docs.

This approach would quickly get us an auto-generated list of the metrics with partial documentation, and would allow an incremental approach to adding human-readable descriptions. And it would not require large code changes. However, it wouldn't guarantee that we have documentation for *all* metrics, and it wouldn't guarantee that the descriptions stay in sync with the metric names. As we get closer and closer to having complete documentation for all the metrics, we could add a step that would break the build if there were any metrics that did not have descriptions.

Would something like that be useful? What are some other approaches?


> Autogenerate metrics documentation
> ----------------------------------
>
>                 Key: KAFKA-3480
>                 URL: https://issues.apache.org/jira/browse/KAFKA-3480
>             Project: Kafka
>          Issue Type: Improvement
>            Reporter: Jason Gustafson
>
> Metrics documentation is done manually, which means it's hard to keep it current. It would be nice to have automatic generation of this documentation as we have for configs.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)