From 3ecace4528ecdc0d548f99725fec7a92d2a6492c Mon Sep 17 00:00:00 2001
From: checketts <checketts@gmail.com>
Date: Sun, 19 Feb 2017 14:57:39 -0700
Subject: [PATCH] Add metrics registration and 'child' explanation to readme
 (#188)

Add metrics registration explanation, add TOC
---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 81 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 2d70ee18d..d79ede030 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,31 @@ It supports Java, Clojure, Scala, JRuby, and anything else that runs on the JVM.
  
 [![Build Status](https://travis-ci.org/prometheus/client_java.png?branch=master)](https://travis-ci.org/prometheus/client_java)
 
+Table of Contents
+=================
+
+  * [Using](#using)
+     * [Assets](#assets)
+     * [Javadocs](#javadocs)
+  * [Instrumenting](#instrumenting)
+     * [Counter](#counter)
+     * [Gauge](#gauge)
+     * [Summary](#summary)
+     * [Histogram](#histogram)
+     * [Labels](#labels)
+     * [Registering Metrics](#registering-metrics)
+  * [Included Collectors](#included-collectors)
+     * [Logging](#logging)
+     * [Caches](#caches)
+     * [Hibernate](#hibernate)
+  * [Exporting](#exporting)
+     * [HTTP](#http)
+  * [Exporting to a Pushgateway](#exporting-to-a-pushgateway)
+  * [Bridges](#bridges)
+     * [Graphite](#graphite)
+  * [Custom Collectors](#custom-collectors)
+  * [Contact](#contact)
+
 ## Using
 ### Assets
 If you use Maven, you can simply reference the assets below.  The latest
@@ -42,7 +67,6 @@ There are canonical examples defined in the class definition Javadoc of the clie
 Documentation can be found at the [Java Client
 Github Project Page](http://prometheus.github.io/client_java).
 
-
 ## Instrumenting
 
 Four types of metrics are offered: Counter, Gauge, Summary and Histogram.
@@ -205,7 +229,7 @@ Taking a counter as an example:
 ```java
 class YourClass {
   static final Counter requests = Counter.build()
-     .name("requests_total").help("Total requests.")
+     .name("my_library_requests_total").help("Total requests.")
      .labelNames("method").register();
   
   void processGetRequest() {
@@ -215,7 +239,58 @@ class YourClass {
 }
 ```
 
-### Included Collectors
+### Registering Metrics
+
+The best way to register a metric is via a `static final` class variable as is common with loggers.
+
+```java
+static final Counter requests = Counter.build()
+   .name("my_library_requests_total").help("Total requests.").labelNames("path").register();
+```
+ 
+Using the default registry with variables that are `static` is ideal since registering a metric with the same name 
+is not allowed and the default registry is also itself static. You can think of registering a metric, more like 
+registering a definition (as in the `TYPE` and `HELP` sections). The metric 'definition' internally holds the samples 
+that are reported and pulled out by Prometheus. Here is an example of registering a metric that has no labels.
+
+```java
+class YourClass {
+  static final Gauge activeTransactions = Gauge.build()
+     .name("my_library_transactions_active")
+     .help("Active transactions.")
+     .register();
+  
+  void processThatCalculates(String key) {
+    activeTransactions.inc();
+    try {
+        // Perform work.    
+    } finally{
+        activeTransactions.dec();
+    }
+  }
+}
+```
+
+To create timeseries with labels, include `labelNames()` with the builder. The `labels()` method looks up or creates 
+the corresponding labelled timeseries. You might also consider storing the labelled timeseries as an instance variable if it is
+appropriate. It is thread safe and can be used multiple times, which can help performance.
+
+
+```java
+class YourClass {
+  static final Counter calculationsCounter = Counter.build()
+     .name("my_library_calculations_total").help("Total calls.")
+     .labelNames("key").register();
+  
+  void processThatCalculates(String key) {
+    calculationsCounter.labels(key).inc();
+    // Run calculations.
+  }
+}
+```
+
+
+## Included Collectors
 
 The Java client includes collectors for garbage collection, memory pools, JMX, classloading, and thread counts.
 These can be added individually or just use the `DefaultExports` to conveniently register them. 
@@ -224,7 +299,7 @@ These can be added individually or just use the `DefaultExports` to conveniently
 DefaultExports.initialize();
 ```
 
-####Logging
+###Logging
 
 There are logging collectors for log4j, log4j2 and logback.
 
@@ -274,7 +349,7 @@ To register the log4j2 collector at root level:
 </Configuration>
 ```
 
-#### Caches
+### Caches
 
 To register the Guava cache collector, be certain to add `recordStats()` when building
 the cache and adding it to the registered collector. 
@@ -296,7 +371,7 @@ Cache<String, String> cache = Caffeine.newBuilder().recordStats().build();
 cacheMetrics.addCache("myCacheLabel", cache);
 ```
 
-#### Hibernate
+### Hibernate
 
 There is a collector for Hibernate which allows to collect metrics from one or more 
 `SessionFactory` instances.