Documentation/upgrades: update guides with latest logger change

Signed-off-by: Gyuho Lee <gyuhox@gmail.com>

Documentation/upgrades/upgrade_3_2.md

@@ -12,17 +12,17 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
 
 Highlighted breaking changes in 3.2.
 
-#### Change in default `snapshot-count` value
+#### Changed default `snapshot-count` value
 
 Higher `--snapshot-count` holds more Raft entries in memory until snapshot, thus causing [recurrent higher memory usage](https://github.com/kubernetes/kubernetes/issues/60589#issuecomment-371977156). Since leader retains latest Raft entries for longer, a slow follower has more time to catch up before leader snapshot. `--snapshot-count` is a tradeoff between higher memory usage and better availabilities of slow followers.
 
 Since v3.2, the default value of `--snapshot-count` has [changed from from 10,000 to 100,000](https://github.com/coreos/etcd/pull/7160).
 
-#### Change in gRPC dependency (>=3.2.10)
+#### Changed gRPC dependency (>=3.2.10)
 
 3.2.10 or later now requires [grpc/grpc-go](https://github.com/grpc/grpc-go/releases) `v1.7.5` (<=3.2.9 requires `v1.2.1`).
 
-##### Deprecate `grpclog.Logger`
+##### Deprecated `grpclog.Logger`
 
 `grpclog.Logger` has been deprecated in favor of [`grpclog.LoggerV2`](https://github.com/grpc/grpc-go/blob/master/grpclog/loggerv2.go). `clientv3.Logger` is now `grpclog.LoggerV2`.
 
@@ -43,7 +43,7 @@ clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))
 // log.New above cannot be used (not implement grpclog.LoggerV2 interface)
 ```
 
-##### Deprecate `grpc.ErrClientConnTimeout`
+##### Deprecated `grpc.ErrClientConnTimeout`
 
 Previously, `grpc.ErrClientConnTimeout` error is returned on client dial time-outs. 3.2 instead returns `context.DeadlineExceeded` (see [#8504](https://github.com/coreos/etcd/issues/8504)).
 
@@ -72,7 +72,7 @@ if err == context.DeadlineExceeded {
 }
 ```
 
-#### Change in maximum request size limits (>=3.2.10)
+#### Changed maximum request size limits (>=3.2.10)
 
 3.2.10 and 3.2.11 allow custom request size limits in server side. >=3.2.12 allows custom request size limits for both server and **client side**. In previous versions(v3.2.10, v3.2.11), client response size was limited to only 4 MiB.
 
@@ -145,7 +145,7 @@ err.Error() == "rpc error: code = ResourceExhausted desc = grpc: received messag
 
 **If not specified, client-side send limit defaults to 2 MiB (1.5 MiB + gRPC overhead bytes) and receive limit to `math.MaxInt32`**. Please see [clientv3 godoc](https://godoc.org/github.com/coreos/etcd/clientv3#Config) for more detail.
 
-#### Change in raw gRPC client wrappers
+#### Changed raw gRPC client wrappers
 
 3.2.12 or later changes the function signatures of `clientv3` gRPC client wrapper. This change was needed to support [custom `grpc.CallOption` on message size limits](https://github.com/coreos/etcd/pull/9047).
 
@@ -168,7 +168,7 @@ Before and after
 +func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher {
 ```
 
-#### Change in `clientv3.Lease.TimeToLive` API
+#### Changed `clientv3.Lease.TimeToLive` API
 
 Previously, `clientv3.Lease.TimeToLive` API returned `lease.ErrLeaseNotFound` on non-existent lease ID. 3.2 instead returns TTL=-1 in its response and no error (see [#7305](https://github.com/coreos/etcd/pull/7305)).
 
@@ -190,7 +190,7 @@ resp.TTL == -1
 err == nil
 ```
 
-#### Change in `clientv3.NewFromConfigFile`
+#### Moved `clientv3.NewFromConfigFile` to `clientv3.yaml.NewConfig`
 
 `clientv3.NewFromConfigFile` is moved to `yaml.NewConfig`.
 

Documentation/upgrades/upgrade_3_3.md

@@ -12,7 +12,7 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
 
 Highlighted breaking changes in 3.3.
 
-#### Change in `--auto-compaction-retention` flag
+#### Changed value type of `etcd --auto-compaction-retention` flag to `string`
 
 Changed `--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). Now that `--auto-compaction-retention` accepts string values, etcd configuration YAML file `auto-compaction-retention` field must be changed to `string` type. Previously, `--config-file etcd.config.yaml` can have `auto-compaction-retention: 24` field, now must be `auto-compaction-retention: "24"` or `auto-compaction-retention: "24h"`. If configured as `--auto-compaction-mode periodic --auto-compaction-retention "24h"`, the time duration value for `--auto-compaction-retention` flag must be valid for [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration) function in Go.
 
@@ -25,7 +25,7 @@ Changed `--auto-compaction-retention` flag to [accept string values](https://git
 +# auto-compaction-retention: "24h"
 ```
 
-#### Change in `etcdserver.EtcdServer` struct
+#### Changed `etcdserver.EtcdServer.ServerConfig` to `*etcdserver.EtcdServer.ServerConfig`
 
 `etcdserver.EtcdServer` has changed the type of its member field `*etcdserver.ServerConfig` to `etcdserver.ServerConfig`. And `etcdserver.NewServer` now takes `etcdserver.ServerConfig`, instead of `*etcdserver.ServerConfig`.
 
@@ -55,7 +55,9 @@ func (e *EtcdServer) Start() error {
     ...
 ```
 
-#### Change in `embed.EtcdServer` struct
+#### Added `embed.Config.LogOutput` struct
+
+**Note that this field has been renamed to `embed.Config.LogOutputs` in `[]string` type in v3.4. Please see [v3.4 upgrade guide](https://github.com/coreos/etcd/blob/master/Documentation/upgrades/upgrade_3_4.md) for more details.**
 
 Field `LogOutput` is added to `embed.Config`:
 
@@ -78,6 +80,8 @@ WARNING: 2017/11/02 11:35:51 grpc: addrConn.resetTransport failed to create clie
 
 From v3.3, gRPC server logs are disabled by default.
 
+**Note that `embed.Config.SetupLogging` method has been deprecated in v3.4. Please see [v3.4 upgrade guide](https://github.com/coreos/etcd/blob/master/Documentation/upgrades/upgrade_3_4.md) for more details.**
+
 ```go
 import "github.com/coreos/etcd/embed"
 
@@ -87,7 +91,7 @@ cfg.SetupLogging()
 
 Set `embed.Config.Debug` field to `true` to enable gRPC server logs.
 
-#### Change in `/health` endpoint response
+#### Changed `/health` endpoint response
 
 Previously, `[endpoint]:[client-port]/health` returned manually marshaled JSON value. 3.3 now defines [`etcdhttp.Health`](https://godoc.org/github.com/coreos/etcd/etcdserver/api/etcdhttp#Health) struct.
 
@@ -98,7 +102,7 @@ $ curl http://localhost:2379/health
 {"health":"true"}
 ```
 
-#### Change in gRPC gateway HTTP endpoints (replaced `/v3alpha` with `/v3beta`)
+#### Changed gRPC gateway HTTP endpoints (replaced `/v3alpha` with `/v3beta`)
 
 Before
 
@@ -116,7 +120,7 @@ curl -L http://localhost:2379/v3beta/kv/put \
 
 Requests to `/v3alpha` endpoints will redirect to `/v3beta`, and `/v3alpha` will be removed in 3.4 release.
 
-#### Change in maximum request size limits
+#### Changed maximum request size limits
 
 3.3 now allows custom request size limits for both server and **client side**. In previous versions(v3.2.10, v3.2.11), client response size was limited to only 4 MiB.
 
@@ -189,7 +193,7 @@ err.Error() == "rpc error: code = ResourceExhausted desc = grpc: received messag
 
 **If not specified, client-side send limit defaults to 2 MiB (1.5 MiB + gRPC overhead bytes) and receive limit to `math.MaxInt32`**. Please see [clientv3 godoc](https://godoc.org/github.com/coreos/etcd/clientv3#Config) for more detail.
 
-#### Change in raw gRPC client wrappers
+#### Changed raw gRPC client wrapper function signatures
 
 3.3 changes the function signatures of `clientv3` gRPC client wrapper. This change was needed to support [custom `grpc.CallOption` on message size limits](https://github.com/coreos/etcd/pull/9047).
 
@@ -212,7 +216,7 @@ Before and after
 +func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher {
 ```
 
-#### Change in clientv3 `Snapshot` API error type
+#### Changed clientv3 `Snapshot` API error type
 
 Previously, clientv3 `Snapshot` API returned raw [`grpc/*status.statusError`] type error. v3.3 now translates those errors to corresponding public error types, to be consistent with other APIs.
 
@@ -258,7 +262,7 @@ _, err = io.Copy(f, rc)
 err == context.DeadlineExceeded
 ```
 
-#### Change in `etcdctl lease timetolive` command output
+#### Changed `etcdctl lease timetolive` command output
 
 Previously, `lease timetolive LEASE_ID` command on expired lease prints `-1s` for remaining seconds. 3.3 now outputs clearer messages.
 
@@ -275,7 +279,7 @@ After
 lease 2d8257079fa1bc0c already expired
 ```
 
-#### Change in `golang.org/x/net/context` imports
+#### Changed `golang.org/x/net/context` imports
 
 `clientv3` has deprecated `golang.org/x/net/context`. If a project vendors `golang.org/x/net/context` in other code (e.g. etcd generated protocol buffer code) and imports `github.com/coreos/etcd/clientv3`, it requires Go 1.9+ to compile.
 
@@ -293,11 +297,11 @@ import "context"
 cli.Put(context.Background(), "f", "v")
 ```
 
-#### Change in gRPC dependency
+#### Changed gRPC dependency
 
 3.3 now requires [grpc/grpc-go](https://github.com/grpc/grpc-go/releases) `v1.7.5`.
 
-##### Deprecate `grpclog.Logger`
+##### Deprecated `grpclog.Logger`
 
 `grpclog.Logger` has been deprecated in favor of [`grpclog.LoggerV2`](https://github.com/grpc/grpc-go/blob/master/grpclog/loggerv2.go). `clientv3.Logger` is now `grpclog.LoggerV2`.
 
@@ -318,7 +322,7 @@ clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))
 // log.New above cannot be used (not implement grpclog.LoggerV2 interface)
 ```
 
-##### Deprecate `grpc.ErrClientConnTimeout`
+##### Deprecated `grpc.ErrClientConnTimeout`
 
 Previously, `grpc.ErrClientConnTimeout` error is returned on client dial time-outs. 3.3 instead returns `context.DeadlineExceeded` (see [#8504](https://github.com/coreos/etcd/issues/8504)).
 
@@ -347,7 +351,7 @@ if err == context.DeadlineExceeded {
 }
 ```
 
-#### Change in official container registry
+#### Changed official container registry
 
 etcd now uses [`gcr.io/etcd-development/etcd`](https://gcr.io/etcd-development/etcd) as a primary container registry, and [`quay.io/coreos/etcd`](https://quay.io/coreos/etcd) as secondary.
 

Documentation/upgrades/upgrade_3_4.md

@@ -12,7 +12,7 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
 
 Highlighted breaking changes in 3.4.
 
-#### Change in `etcd` flags
+#### Deprecated `etcd --ca-file` and `etcd --peer-ca-file` flags
 
 `--ca-file` and `--peer-ca-file` flags are deprecated; they have been deprecated since v2.1.
 
@@ -26,16 +26,42 @@ Highlighted breaking changes in 3.4.
 +etcd --peer-trusted-ca-file ca-peer.crt
 ```
 
-Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624)  to support multiple log outputs.
+#### Deprecating `etcd --log-output` flag (now `--log-outputs`)
 
-**`etcd --log-output`** will be deprecated in v3.5.
+Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs. **`etcd --logger=capnslog` does not support multiple log outputs.**
+
+**`etcd --log-output`** will be deprecated in v3.5. **`etcd --logger=capnslog` will be deprecated in v3.5**.
 
 ```diff
 -etcd --log-output stderr
 +etcd --log-outputs stderr,a.log
 ```
 
-#### Change in `pkg/transport`
+v3.4 adds `etcd --logger zap` support for structured logging and multiple log outputs. Main motivation is to promote automated etcd monitoring, rather than looking back server logs when it starts breaking. Future development will make etcd log as few as possible, and make etcd easier to monitor with metrics and alerts. **`etcd --logger=capnslog` will be deprecated in v3.5**.
+
+#### Changed `log-outputs` field type in `etcd --config-file` to `[]string`
+
+Now that `log-outputs` (old field name `log-output`) accepts multiple writers, etcd configuration YAML file `log-outputs` field must be changed to `[]string` type as below:
+
+```diff
+ # Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
+-log-output: default
++log-outputs: [default]
+```
+
+#### Renamed `embed.Config.LogOutput` to `embed.Config.LogOutputs`
+
+Renamed [**`embed.Config.LogOutput`** to **`embed.Config.LogOutputs`**](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs. And changed [`embed.Config.LogOutput` type from `string` to `[]string`](https://github.com/coreos/etcd/pull/9579) to support multiple log outputs.
+
+```diff
+import "github.com/coreos/etcd/embed"
+
+cfg := &embed.Config{Debug: false}
+-cfg.LogOutput = "stderr"
++cfg.LogOutputs = []string{"stderr"}
+```
+
+#### Deprecated `pkg/transport.TLSInfo.CAFile` field
 
 Deprecated `pkg/transport.TLSInfo.CAFile` field.
 
@@ -54,7 +80,7 @@ if err != nil {
 }
 ```
 
-#### Change in `wal`
+#### Changed function signature in package `wal`
 
 Changed `wal` function signatures to support structured logger.
 
@@ -77,7 +103,7 @@ import "github.com/coreos/etcd/wal"
 +wal.Create(lg, dirpath, metadata)
 ```
 
-#### Change in `embed.Etcd`
+#### Deprecated `embed.Config.SetupLogging`
 
 `embed.Config.SetupLogging` has been removed in order to prevent wrong logging configuration, and now set up automatically.
 
@@ -88,42 +114,23 @@ cfg := &embed.Config{Debug: false}
 -cfg.SetupLogging()
 ```
 
-Renamed [**`embed.Config.LogOutput`** to **`embed.Config.LogOutputs`**](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs. And changed [`embed.Config.LogOutput` type from `string` to `[]string`](https://github.com/coreos/etcd/pull/9579) to support multiple log outputs.
+#### Changed gRPC gateway HTTP endpoints (replaced `/v3beta` with `/v3`)
 
-```diff
-import "github.com/coreos/etcd/embed"
+Before
 
-cfg := &embed.Config{Debug: false}
--cfg.LogOutput = "stderr"
-+cfg.LogOutputs = []string{"stderr"}
+```bash
+curl -L http://localhost:2379/v3beta/kv/put \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
 ```
 
-#### Change in `etcd --log-output` (now `--log-outputs`)
-
-Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624)  to support multiple log outputs.
+After
 
-**`etcd --log-output`** will be deprecated in v3.5.
-
-```diff
--etcd --log-output stderr
-+etcd --log-outputs stderr,a.log
+```bash
+curl -L http://localhost:2379/v3/kv/put \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
 ```
 
-```diff
- # Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
--log-output: [default]
-+log-outputs: [default]
-```
-
-#### Change in `etcd --config-file`
-
-Now that `log-outputs` (old field name `log-output`) accepts multiple writers, etcd configuration YAML file `log-outputs` field must be changed to `[]string` type as below:
-
-```diff
- # Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
--log-output: default
-+log-outputs: [default]
-```
+Requests to `/v3beta` endpoints will redirect to `/v3`, and `/v3beta` will be removed in 3.5 release.
 
 ### Server upgrade checklists
 

Documentation/upgrades/upgrade_3_5.md

@@ -12,17 +12,46 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
 
 Highlighted breaking changes in 3.5.
 
+#### Deprecated in `etcd --logger capnslog`
+
+v3.4 adds `--logger=zap` to support multiple log outputs and structured logging. **`etcd --logger=capnslog` has been deprecated in v3.5**, and now `--logger=zap` is the default.
+
+```diff
+-etcd --logger capnslog
++etcd --logger zap --log-outputs stderr,a.log
+```
+
+TODO(add more monitoring guides); v3.4 adds `etcd --logger zap` support for structured logging and multiple log outputs. Main motivation is to promote automated etcd monitoring, rather than looking back server logs when it starts breaking. Future development will make etcd log as few as possible, and make etcd easier to monitor with metrics and alerts. **`etcd --logger=capnslog` will be deprecated in v3.5**.
+
 #### Deprecated in `etcd --log-output`
 
-Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624)  to support multiple log outputs.
+v3.4 renamed [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs.
 
-**`etcd --log-output`** is deprecated in v3.5.
+**`etcd --log-output` has been deprecated in v3.5**.
 
 ```diff
--$ etcd --log-output stderr
-+$ etcd --log-outputs stderr,a.log
+-etcd --log-output stderr
++etcd --log-outputs stderr,a.log
+```
+
+#### Changed gRPC gateway HTTP endpoints (deprecated `/v3beta`)
+
+Before
+
+```bash
+curl -L http://localhost:2379/v3beta/kv/put \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
 ```
 
+After
+
+```bash
+curl -L http://localhost:2379/v3/kv/put \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
+```
+
+`/v3beta` has been removed in 3.5 release.
+
 ### Server upgrade checklists
 
 #### Upgrade requirements