1--- 2layout: "docs" 3page_title: "Watches" 4sidebar_current: "docs-agent-watches" 5description: |- 6 Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs, health checks) which is monitored for updates. When an update is detected, an external 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. 7--- 8 9# Watches 10 11Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs, health 12checks) which is monitored for updates. When an update is detected, an external handler 13is invoked. A handler can be any executable or HTTP endpoint. As an example, you could watch the status 14of health checks and notify an external system when a check is critical. 15 16Watches are implemented using blocking queries in the [HTTP API](/api/index.html). 17Agents automatically make the proper API calls to watch for changes 18and inform a handler when the data view has updated. 19 20Watches can be configured as part of the [agent's configuration](/docs/agent/options.html#watches), 21causing them to run once the agent is initialized. Reloading the agent configuration 22allows for adding or removing watches dynamically. 23 24Alternatively, the [watch command](/docs/commands/watch.html) enables a watch to be 25started outside of the agent. This can be used by an operator to inspect data in Consul 26or to easily pipe data into processes without being tied to the agent lifecycle. 27 28In either case, the `type` of the watch must be specified. Each type of watch 29supports different parameters, some required and some optional. These options are specified 30in a JSON body when using agent configuration or as CLI flags for the watch command. 31 32## Handlers 33 34The watch configuration specifies the view of data to be monitored. 35Once that view is updated, the specified handler is invoked. Handlers can be either an 36executable or an HTTP endpoint. A handler receives JSON formatted data 37with invocation info, following a format that depends on the type of the watch. 38Each watch type documents the format type. Because they map directly to an HTTP 39API, handlers should expect the input to match the format of the API. A Consul 40index is also given, corresponding to the responses from the 41[HTTP API](/api/index.html). 42 43### Executable 44 45An executable handler reads the JSON invocation info from stdin. Additionally, 46the `CONSUL_INDEX` environment variable will be set to the Consul index 47Anything written to stdout is logged. 48 49Here is an example configuration, where `handler_type` is optionally set to 50`script`: 51 52```javascript 53{ 54 "type": "key", 55 "key": "foo/bar/baz", 56 "handler_type": "script", 57 "args": ["/usr/bin/my-service-handler.sh", "-redis"] 58} 59``` 60 61Prior to Consul 1.0, watches used a single `handler` field to define the command to run, and 62would always run in a shell. In Consul 1.0, the `args` array was added so that handlers can be 63run without a shell. The `handler` field is deprecated, and you should include the shell in 64the `args` to run under a shell, eg. `"args": ["sh", "-c", "..."]`. 65 66### HTTP endpoint 67 68An HTTP handler sends an HTTP request when a watch is invoked. The JSON invocation info is sent 69as a payload along the request. The response also contains the Consul index as a header named 70`X-Consul-Index`. 71 72The HTTP handler can be configured by setting `handler_type` to `http`. Additional handler options 73are set using `http_handler_config`. The only required parameter is the `path` field which specifies 74the URL to the HTTP endpoint. Consul uses `POST` as the default HTTP method, but this is also configurable. 75Other optional fields are `header`, `timeout` and`tls_skip_verify`. The watch invocation data is 76always sent as a JSON payload. 77 78Here is an example configuration: 79 80```javascript 81{ 82 "type": "key", 83 "key": "foo/bar/baz", 84 "handler_type": "http", 85 "http_handler_config": { 86 "path":"https://localhost:8000/watch", 87 "method": "POST", 88 "header": {"x-foo":["bar", "baz"]}, 89 "timeout": "10s", 90 "tls_skip_verify": false 91 } 92} 93``` 94 95## Global Parameters 96 97In addition to the parameters supported by each option type, there 98are a few global parameters that all watches support: 99 100* `datacenter` - Can be provided to override the agent's default datacenter. 101* `token` - Can be provided to override the agent's default ACL token. 102* `args` - The handler subprocess and arguments to invoke when the data view updates. 103* `handler` - The handler shell command to invoke when the data view updates. 104 105## Watch Types 106 107The following types are supported. Detailed documentation on each is below: 108 109* [`key`](#key) - Watch a specific KV pair 110* [`keyprefix`](#keyprefix) - Watch a prefix in the KV store 111* [`services`](#services) - Watch the list of available services 112* [`nodes`](#nodes) - Watch the list of nodes 113* [`service`](#service)- Watch the instances of a service 114* [`checks`](#checks) - Watch the value of health checks 115* [`event`](#event) - Watch for custom user events 116 117 118### <a name="key"></a>Type: key 119 120The "key" watch type is used to watch a specific key in the KV store. 121It requires that the "key" parameter be specified. 122 123This maps to the `/v1/kv/` API internally. 124 125Here is an example configuration: 126 127```javascript 128{ 129 "type": "key", 130 "key": "foo/bar/baz", 131 "args": ["/usr/bin/my-service-handler.sh", "-redis"] 132} 133``` 134 135Or, using the watch command: 136 137 $ consul watch -type=key -key=foo/bar/baz /usr/bin/my-key-handler.sh 138 139An example of the output of this command: 140 141```javascript 142{ 143 "Key": "foo/bar/baz", 144 "CreateIndex": 1793, 145 "ModifyIndex": 1793, 146 "LockIndex": 0, 147 "Flags": 0, 148 "Value": "aGV5", 149 "Session": "" 150} 151``` 152 153### <a name="keyprefix"></a>Type: keyprefix 154 155The "keyprefix" watch type is used to watch a prefix of keys in the KV store. 156It requires that the "prefix" parameter be specified. This watch 157returns *all* keys matching the prefix whenever *any* key matching the prefix 158changes. 159 160This maps to the `/v1/kv/` API internally. 161 162Here is an example configuration: 163 164```javascript 165{ 166 "type": "keyprefix", 167 "prefix": "foo/", 168 "args": ["/usr/bin/my-service-handler.sh", "-redis"] 169} 170``` 171 172Or, using the watch command: 173 174 $ consul watch -type=keyprefix -prefix=foo/ /usr/bin/my-prefix-handler.sh 175 176An example of the output of this command: 177 178```javascript 179[ 180 { 181 "Key": "foo/bar", 182 "CreateIndex": 1796, 183 "ModifyIndex": 1796, 184 "LockIndex": 0, 185 "Flags": 0, 186 "Value": "TU9BUg==", 187 "Session": "" 188 }, 189 { 190 "Key": "foo/baz", 191 "CreateIndex": 1795, 192 "ModifyIndex": 1795, 193 "LockIndex": 0, 194 "Flags": 0, 195 "Value": "YXNkZg==", 196 "Session": "" 197 }, 198 { 199 "Key": "foo/test", 200 "CreateIndex": 1793, 201 "ModifyIndex": 1793, 202 "LockIndex": 0, 203 "Flags": 0, 204 "Value": "aGV5", 205 "Session": "" 206 } 207] 208``` 209 210### <a name="services"></a>Type: services 211 212The "services" watch type is used to watch the list of available 213services. It has no parameters. 214 215This maps to the `/v1/catalog/services` API internally. 216 217An example of the output of this command: 218 219```javascript 220{ 221 "consul": [], 222 "redis": [], 223 "web": [] 224} 225``` 226 227### <a name="nodes"></a>Type: nodes 228 229The "nodes" watch type is used to watch the list of available 230nodes. It has no parameters. 231 232This maps to the `/v1/catalog/nodes` API internally. 233 234An example of the output of this command: 235 236```javascript 237[ 238 { 239 "Node": "nyc1-consul-1", 240 "Address": "192.241.159.115" 241 }, 242 { 243 "Node": "nyc1-consul-2", 244 "Address": "192.241.158.205" 245 }, 246 { 247 "Node": "nyc1-consul-3", 248 "Address": "198.199.77.133" 249 }, 250 { 251 "Node": "nyc1-worker-1", 252 "Address": "162.243.162.228" 253 }, 254 { 255 "Node": "nyc1-worker-2", 256 "Address": "162.243.162.226" 257 }, 258 { 259 "Node": "nyc1-worker-3", 260 "Address": "162.243.162.229" 261 } 262] 263``` 264 265### <a name="service"></a>Type: service 266 267The "service" watch type is used to monitor the providers 268of a single service. It requires the "service" parameter 269and optionally takes the parameters "tag" and "passingonly". 270The "tag" parameter will filter by tag, and "passingonly" is 271a boolean that will filter to only the instances passing all 272health checks. 273 274This maps to the `/v1/health/service` API internally. 275 276Here is an example configuration: 277 278```javascript 279{ 280 "type": "service", 281 "service": "redis", 282 "args": ["/usr/bin/my-service-handler.sh", "-redis"] 283} 284``` 285 286Or, using the watch command: 287 288 $ consul watch -type=service -service=redis /usr/bin/my-service-handler.sh 289 290An example of the output of this command: 291 292```javascript 293[ 294 { 295 "Node": { 296 "Node": "foobar", 297 "Address": "10.1.10.12" 298 }, 299 "Service": { 300 "ID": "redis", 301 "Service": "redis", 302 "Tags": null, 303 "Port": 8000 304 }, 305 "Checks": [ 306 { 307 "Node": "foobar", 308 "CheckID": "service:redis", 309 "Name": "Service 'redis' check", 310 "Status": "passing", 311 "Notes": "", 312 "Output": "", 313 "ServiceID": "redis", 314 "ServiceName": "redis" 315 }, 316 { 317 "Node": "foobar", 318 "CheckID": "serfHealth", 319 "Name": "Serf Health Status", 320 "Status": "passing", 321 "Notes": "", 322 "Output": "", 323 "ServiceID": "", 324 "ServiceName": "" 325 } 326 ] 327 } 328] 329``` 330 331### <a name="checks"></a>Type: checks 332 333The "checks" watch type is used to monitor the checks of a given 334service or those in a specific state. It optionally takes the "service" 335parameter to filter to a specific service or the "state" parameter to 336filter to a specific state. By default, it will watch all checks. 337 338This maps to the `/v1/health/state/` API if monitoring by state 339or `/v1/health/checks/` if monitoring by service. 340 341An example of the output of this command: 342 343```javascript 344[ 345 { 346 "Node": "foobar", 347 "CheckID": "service:redis", 348 "Name": "Service 'redis' check", 349 "Status": "passing", 350 "Notes": "", 351 "Output": "", 352 "ServiceID": "redis", 353 "ServiceName": "redis" 354 } 355] 356``` 357 358### <a name="event"></a>Type: event 359 360The "event" watch type is used to monitor for custom user 361events. These are fired using the [consul event](/docs/commands/event.html) command. 362It takes only a single optional "name" parameter which restricts 363the watch to only events with the given name. 364 365This maps to the `v1/event/list` API internally. 366 367Here is an example configuration: 368 369```javascript 370{ 371 "type": "event", 372 "name": "web-deploy", 373 "args": ["/usr/bin/my-service-handler.sh", "-web-deploy"] 374} 375``` 376 377Or, using the watch command: 378 379 $ consul watch -type=event -name=web-deploy /usr/bin/my-deploy-handler.sh -web-deploy 380 381An example of the output of this command: 382 383```javascript 384[ 385 { 386 "ID": "f07f3fcc-4b7d-3a7c-6d1e-cf414039fcee", 387 "Name": "web-deploy", 388 "Payload": "MTYwOTAzMA==", 389 "NodeFilter": "", 390 "ServiceFilter": "", 391 "TagFilter": "", 392 "Version": 1, 393 "LTime": 18 394 }, 395 ... 396] 397``` 398 399To fire a new `web-deploy` event the following could be used: 400 401 $ consul event -name=web-deploy 1609030 402