website: Document watches

website/source/docs/agent/options.html.markdown

@@ -145,7 +145,13 @@ definitions support being updated during a reload.
   "data_dir": "/opt/consul",
   "log_level": "INFO",
   "node_name": "foobar",
-  "server": true
+  "server": true,
+  "watches": [
+    {
+        "type": "checks",
+        "handler": "/usr/bin/health-check-handler.sh"
+    }
+  ]
 }
 </pre>
 
@@ -316,6 +322,11 @@ definitions support being updated during a reload.
    However, because the caches are not actively invalidated, ACL policy may be stale
    up to the TTL value.
 
+* `watches` - Watches is a list of watch specifications.
+   These allow an external process to be automatically invoked when a particular
+   data view is updated. See the [watch documentation](/docs/agent/watches.html) for
+   more documentation. Watches can be modified when the configuration is reloaded.
+
 ## Ports Used
 
 Consul requires up to 5 different ports to work properly, some requiring

website/source/docs/agent/watches.html.markdown

@@ -0,0 +1,286 @@
+---
+layout: "docs"
+page_title: "Watches"
+sidebar_current: "docs-agent-watches"
+---
+
+# Watches
+
+Watches are a way of specifying a view of data (list of nodes, KV pairs,
+health checks, etc) which is monitored for any updates. When an update
+is detected, an external handler handler is invoked. A handler can be any
+executable. As an example, you could  watch the status of health checks and
+notify an external system when a check is critical.
+
+Watches are implemented using blocking queries in the [HTTP API](/docs/agent/http.html).
+Agent's automatically make the proper API calls to watch for changes,
+and inform a handler when the data view has updated.
+
+Watches can can be configured as part of the [agent's configuration](/docs/agent/options.html),
+causing them to run once the agent is initialized. Reloading the agent configuration
+allows for adding or removing watches dynamically.
+
+Alternatively, the [watch command](/docs/commands/watch.html) enables a watch to be
+started outside of the agent. This can be used by an operator to inspect data in Consul,
+or to easily pipe data into processes without being tied to the agent lifecycle.
+
+In either case, the `type` of the watch must be specified. Each type of watch
+supports different parameters, both required and optional. These options are specified
+in a JSON body when using agent configuration, or as CLI flags for the watch command.
+
+## Handlers
+
+The watch specifiation specifies the view of data to be monitored.
+Once that view is updated the specified handler is invoked. The handler
+can be any executable.
+
+A handler should read it's input from stdin, and expect to read
+JSON formatted data. The format of the data depends on the type of the
+watch. Each watch type documents the format type, and because they
+map directly to an HTTP API, handlers should expect the input to
+match the format of the API.
+
+Additionally, the `CONSUL_INDEX` environmental variable will be set.
+This maps to the `X-Consul-Index` value from the [HTTP API](/docs/agent/http.html).
+
+## Global Parameters
+
+In addition to the parameters supported by each option type, there
+are a few global parameters that all watches support:
+
+* `datacenter` - Can be provided to override the agent's default datacenter.
+* `token` - Can be provided to override the agent's default ACL token.
+* `handler` - The handler to invoke when the data view updates.
+
+## Watch Types
+
+The following types are supported, with more documentation below:
+
+* `key` - Watch a specific KV pair
+* `keyprefix` - Watch a prefix in the KV store
+* `services` - Watch the list of available services
+* `nodes` - Watch the list of nodes
+* `service`-  Watch the instances of a service
+* `checks` - Watch the value of health checks
+
+
+### Type: key
+
+The "key" watch type is used to watch a specific key in the KV store.
+It requires that the "key" parameter be specified.
+
+This maps to the `/v1/kv/` API internally.
+
+Here is an example configuration:
+
+    {
+        "type": "key",
+        "key": "foo/bar/baz",
+        "handler": "/usr/bin/my-key-handler.sh"
+    }
+
+Or, using the watch command:
+
+    $ consul watch -type key -key foo/bar/baz /usr/bin/my-key-handler.sh
+
+An example of the output of this command:
+
+    {
+        "Key": "foo/bar/baz",
+        "CreateIndex": 1793,
+        "ModifyIndex": 1793,
+        "LockIndex": 0,
+        "Flags": 0,
+        "Value": "aGV5",
+        "Session": ""
+    }
+
+### Type: keyprefix
+
+The "keyprefix" watch type is used to watch a prefix of keys in the KV store.
+It requires that the "prefix" parameter be specified.
+
+This maps to the `/v1/kv/` API internally.
+
+Here is an example configuration:
+
+    {
+        "type": "keyprefix",
+        "prefix": "foo/",
+        "handler": "/usr/bin/my-prefix-handler.sh"
+    }
+
+Or, using the watch command:
+
+    $ consul watch -type keyprefix -prefix foo/ /usr/bin/my-prefix-handler.sh
+
+An example of the output of this command:
+
+    [
+        {
+            "Key": "foo/bar",
+            "CreateIndex": 1796,
+            "ModifyIndex": 1796,
+            "LockIndex": 0,
+            "Flags": 0,
+            "Value": "TU9BUg==",
+            "Session": ""
+        },
+        {
+            "Key": "foo/baz",
+            "CreateIndex": 1795,
+            "ModifyIndex": 1795,
+            "LockIndex": 0,
+            "Flags": 0,
+            "Value": "YXNkZg==",
+            "Session": ""
+        },
+        {
+            "Key": "foo/test",
+            "CreateIndex": 1793,
+            "ModifyIndex": 1793,
+            "LockIndex": 0,
+            "Flags": 0,
+            "Value": "aGV5",
+            "Session": ""
+        }
+    ]
+
+
+### Type: services
+
+The "services" watch type is used to watch the list of available
+services. It has no parameters.
+
+This maps to the `/v1/catalog/services` API internally.
+
+An example of the output of this command:
+
+    {
+        "consul": [],
+        "redis": [],
+        "web": []
+    }
+
+### Type: nodes
+
+The "nodes" watch type is used to watch the list of available
+nodes. It has no parameters.
+
+This maps to the `/v1/catalog/nodes` API internally.
+
+An example of the output of this command:
+
+    [
+        {
+            "Node": "nyc1-consul-1",
+            "Address": "192.241.159.115"
+        },
+        {
+            "Node": "nyc1-consul-2",
+            "Address": "192.241.158.205"
+        },
+        {
+            "Node": "nyc1-consul-3",
+            "Address": "198.199.77.133"
+        },
+        {
+            "Node": "nyc1-worker-1",
+            "Address": "162.243.162.228"
+        },
+        {
+            "Node": "nyc1-worker-2",
+            "Address": "162.243.162.226"
+        },
+        {
+            "Node": "nyc1-worker-3",
+            "Address": "162.243.162.229"
+        }
+    ]
+
+### Type: service
+
+The "service" watch type is used to monitor the providers
+of a single service. It requires the "service" parameter,
+but optionally takes "tag" and "passingonly". The "tag" parameter
+will filter by tag, and "passingonly" is a boolean that will
+filter to only the instances passing all health checks.
+
+This maps to the `/v1/health/service` API internally.
+
+Here is an example configuration:
+
+    {
+        "type": "service",
+        "key": "redis",
+        "handler": "/usr/bin/my-service-handler.sh"
+    }
+
+Or, using the watch command:
+
+    $ consul watch -type service -service redis /usr/bin/my-service-handler.sh
+
+An example of the output of this command:
+
+    [
+        {
+            "Node": {
+                "Node": "foobar",
+                "Address": "10.1.10.12"
+            },
+            "Service": {
+                "ID": "redis",
+                "Service": "redis",
+                "Tags": null,
+                "Port": 8000
+            },
+            "Checks": [
+                {
+                    "Node": "foobar",
+                    "CheckID": "service:redis",
+                    "Name": "Service 'redis' check",
+                    "Status": "passing",
+                    "Notes": "",
+                    "Output": "",
+                    "ServiceID": "redis",
+                    "ServiceName": "redis"
+                },
+                {
+                    "Node": "foobar",
+                    "CheckID": "serfHealth",
+                    "Name": "Serf Health Status",
+                    "Status": "passing",
+                    "Notes": "",
+                    "Output": "",
+                    "ServiceID": "",
+                    "ServiceName": ""
+                }
+            ]
+        }
+    ]
+
+### Type: checks
+
+The "checks" watch type is used to monitor the checks of a given
+service or in a specific state. It optionally takes the "service"
+parameter to filter to a specific service, or "state" to filter
+to a specific state. By default, it will watch all checks.
+
+This maps to the `/v1/health/state/` API if monitoring by state,
+or `/v1/health/checks/` if monitoring by service.
+
+An example of the output of this command:
+
+    [
+        {
+            "Node": "foobar",
+            "CheckID": "service:redis",
+            "Name": "Service 'redis' check",
+            "Status": "passing",
+            "Notes": "",
+            "Output": "",
+            "ServiceID": "redis",
+            "ServiceName": "redis"
+        }
+    ]
+

website/source/docs/commands/index.html.markdown

@@ -34,6 +34,7 @@ Available commands are:
     monitor        Stream logs from a Consul agent
     reload         Triggers the agent to reload configuration files
     version        Prints the Consul version
+    watch          Watch for changes in Consul
 ```
 
 To get help for any specific command, pass the `-h` flag to the relevant

website/source/docs/commands/watch.html.markdown

@@ -0,0 +1,53 @@
+---
+layout: "docs"
+page_title: "Commands: Watch"
+sidebar_current: "docs-commands-watch"
+---
+
+# Consul Watch
+
+Command: `consul watch`
+
+The watch command provides a mechanism to watch for changes in a particular
+data view (list of nodes, service members, key value, etc) and to invoke
+a process with the latest values of the view. If no process is specified,
+the current values are dumped to stdout which can be a useful way to inspect
+data in Consul.
+
+There is more [documentation on watches here](/docs/agent/watches.html).
+
+## Usage
+
+Usage: `consul watch [options] [child...]`
+
+The only required option is `-type` which specifies the particular
+data view. Depending on the type, various options may be required
+or optionally provided. There is more documentation on watch
+[specifications here](/docs/agent/watches.html).
+
+The list of available flags are:
+
+* `-http-addr` - Address to the HTTP server of the agent you want to contact
+  to send this command. If this isn't specified, the command will contact
+  "127.0.0.1:8500" which is the default HTTP address of a Consul agent.
+
+* `-datacenter` - Datacenter to query. Defaults to that of agent.
+
+* `-token` - ACL token to use. Defaults to that of agent.
+
+* `-key` - Key to watch. Only for `key` type.
+
+* `-passingonly=[true|false]` - Should only passing entries be returned. Default false.
+  only for `service` type.
+
+* `-prefix` - Key prefix to watch. Only for `keyprefix` type.
+
+* `-service` - Service to watch. Required for `service` type, optional for `checks` type.
+
+* `-state` - Check state to filter on. Optional for `checks` type.
+
+* `-tag` - Service tag to filter on. Optional for `service` type.
+
+* `-type` - Watch type. Required, one of "key", "keyprefix", "services",
+  "nodes", "services", or "checks".
+

website/source/layouts/docs.erb

@@ -89,6 +89,10 @@
 
 					<li<%= sidebar_current("docs-commands-reload") %>>
 					<a href="/docs/commands/reload.html">reload</a>
+                    </li>
+
+					<li<%= sidebar_current("docs-commands-watch") %>>
+					<a href="/docs/commands/watch.html">watch</a>
 					</li>
 				</ul>
 				</li>
@@ -130,6 +134,10 @@
 
 					<li<%= sidebar_current("docs-agent-telemetry") %>>
 					<a href="/docs/agent/telemetry.html">Telemetry</a>
+                    </li>
+
+					<li<%= sidebar_current("docs-agent-watches") %>>
+					<a href="/docs/agent/watches.html">Watches</a>
 					</li>
                 </ul>