gortiz opened a new pull request, #20105:
URL: https://github.com/apache/pinot/pull/20105
## Summary
This PR adds review principle C3.25 to `kb/code-review-principles.md` and
points to it from `AGENTS.md`. The principle tells authors and reviewers to
estimate the ZooKeeper cost of a Helix change listener that runs on every
server or broker.
## Background
Helix prefetch is on by default. On each change, every listening process
reads all znodes under the watched path. A ZooKeeper event does not carry the
new data, so Helix builds the full list again for each callback.
```
1 InstanceConfig change
└─► L processes with the listener (servers + brokers)
└─► each process reads N InstanceConfigs
= L × N ZK reads per change, on the Helix event thread
```
A burst of changes, for example a scale-down, pays this cost for each
change. In a cluster with hundreds of instances, one change can cost hundreds
of thousands of reads.
The cost is not always a reason to remove the listener. Sometimes every
instance needs it. The principle gives two options:
1. If only the query path needs the data, read it on the broker and send it
with the request.
2. If every instance needs the listener, disable prefetch with
`@PreFetch(enabled = false)`. Then read only the znode in
`NotificationContext.getPathChanged()`. Do a full read only on `INIT` or on a
child change.
## Changes
- `kb/code-review-principles.md`: new MAJOR principle C3.25 in chapter 3,
after C3.16, with a BAD/GOOD example. The summary table changes from 167 to 168
principles.
- `AGENTS.md`: one line in "Change guidance". The line asks agents to
estimate the ZooKeeper cost before they add such a listener, and it points to
C3.25.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
