You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@bookkeeper.apache.org by si...@apache.org on 2018/11/13 08:53:38 UTC
[bookkeeper] branch master updated: BP-36: Stats documentation
annotation
This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git
The following commit(s) were added to refs/heads/master by this push:
new 1590ca3 BP-36: Stats documentation annotation
1590ca3 is described below
commit 1590ca3c7056f878cf1d0c6298f277d4cd04315c
Author: Sijie Guo <gu...@gmail.com>
AuthorDate: Tue Nov 13 00:53:33 2018 -0800
BP-36: Stats documentation annotation
Descriptions of the changes in this PR:
*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.
Master Issue: #1785
Reviewers: Sijie Guo <si...@apache.org>, Jia Zhai <None>, Enrico Olivelli <eo...@gmail.com>, Andrey Yegorov <None>
This closes #1786 from sijie/bp_stats_generator
---
site/bps/BP-36-stats-documentation-annotation.md | 157 +++++++++++++++++++++++
site/community/bookkeeper_proposals.md | 5 +-
2 files changed, 160 insertions(+), 2 deletions(-)
diff --git a/site/bps/BP-36-stats-documentation-annotation.md b/site/bps/BP-36-stats-documentation-annotation.md
new file mode 100644
index 0000000..c8905dd
--- /dev/null
+++ b/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: "Accepted"
+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 happensAfter() { return ""; }
+
+
+}
+```
+
+The `StatsDoc` annotation provides a way to annotate metrics we added to bookkeeper.
+
+- category: which category that the metric belongs to. e.g. server, or client.
+- scope: the scope of the metric. e.g. `bookie` scope.
+- name: the name of the metric.
+- help: the description of the metric.
+
+### Proposed Changes
+
+In addition to the `StatsDoc` annotation, bookkeeper should provide a tool for generating the metrics yaml file
+for documenting all annotated metrics.
+
+```bash
+bin/stats-doc-gen
+```
+
+Example output:
+
+```yaml
+"server":
+ "bookie_BOOKIE_READ_ENTRY_BYTES":
+ "description": |-
+ bytes stats of ReadEntry on a bookie
+ "type": |-
+ OPSTATS
+ "bookie_WRITE_BYTES":
+ "description": |-
+ total bytes written to a bookie
+ "type": |-
+ COUNTER
+ "bookie_BOOKIE_ADD_ENTRY":
+ "description": |-
+ operations stats of AddEntry on a bookie
+ "type": |-
+ OPSTATS
+ "bookie_BOOKIE_RECOVERY_ADD_ENTRY":
+ "description": |-
+ operation stats of RecoveryAddEntry on a bookie
+ "type": |-
+ OPSTATS
+ "bookie_BOOKIE_ADD_ENTRY_BYTES":
+ "description": |-
+ bytes stats of AddEntry on a bookie
+ "type": |-
+ OPSTATS
+ "bookie_BOOKIE_FORCE_LEDGER":
+ "description": |-
+ total force operations occurred on a bookie
+ "type": |-
+ COUNTER
+ "bookie_READ_BYTES":
+ "description": |-
+ total bytes read from a bookie
+ "type": |-
+ COUNTER
+ "bookie_BOOKIE_READ_ENTRY":
+ "description": |-
+ operation stats of ReadEntry on a bookie
+ "type": |-
+ OPSTATS
+```
+
+### Compatibility, Deprecation, and Migration Plan
+
+It is a new feature, which doesn't have any compatibility impacts.
+
+There is nothing deprecated.
+
+There is nothing to migrate.
+
+### Test Plan
+
+Existing testing is good enough to cover code changes. No new tests are needed.
+
+### Rejected Alternatives
+
+Alternatively, we have to manually maintain the metrics page and update each time when a new metric is added.
diff --git a/site/community/bookkeeper_proposals.md b/site/community/bookkeeper_proposals.md
index 94bd6a5..5824408 100644
--- a/site/community/bookkeeper_proposals.md
+++ b/site/community/bookkeeper_proposals.md
@@ -85,7 +85,7 @@ using Google Doc.
This section lists all the _bookkeeper proposals_ made to BookKeeper.
-*Next Proposal Number: 36*
+*Next Proposal Number: 37*
### Inprogress
@@ -106,7 +106,8 @@ Proposal | State
[BP-32: Advisory (optimistic) write close](../../bps/BP-32-advisory-write-close) | Accepted
[BP-33: Move releasing docker images out of main repo](../../bps/BP-33-building-official-docker-imags) | Draft
[BP-34: Cluster Metadata Checker](../../bps/BP-34-cluster-metadata-checker) | Accepted
-[BP-35: 128 bits support](../../bps/BP-35-128-bits-support) | Under Discussion
+[BP-35: 128 bits support](../../bps/BP-35-128-bits-support) | Accepted
+[BP-36: Stats documentation annotation](../../bps/BP-36-stats-documentation-annotation) | Accepted
### Adopted