From 1caa3245e6b56cbe330888137b53325e259aea2d Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Sun, 5 Jan 2014 23:04:27 -0800 Subject: [PATCH 1/5] feat(Documentation/api): add some intro material add some intro material and normalize the headers to the rest of the coreos/docs. --- Documentation/api.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/api.md b/Documentation/api.md index 2f1360acc..0200f3302 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -1,6 +1,6 @@ -## etcd API +# etcd API -### Running a Single Machine Cluster +## Running a Single Machine Cluster These examples will use a single machine cluster to show you the basics of the etcd REST API. Let's start etcd: @@ -13,6 +13,10 @@ This will bring up etcd listening on port 4001 for client communication and on p The `-data-dir machine0` argument tells etcd to write machine configuration, logs and snapshots to the `./machine0/` directory. The `-name machine` tells the rest of the cluster that this machine is named machine0. +## Key Space Operations + +The primary API of etcd is hierarchical key space. +There are directories and keys which are generically referred to as "nodes". ### Setting the value to a key From 66271fe9868facd3ccde4e558d786b0df9b27993 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Sun, 5 Jan 2014 23:05:15 -0800 Subject: [PATCH 2/5] chore(Documentation/api): remove some whitespace --- Documentation/api.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/api.md b/Documentation/api.md index 0200f3302..712379d86 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -357,7 +357,6 @@ curl -X GET http://127.0.0.1:4001/v2/keys/dir/asdf\?consistent\=true\&wait\=true } ``` - ### Atomic Compare-and-Swap (CAS) Etcd can be used as a centralized coordination service in a cluster and `CompareAndSwap` is the most basic operation used to build a distributed lock service. @@ -585,7 +584,6 @@ curl -L http://127.0.0.1:4001/v2/keys/dir?recursive=true -XDELETE } ``` - ### Creating a hidden node We can create a hidden key-value pair or directory by add a `_` prefix. From 9a8bd96ad35e57be8b6f202a562b07418049d931 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Sun, 5 Jan 2014 23:05:29 -0800 Subject: [PATCH 3/5] feat(Documentation/api): add a statistics section --- Documentation/api.md | 106 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/Documentation/api.md b/Documentation/api.md index 712379d86..f92300a29 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -658,4 +658,110 @@ curl -L http://127.0.0.1:4001/v2/keys/ Here we see the `/message` key but our hidden `/_message` key is not returned. +## Statistics +An etcd cluster keeps track of a number of stastics including latency, bandwidth and uptime. +These statistics are used in the `/mod/dashboard` to generate tables and graphs about the cluster state. + +### Leader Statistics + +The leader has a view of the entire cluster and keeps track of two interesting statistics: latency to each peer in the cluster and the number of failed and successful Raft RPC requests. +You can find grab these stastistics from the `/v2/stats/leader` endpoint: + +```sh +curl -L 127.0.0.1:4001/v2/stats/leader +``` + +```json +{ + "followers": { + "etcd-node1": { + "counts": { + "fail": 1212, + "success": 4163176 + }, + "latency": { + "average": 2.7206299430775007, + "current": 1.486487, + "maximum": 2018.410279, + "minimum": 1.011763, + "standardDeviation": 6.246990702203536 + } + }, + "etcd-node3": { + "counts": { + "fail": 1378, + "success": 4164598 + }, + "latency": { + "average": 2.707100125761001, + "current": 1.666258, + "maximum": 1409.054765, + "minimum": 0.998415, + "standardDeviation": 5.910089773061448 + } + } + }, + "leader": "etcd-node2" +} +``` + +### Self Statistics + +Each node keeps a number of internal statistics: + +- `leaderInfo.leader`: name of the current leader machine +- `leaderInfo.uptime`: amount of time the leader has been leader +- `name`: this machine's name +- `recvAppendRequestCnt`: number of append requests this node has processed +- `recvBandwidthRate`: number of bytes per second this node is receiving (follower only) +- `recvPkgRate`: number of requests per second this node is receiving (follower only) +- `sendAppendRequestCnt`: number of requests that this node has sent +- `sendBandwidthRate`: number of bytes per second this node is receiving (leader only) +- `sendPkgRate`: number of requests per second this node is receiving (leader only) +- `state`: either leader or folower +- `startTime`: the time when this node was started + +This is an example response from a follower machine: + +```sh +curl -L 127.0.0.1:4001/v2/stats/self +``` + +```json +{ + "leaderInfo": { + "leader": "etcd-node2", + "uptime": "1m18.544996775s" + }, + "name": "", + "recvAppendRequestCnt": 5871307, + "recvBandwidthRate": 630.3121596542599, + "recvPkgRate": 19.272654323628185, + "sendAppendRequestCnt": 3175763, + "startTime": "2014-01-01T15:26:24.96569404Z", + "state": "follower" +} +``` + +And this is an example response from a leader machine: + +```sh +curl -L 127.0.0.1:4001/v2/stats/self +``` + +``` +{ + "leaderInfo": { + "leader": "", + "uptime": "24.648619798s" + }, + "name": "", + "recvAppendRequestCnt": 5901116, + "sendAppendRequestCnt": 3212344, + "sendBandwidthRate": 1254.3151237301615, + "sendPkgRate": 38.71342974475808, + "startTime": "2014-01-01T15:26:24.96569404Z", + "state": "leader" +} +``` From c7e642baa2766f251cc0de9c9722b5739b91af98 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Wed, 8 Jan 2014 10:36:44 -0800 Subject: [PATCH 4/5] fix(Documentation/api): fixup the names in stats This was fixed in #449 --- Documentation/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/api.md b/Documentation/api.md index f92300a29..5201bb48a 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -731,10 +731,10 @@ curl -L 127.0.0.1:4001/v2/stats/self ```json { "leaderInfo": { - "leader": "etcd-node2", + "leader": "machine1", "uptime": "1m18.544996775s" }, - "name": "", + "name": "machine0", "recvAppendRequestCnt": 5871307, "recvBandwidthRate": 630.3121596542599, "recvPkgRate": 19.272654323628185, @@ -753,10 +753,10 @@ curl -L 127.0.0.1:4001/v2/stats/self ``` { "leaderInfo": { - "leader": "", + "leader": "machine0", "uptime": "24.648619798s" }, - "name": "", + "name": "machine0", "recvAppendRequestCnt": 5901116, "sendAppendRequestCnt": 3212344, "sendBandwidthRate": 1254.3151237301615, From 7553a92232f642a50af15b07e2b9d94bf203cb09 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Wed, 8 Jan 2014 10:40:57 -0800 Subject: [PATCH 5/5] feat(Documentation/api): document the store statistics --- Documentation/api.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/api.md b/Documentation/api.md index 5201bb48a..0f0cbc343 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -765,3 +765,33 @@ curl -L 127.0.0.1:4001/v2/stats/self "state": "leader" } ``` + +### Store Statistics + +The store statistics include information about the operations that this node has handled. + +Operations that modify the store's state like create, delete, set and update are seen by the entire cluster and the number will increase on all nodes. +Operations like get and watch are node local and will only be seen on this node. + +```sh +curl -L 127.0.0.1:4001/v2/stats/store +``` + +```json +{ + "compareAndSwapFail": 0, + "compareAndSwapSuccess": 0, + "createFail": 0, + "createSuccess": 2, + "deleteFail": 0, + "deleteSuccess": 0, + "expireCount": 0, + "getsFail": 4, + "getsSuccess": 75, + "setsFail": 2, + "setsSuccess": 4, + "updateFail": 0, + "updateSuccess": 0, + "watchers": 0 +} +```