sijie commented on a change in pull request #1786: BP-36: Stats documentation annotation URL: https://github.com/apache/bookkeeper/pull/1786#discussion_r231972932
########## File path: site/bps/BP-36-stats-documentation-annotation.md ########## @@ -0,0 +1,157 @@ +--- +title: "BP-36: Stats documentation annotation" +issue: https://github.com/apache/bookkeeper/<issue-number> +state: "Under Discussion" +release: "4.9.0" +--- + +### Motivation + +A common ask from people using bookkeeper is how they can monitor bookies and bookkeeper clients, what kind of metrics that bookkeeper exposes +and what are the important metrics. Currently bookkeeper doesn't provide any metrics page for guiding people on monitoring bookkeeper services. + +In order to help people on this, we need to provide a few documentation pages about metrics. However if we just write such pages, those pages +can quickly get out-of-dated when code is changed. The proposal here is to seek a programming way for generating metrics related pages. + +### Public Interfaces + +Introduced a `StatsDoc` annotation. + +```bash +/** + * Documenting the stats. + */ +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface StatsDoc { + + /** + * The name of the category to group stats together. + * + * @return name of the stats category. + */ + String category() default ""; + + /** + * The scope of this stats. + * + * @return scope of this stats + */ + String scope() default ""; + + /** + * The name of this stats + * + * @return name of this stats + */ + String name(); + + /** + * The help message of this stats + * + * @return help message of this stats + */ + String help(); + + /** + * The parent metric name. + * + * <p>It can used for analyzing the relationships + * between the metrics, especially for the latency metrics. + * + * @return the parent metric name + */ + default String parent() { return ""; } + + /** + * The metric name of an operation that happens + * after the operation of this metric. + * + * <p>similar as {@link #parent()}, it can be used for analyzing + * the dependencies between metrics. + * + * @return the metric name of an operation that happens after the operation of this metric. + */ + default String happenAfter() { return ""; } Review comment: fixed ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
