Skip to main content
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.
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 TypeDescription
keyWatch a single key-value entry
keyprefixWatch all keys under a specified prefix
servicesMonitor the list of registered services
nodesMonitor the list of cluster nodes
serviceMonitor instances of a specific service
checksMonitor the state of health checks
eventWatch 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:
  1. In the agent’s JSON configuration file
  2. 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