apache / bookkeeper / 268 / 1
72%
master: 72%

DEFAULT BRANCH: master
Ran
Files 456
Run time 23s
Badge
Embed ▾
README BADGES
x

If you need to use a raster PNG badge, change the '.svg' to '.png' in the link

Markdown

Textile

RDoc

HTML

Rst
coverage: 72.162% (-0.1%) from 72.299%
268.1

push

jenkins

GitHub 
[STATS] introduce `StatsDoc` annotation for better documenting metrics exposed by bookkeeper

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.

### Changes

- Introduce an annotation `StatsDoc` for annotating the counters/gauges/opstats in the source code.
- Provide a tool to generate the stats and their documentation into a yaml file.

The yaml file will be used by the website for rendering a metrics reference page.

### Results

```
"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
... (continued)

25271 of 35020 relevant lines covered (72.16%)

0.72 hits per line

Source Files on job 268.1