Using Consul Watch to Monitor Changes

When your configuration lives in Consul’s Key/Value store, you need an automated way to detect updates and react. Consul Watch is a built-in feature that continuously observes changes—whether in KV entries, service registration, node health, or custom events—and triggers handlers when updates occur.

The image is a slide explaining how to monitor KV changes using the "Watch" feature in Consul, highlighting its built-in capabilities and handler options. It mentions that handlers can invoke commands or hit HTTP endpoints when changes are detected.

Consul Watch runs entirely inside the agent—no extra binaries or plugins required. When a watched resource changes, you can:

Log the event for downstream processing by log-collection tools.
Execute a shell command or custom script via the script handler.
Send an HTTP request to an API, webhook, or service endpoint via the http handler.

Note

Ensure your handler scripts have executable permissions (e.g., chmod +x /path/to/script.sh), and verify that the Consul agent user can invoke them.

Next, let’s review the watch types available out of the box.

The image lists different types of "Watch" options for monitoring KV changes, including key, keyprefix, services, nodes, service, checks, and event, each with a brief description.

Watch Type	Description
key	Watch a single key-value entry
keyprefix	Watch all keys under a specified prefix
services	Monitor the list of registered services
nodes	Monitor the list of cluster nodes
service	Monitor instances of a specific service
checks	Monitor the state of health checks
event	Watch for custom user-triggered events

Under the hood, Consul Watch leverages the blocking query feature of the HTTP API. You can configure and run watches in two ways:

In the agent’s JSON configuration file
With the consul watch CLI command

The image is a slide titled "Monitor KV Changes Using Watch," explaining how watches are implemented using blocking queries in the Consul API, with details on configuration and behavior. It includes bullet points on adding watches to an agent configuration and using the `consul watch` command.

1. Configure a Watch in the Agent Configuration

Edit your Consul agent’s JSON config (e.g., /etc/consul.d/agent.json) and add a watches block:

{
  "watches": [
    {
      "type": "key",
      "key": "prod/database/mysql",
      "handler_type": "script",
      "args": ["/usr/bin/update_database_creds.sh"]
    }
  ]
}

After saving, restart or reload the Consul agent:

consul reload

2. Start a Watch from the Command Line

You can also spin up a watch on the fly without touching config files:

consul watch -type=key \
  -key=prod/database/mysql \
  /usr/bin/update_database_creds.sh

Now, whenever the prod/database/mysql KV entry changes, Consul Watch executes your script—automatically rolling out updated credentials to your application.

Watch Video

Watch video content

1. Configure a Watch in the Agent Configuration

2. Start a Watch from the Command Line

Related Resources

Watch Video