Merge pull request #9681 from gyuho/config-log

doc: deprecate '/config/local/log' in v3.5
etcd-io · May 15, 2018 · 4a4be92 · 4a4be92
2 parents 53373fe + d6a2c4d
commit 4a4be92
Show file tree

Hide file tree

Showing 6 changed files with 35 additions and 11 deletions.
diff --git a/CHANGELOG-3.4.md b/CHANGELOG-3.4.md
@@ -212,6 +212,8 @@ See [security doc](https://github.com/coreos/etcd/blob/master/Documentation/op-g
   - e.g. `"etcdserver: no leader", "NOSPACE", "CORRUPT"`
 - Add [`dbSizeInUse` field to `etcdserverpb.StatusResponse`](https://github.com/coreos/etcd/pull/9256) for actual DB size after compaction.
 
+Note: **v3.5 will deprecate `etcd --log-package-levels` flag for `capnslog`**; `etcd --logger=zap` will the default. **v3.5 will deprecate `[CLIENT-URL]/config/local/log` endpoint.**
+
 ### Package `embed`
 
 - Add [`embed.Config.InitialElectionTickAdvance`](https://github.com/coreos/etcd/pull/9591) to enable/disable initial election tick fast-forward.

diff --git a/CHANGELOG-3.5.md b/CHANGELOG-3.5.md
@@ -12,9 +12,12 @@ See [code changes](https://github.com/coreos/etcd/compare/v3.4.0...v3.5.0) and [
 - [gRPC gateway](https://github.com/grpc-ecosystem/grpc-gateway) only supports [`/v3`](TODO) endpoint.
   - Deprecated [`/v3beta`](https://github.com/coreos/etcd/pull/9298).
   - `curl -L http://localhost:2379/v3beta/kv/put -X POST -d '{"key": "Zm9v", "value": "YmFy"}'` does work in v3.5. Use `curl -L http://localhost:2379/v3/kv/put -X POST -d '{"key": "Zm9v", "value": "YmFy"}'` instead.
-- **`etcd --log-output` has been deprecated**. Use **`etcd --log-outputs`** instead.
-- **`etcd --logger=capnslog` has been deprecated**. Now, **`etcd --logger=zap`** is the default.
-- **`etcd --log-package-levels` for `capnslog` has been deprecated**. Now, **`etcd --logger=zap`** is the default.
+- **`etcd --log-output` flag has been deprecated.** Use **`etcd --log-outputs`** instead.
+- **`etcd --logger=capnslog` flag has been deprecated.** Now, **`etcd --logger=zap`** is the default.
+- **`etcd --log-package-levels` flag for `capnslog` has been deprecated.** Now, **`etcd --logger=zap`** is the default.
+- **`[CLIENT-URL]/config/local/log` endpoint has been deprecated, as is `etcd --log-package-levels` flag.**
+  - `curl http://127.0.0.1:2379/config/local/log -XPUT -d '{"Level":"DEBUG"}'` won't work.
+  - Please use `etcd --logger=zap` instead.
 
 ### gRPC gateway
 

diff --git a/Documentation/upgrades/upgrade_3_4.md b/Documentation/upgrades/upgrade_3_4.md
@@ -65,6 +65,10 @@ cfg := &embed.Config{Debug: false}
 +cfg.LogOutputs = []string{"stderr"}
 ```
 
+#### v3.5 deprecates `capnslog`
+
+**v3.5 will deprecate `etcd --log-package-levels` flag for `capnslog`**; `etcd --logger=zap` will the default. **v3.5 will deprecate `[CLIENT-URL]/config/local/log` endpoint.**
+
 #### Deprecated `pkg/transport.TLSInfo.CAFile` field
 
 Deprecated `pkg/transport.TLSInfo.CAFile` field.

diff --git a/Documentation/upgrades/upgrade_3_5.md b/Documentation/upgrades/upgrade_3_5.md
@@ -26,22 +26,22 @@ v3.4 defaults to `--logger=zap` in order to support multiple log outputs and str
 +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**.
+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`
 
 v3.4 renamed [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs.
 
-**`etcd --log-output` has been deprecated in v3.5**.
+**`etcd --log-output` has been deprecated in v3.5.**
 
 ```diff
 -etcd --log-output stderr
 +etcd --log-outputs stderr
 ```
 
-#### Deprecated in `etcd --log-package-levels`
+#### Deprecated `etcd --log-package-levels`
 
-**`etcd --log-package-levels` for `capnslog` has been deprecated**.
+**`etcd --log-package-levels` flag for `capnslog` has been deprecated.**
 
 Now, **`etcd --logger=zap`** is the default.
 
@@ -50,6 +50,15 @@ Now, **`etcd --logger=zap`** is the default.
 +etcd --logger=zap
 ```
 
+#### Deprecated `[CLIENT-URL]/config/local/log`
+
+**`/config/local/log` endpoint is being deprecated in v3.5, as is `etcd --log-package-levels` flag.**
+
+```diff
+-$ curl http://127.0.0.1:2379/config/local/log -XPUT -d '{"Level":"DEBUG"}'
+-# debug logging enabled
+```
+
 #### Changed gRPC gateway HTTP endpoints (deprecated `/v3beta`)
 
 Before
@@ -96,7 +105,7 @@ For a much larger total data size, 100MB or more , this one-time process might t
 
 #### Downgrade
 
-If all members have been upgraded to v3.5, the cluster will be upgraded to v3.5, and downgrade from this completed state is **not possible**. If any single member is still v3.4, however, the cluster and its operations remains "v3.4", and it is possible from this mixed cluster state to return to using a v3.4 etcd binary on all members.
+If all members have been upgraded to v3.5, the cluster will be upgraded to v3.5, and downgrade from this completed state is **not possible.** If any single member is still v3.4, however, the cluster and its operations remains "v3.4", and it is possible from this mixed cluster state to return to using a v3.4 etcd binary on all members.
 
 Please [backup the data directory](../op-guide/maintenance.md#snapshot-backup) of all etcd members to make downgrading the cluster possible even after it has been completely upgraded.
 

diff --git a/Documentation/v2/admin_guide.md b/Documentation/v2/admin_guide.md
@@ -77,12 +77,14 @@ easier.
 When you want to debug etcd without stopping it, you can enable debug logging at runtime.
 etcd exposes logging configuration at `/config/local/log`.
 
+**`/config/local/log` endpoint is being deprecated in v3.5.**
+
 ```
 $ curl http://127.0.0.1:2379/config/local/log -XPUT -d '{"Level":"DEBUG"}'
-$ # debug logging enabled
-$
+# debug logging enabled
+
 $ curl http://127.0.0.1:2379/config/local/log -XPUT -d '{"Level":"INFO"}'
-$ # debug logging disabled
+# debug logging disabled
 ```
 
 #### Debugging Variables

diff --git a/etcdserver/api/etcdhttp/base.go b/etcdserver/api/etcdhttp/base.go
@@ -47,7 +47,10 @@ const (
 // that do not access the v2 store.
 func HandleBasic(mux *http.ServeMux, server etcdserver.ServerPeer) {
 	mux.HandleFunc(varsPath, serveVars)
+
+	// TODO: deprecate '/config/local/log' in v3.5
 	mux.HandleFunc(configPath+"/local/log", logHandleFunc)
+
 	HandleMetricsHealth(mux, server)
 	mux.HandleFunc(versionPath, versionHandler(server.Cluster(), serveVersion))
 }
@@ -80,6 +83,7 @@ func serveVersion(w http.ResponseWriter, r *http.Request, clusterV string) {
 	w.Write(b)
 }
 
+// TODO: deprecate '/config/local/log' in v3.5
 func logHandleFunc(w http.ResponseWriter, r *http.Request) {
 	if !allowMethod(w, r, "PUT") {
 		return