Merge pull request #9672 from joelegasse/listen-metrics-doc

docs: Update documentation around --listen-metrics-urls

CHANGELOG-3.3.md

@@ -174,7 +174,7 @@ See [code changes](https://github.com/coreos/etcd/compare/v3.2.0...v3.3.0) and [
 
 ### Metrics, Monitoring
 
-- Add [`etcd --listen-metrics-urls`](https://github.com/coreos/etcd/pull/8242) flag for additional `/metrics` endpoints.
+- Add [`etcd --listen-metrics-urls`](https://github.com/coreos/etcd/pull/8242) flag for additional `/metrics` and `/health` endpoints.
   - Useful for [bypassing critical APIs when monitoring etcd](https://github.com/coreos/etcd/issues/8060).
 - Add [`etcd_server_version`](https://github.com/coreos/etcd/pull/8960) Prometheus metric.
   - To replace [Kubernetes `etcd-version-monitor`](https://github.com/coreos/etcd/issues/8948).
@@ -222,9 +222,9 @@ See [security doc](https://github.com/coreos/etcd/blob/master/Documentation/op-g
   - If not configured, it defaults to 1.5 MiB.
 - Add [`--client-crl-file`, `--peer-crl-file`](https://github.com/coreos/etcd/pull/8124) flags for [Certificate revocation list](https://github.com/coreos/etcd/issues/4034).
 - Add [`--peer-cert-allowed-cn`](https://github.com/coreos/etcd/pull/8616) flag to support [CN-based auth for inter-peer connection](https://github.com/coreos/etcd/issues/8262).
-- Add [`--listen-metrics-urls`](https://github.com/coreos/etcd/pull/8242) flag for additional `/metrics` endpoints.
+- Add [`--listen-metrics-urls`](https://github.com/coreos/etcd/pull/8242) flag for additional `/metrics` and `/health` endpoints.
   - Support [additional (non) TLS `/metrics` endpoints for a TLS-enabled cluster](https://github.com/coreos/etcd/pull/8282).
-  - e.g. `--listen-metrics-urls=https://localhost:2378,http://localhost:9379` to serve `/metrics` in secure port 2378 and insecure port 9379.
+  - e.g. `--listen-metrics-urls=https://localhost:2378,http://localhost:9379` to serve `/metrics` and `/health` on secure port 2378 and insecure port 9379.
   - Useful for [bypassing critical APIs when monitoring etcd](https://github.com/coreos/etcd/issues/8060).
 - Add [`--auto-compaction-mode`](https://github.com/coreos/etcd/pull/8123) flag to [support revision-based compaction](https://github.com/coreos/etcd/issues/8098).
 - Change `--auto-compaction-retention` flag to [accept string values](https://github.com/coreos/etcd/pull/8563) with [finer granularity](https://github.com/coreos/etcd/issues/8503).

Documentation/op-guide/configuration.md

@@ -365,7 +365,7 @@ Follow the instructions when using these flags.
 + default: basic
 
 ### --listen-metrics-urls
-+ List of URLs to listen on for metrics.
++ List of additional URLs to listen on that will respond to both the `/metrics` and `/health` endpoints
 + default: ""
 
 ## Auth flags

Documentation/op-guide/monitoring.md

@@ -43,7 +43,7 @@ When	Elapsed (s)
 
 ## Metrics endpoint
 
-Each etcd server exports metrics under the `/metrics` path on its client port and optionally on interfaces given by `--listen-metrics-urls`.
+Each etcd server exports metrics under the `/metrics` path on its client port and optionally on locations given by `--listen-metrics-urls`.
 
 The metrics can be fetched with `curl`:
 
@@ -59,6 +59,10 @@ etcd_disk_backend_commit_duration_seconds_bucket{le="0.016"} 406464
 ...
 ```
 
+## Health Check
+
+In addtion to responding to the `/metrics` endpoint, any locations specified by `--listen-metrics-urls` will also respond to the `/health` endpoint. This can be useful if the standard endpoint is configured with mutual (client) TLS authentation, but a load balancer or monitoring service still needs access to the health check.
+
 ## Prometheus
 
 Running a [Prometheus][prometheus] monitoring service is the easiest way to ingest and record etcd's metrics.

etcdmain/config.go

@@ -145,7 +145,7 @@ func newConfig() *config {
 	fs.Var(
 		flags.NewUniqueURLsWithExceptions("", ""),
 		"listen-metrics-urls",
-		"List of URLs to listen on for metrics.",
+		"List of URLs to listen on for the metrics and health endpoints.",
 	)
 	fs.UintVar(&cfg.ec.MaxSnapFiles, "max-snapshots", cfg.ec.MaxSnapFiles, "Maximum number of snapshot files to retain (0 is unlimited).")
 	fs.UintVar(&cfg.ec.MaxWalFiles, "max-wals", cfg.ec.MaxWalFiles, "Maximum number of wal files to retain (0 is unlimited).")

etcdmain/help.go

@@ -149,13 +149,13 @@ Auth:
   --auth-token 'simple'
     Specify a v3 authentication token type and its options ('simple' or 'jwt').
 
-Profiling:
+Profiling and Monitoring:
   --enable-pprof 'false'
     Enable runtime profiling data via HTTP server. Address is at client URL + "/debug/pprof/"
   --metrics 'basic'
     Set level of detail for exported metrics, specify 'extensive' to include histogram metrics.
   --listen-metrics-urls ''
-    List of URLs to listen on for metrics.
+    List of URLs to listen on for the metrics and health endpoints.
 
 Logging:
   --logger 'capnslog'