[
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)
