doc/user/metrics: Add metrics docs

Author: lilic

doc/user/metrics/README.md

@@ -0,0 +1,44 @@
+# Monitoring with Prometheus
+
+[Prometheus][prometheus] is an open-source systems monitoring and alerting toolkit. Below is the overview of the different helpers that exist in operator-sdk to help setup metrics in the generated operator.
+
+## Metrics in operator-sdk
+
+The `func ExposeMetricsPort(ctx context.Context, port int32) (*v1.Service, error)` is a helper function that exposes general metrics about the running program. These metrics are inherited from controller-runtime. The metrics are by default served on `:8383/metrics`. A [Service][service] object is created with the metrics port exposed, which can be then accessed by Prometheus. The Service object is [garbage collected][gc] by the owner, which is determined based on the pods owner in which the leader is running in.
+
+To modify the port the metrics are exposed on, change the variable `metricsHost string = ":8383"` variable in the `cmd/manager/main.go` file of the generated operator.
+
+### Usage:
+
+```go
+    import(
+     "github.com/operator-framework/operator-sdk/pkg/metrics"
+	"sigs.k8s.io/controller-runtime/pkg/manager"
+    )
+
+    // Change the below variables to serve metrics on different host or port.
+    var metricsHost = "0.0.0.0"
+    var metricsPort int32 = 8383
+
+    // Pass metrics address to controller-runtime manager
+	mgr, err := manager.New(cfg, manager.Options{
+		Namespace:          namespace,
+		MetricsBindAddress: fmt.Sprintf("%s:%d", metricsHost, metricsPort),
+	})
+	
+    ...
+
+	// Create Service object to expose the metrics port.
+	_, err = metrics.ExposeMetricsPort(ctx, metricsPort)
+	if err != nil {
+        // handle error
+		log.Info(err.Error())
+	}
+```
+
+Note: The above example is already present in `cmd/manager/main.go` in all the operators generated with operator-sdk.
+
+[prometheus]: https://prometheus.io/
+[service]: https://kubernetes.io/docs/concepts/services-networking/service/
+[gc]: https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/#owners-and-dependents
+

doc/user/metrics/service_monitor.md

@@ -0,0 +1,28 @@
+## Using the ServiceMonitor prometheus-operator CRD
+
+[prometheus-operator][prom-operator] an operator that creates, configures and manages Prometheus clusters atop Kubernetes.
+
+`ServiceMonitor` is a [CR][cr] of the prometheus-operator, which discovers the `Endpoints` in `Service` objects and configures Prometheus to monitor those `Pod`s. The `GenerateServiceMonitor` takes a `Service` object and generates a `ServiceMonitor` resource based on it.
+To add `Service` target discovery of your created monitoring `Service`s you can use the `metrics.CreateServiceMonitor()` helper function, which accepts the newly created `Service`.
+
+### Prerequisites:
+
+- [prometheus-operator](prom-quickstart) needs to be deployed already in the cluster.
+
+### Usage example:
+
+```go
+    import "github.com/operator-framework/operator-sdk/pkg/metrics"
+
+    // Pass the Service(s) to the helper function, which in turn returns the `ServiceMonitor` object.
+    serviceMonitors, err := metrics.CreateServiceMonitors(restConfig, "namespace", services)
+    if err != nil {
+        // handle error here
+    }
+```
+
+*Note:* Create one `ServiceMonitor` per application and per `Namespace`.
+
+[prom-operator]: https://github.com/coreos/prometheus-operator
+[cr]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
+[prom-quickstart]: https://github.com/coreos/prometheus-operator/tree/master/contrib/kube-prometheus#quickstart