dong he created ZOOKEEPER-5069:
----------------------------------
Summary: Add AdminServer command to query watch registration
details
Key: ZOOKEEPER-5069
URL: https://issues.apache.org/jira/browse/ZOOKEEPER-5069
Project: ZooKeeper
Issue Type: New Feature
Components: server
Affects Versions: 3.10.0
Reporter: dong he
Attachments: watch_details_design_document_en.md
Motivation
ZooKeeper currently provides the watches, watches_by_path, and watch_summary
AdminServer commands. They expose session IDs, paths, or aggregate data only;
they do not provide a per-watch view that can be correlated with current client
connection information, including client IP address, port, connection state,
and Watch type.
This makes it difficult to diagnose Watch registrations on a ZooKeeper Server.
Proposed Change
Add a read-only AdminServer command named watch_details, with the four-letter
command alias wchd.
Endpoints:
- GET /commands/watch_details
- GET /commands/wchd
The command returns Watch registrations maintained by the current ZooKeeper
Server only. It does not aggregate data across the ensemble, so results can
differ when queried from a Leader, Follower, or Observer.
Optional Query Parameters
- path: exact znode path match
- session_id: exact Session ID match; decimal and hexadecimal input are
supported
- client_ip: exact client IP match
- limit: maximum number of returned entries; default 100, range 1 through 1000
Multiple parameters use AND semantics.
Response and Behavior
Each returned entry contains the watched path, hexadecimal Session ID, client
IP and port, watch kind (data or children), watch mode (standard, persistent,
or persistent_recursive), current connection establishment time, session
timeout, and whether the connection uses TLS.
The command returns only Watches associated with active, non-stale ServerCnxn
instances. It does not return total_count, does not guarantee ordering, and
uses limit + 1 internally to determine whether the response is truncated.
The command is intentionally exposed without an additional AdminServer
authentication or ACL restriction.
Compatibility
This is an additive, read-only AdminServer command. The IWatchManager extension
uses a default method to preserve binary compatibility for existing third-party
IWatchManager implementations. A custom WatchManager that does not implement
the detailed query returns HTTP 501.
Performance
The command applies filters while traversing Watch registrations, stops after
limit + 1 matches, does not build a full Watcher-to-Path reverse index, does
not calculate total_count, and does not modify the Watch registration or
trigger hot path.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
