[jira] [Created] (ZOOKEEPER-5069) Add AdminServer command to query watch registration details

["dong he (Jira)" <ji...@apache.org>]

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)