From 74acfe629682ae0be9c96e940d116a3461e4ab5d Mon Sep 17 00:00:00 2001
From: Mike Gee <geezyx@gmail.com>
Date: Sun, 29 Sep 2019 23:47:00 -0400
Subject: [PATCH] Add custom prometheus metrics documentation

---
 docs/book/src/SUMMARY.md             |  1 +
 docs/book/src/reference/metrics.md   | 45 ++++++++++++++++++++++++++++
 docs/book/src/reference/reference.md | 36 +++++++++++++++-------
 3 files changed, 72 insertions(+), 10 deletions(-)
 create mode 100644 docs/book/src/reference/metrics.md

diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index 97f46cb06a2..9d23b882e6c 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -69,6 +69,7 @@
   - [controller-gen CLI](./reference/controller-gen.md)
   - [Artifacts](./reference/artifacts.md)
   - [Writing controller tests](./reference/writing-tests.md)
+  - [Metrics](./reference/metrics.md)
 
 ---
 
diff --git a/docs/book/src/reference/metrics.md b/docs/book/src/reference/metrics.md
new file mode 100644
index 00000000000..f7cb29e164d
--- /dev/null
+++ b/docs/book/src/reference/metrics.md
@@ -0,0 +1,45 @@
+# Metrics
+
+By default, controller-runtime builds a global prometheus registry and
+publishes a collection of performance metrics for each controller.
+
+## Publishing Additional Metrics
+
+If you wish to publish additional metrics from your controllers, this
+can be easily achieved by using the global registry from
+`controller-runtime/pkg/metrics`.
+
+One way to achieve this is to declare your collectors as global variables and then register them using `init()`.
+
+For example:
+
+```go
+import (
+    "github.com/prometheus/client_golang/prometheus"
+    "sigs.k8s.io/controller-runtime/pkg/metrics"
+)
+
+var (
+    goobers = prometheus.NewCounter(
+        prometheus.CounterOpts{
+            Name: "goobers_total",
+            Help: "Number of goobers proccessed",
+        },
+    )
+    gooberFailures = prometheus.NewCounter(
+        prometheus.CounterOpts{
+            Name: "goober_failures_total",
+            Help: "Number of failed goobers",
+        },
+    )
+)
+
+func init() {
+    // Register custom metrics with the global prometheus registry
+    metrics.Registry.MustRegister(goobers, gooberFailures)
+}
+```
+
+You may then record metrics to those collectors from any part of your
+reconcile loop, and those metrics will be available for prometheus or
+other openmetrics systems to scrape.
\ No newline at end of file
diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md
index 46bcf45f37a..bd1c85fc20d 100644
--- a/docs/book/src/reference/reference.md
+++ b/docs/book/src/reference/reference.md
@@ -1,12 +1,28 @@
 # Reference
-  
-  - [Using Finalizers](./using-finalizers.md): Finalizers are a mechanism to
-	execute any custom logic related to a resource before it gets deleted from
-	Kubernetes cluster.
-  - [Webhooks](./webhook-overview.md): Webhooks are HTTP callbacks, there are 3
-  types of webhooks in k8s: 1) admission webhook 2) CRD conversion webhook 3)
-  authorization webhook
 
-    - [Admission Webhook](./admission-webhook.md): Admission webhooks are HTTP
-    callbacks for mutating or validating resources before the API server admit
-    them.
+  - [Generating CRDs](generating-crd.md)
+  - [Using Finalizers](using-finalizers.md)
+    Finalizers are a mechanism to
+    execute any custom logic related to a resource before it gets deleted from
+    Kubernetes cluster.
+  - [Kind cluster](kind.md)
+  - [What's a webhook?](webhook-overview.md)
+    Webhooks are HTTP callbacks, there are 3
+    types of webhooks in k8s: 1) admission webhook 2) CRD conversion webhook 3)
+    authorization webhook
+    - [Admission webhook](admission-webhook.md)
+      Admission webhooks are HTTP
+      callbacks for mutating or validating resources before the API server admit
+      them.
+  - [Markers for Config/Code Generation](markers.md)
+
+      - [CRD Generation](markers/crd.md)
+      - [CRD Validation](markers/crd-validation.md)
+      - [Webhook](markers/webhook.md)
+      - [Object/DeepCopy](markers/object.md)
+      - [RBAC](markers/rbac.md)
+
+  - [controller-gen CLI](controller-gen.md)
+  - [Artifacts](artifacts.md)
+  - [Writing controller tests](writing-tests.md)
+  - [Metrics](metrics.md)
\ No newline at end of file