From 60a50301db0462e225b8b7fcb7aec0dd82f107a1 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Thu, 21 Aug 2014 17:25:42 -0700 Subject: [PATCH] website: Document watches --- .../source/docs/agent/options.html.markdown | 13 +- .../source/docs/agent/watches.html.markdown | 286 ++++++++++++++++++ .../source/docs/commands/index.html.markdown | 1 + .../source/docs/commands/watch.html.markdown | 53 ++++ website/source/layouts/docs.erb | 8 + 5 files changed, 360 insertions(+), 1 deletion(-) create mode 100644 website/source/docs/agent/watches.html.markdown create mode 100644 website/source/docs/commands/watch.html.markdown diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index 4e6d66590..bc37837cc 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/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" + } + ] } @@ -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 diff --git a/website/source/docs/agent/watches.html.markdown b/website/source/docs/agent/watches.html.markdown new file mode 100644 index 000000000..790be11ce --- /dev/null +++ b/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" + } + ] + diff --git a/website/source/docs/commands/index.html.markdown b/website/source/docs/commands/index.html.markdown index afc3d6210..3c43cac47 100644 --- a/website/source/docs/commands/index.html.markdown +++ b/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 diff --git a/website/source/docs/commands/watch.html.markdown b/website/source/docs/commands/watch.html.markdown new file mode 100644 index 000000000..7f565a359 --- /dev/null +++ b/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". + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index fcad0930e..427a7be74 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -89,6 +89,10 @@ > reload + + + > + watch @@ -130,6 +134,10 @@ > Telemetry + + + > + Watches