[improve][client] PIP-468: Make Backoff jitter configurable#25669
Merged
merlimat merged 4 commits intoapache:masterfrom May 6, 2026
Merged
[improve][client] PIP-468: Make Backoff jitter configurable#25669merlimat merged 4 commits intoapache:masterfrom
merlimat merged 4 commits intoapache:masterfrom
Conversation
Adds a jitterPercent parameter to Backoff (default 10%) and exposes it on BackoffPolicy in the v5 client API. Jitter is now applied symmetrically as +/- jitterPercent/2 around the base delay and applied on the first call as well, instead of always shaving up to 10% off and skipping the initial delay.
lhotari
reviewed
May 5, 2026
Reject values above 100 in both Backoff.Builder and BackoffPolicy so the jitter factor stays in a sensible range. Add a test for the upper bound.
lhotari
approved these changes
May 5, 2026
…-7a00e5 # Conflicts: # pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/BackoffPolicy.java
…lTest next() now applies symmetric jitter on the first call, so it no longer returns the configured initial value exactly. The test only cares about configuration, so query the configured initial directly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The existing
Backoffclass always subtracts up to 10% jitter from the next delay, never adds, and skips jitter on the first invocation entirely (the result is clamped back up toinitialDelay). When many clients restart together, the first reconnect attempt fires at the exact configured initial delay — defeating the point of jitter. The jitter percentage was also hard-coded.Modifications
Backofftakes a configurablejitterPercent(default 10).±jitterPercent/2: the underlying delay is multiplied by a uniform random factor in[1 − jitterPercent/200, 1 + jitterPercent/200).Math.max(initial, …)clamp is removed; the returned value may now be slightly belowinitialDelayor slightly abovemaxBackoff.BackoffPolicy(v5 client API) gains ajitterPercentfield with awithJitter(double)helper. Existing factory methods seed the default jitter so callers are unaffected.The new
BackoffPolicy.jitterPercentis currently API-shape only: the connection-backoff path is still TODO'd inPulsarClientBuilderV5, and the redelivery-backoff path goes throughMultiplierRedeliveryBackoffwhich has no jitter support. Wiring is left for a follow-up.Verifying this change
This change added tests and can be verified as follows:
BackoffTest:jitterIsAppliedSymmetricallyOnFirstCall— across 500 resets verifies values both above and below the base, all within[base · 0.9, base · 1.1]forjitterPercent=20.jitterPercentZeroDisablesJitter— verifies the disable path returns the exact base.negativeJitterIsRejected— validation.jitterPercent(0)for deterministic exponential-progression and mandatory-stop checks.Does this pull request potentially affect one of the following parts:
org.apache.pulsar.common.util.Backoffandorg.apache.pulsar.client.api.v5.config.BackoffPolicygain new optional fields/builder methods. Existing callers are unaffected (defaults preserve the 10% magnitude, though the direction now spans±5%instead of−10%).