docs(ADR): extends the fractional operator to support up to .001% distributions #1800
Conversation
…allocations Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
✅ Deploy Preview for polite-licorice-3db33c ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dosubot
bot
added
the
size:L
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @beeme1mr, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request introduces a significant enhancement to the fractional traffic allocation mechanism. It aims to provide much finer-grained control over traffic distribution, enabling precise sub-percent allocations critical for high-throughput environments, A/B testing, and canary deployments. The changes are designed to be backward-compatible with the existing API while improving reliability through robust error handling and validation.
Highlights
- Enhanced Fractional Operator Precision: The fractional operator now supports traffic allocation down to 0.001% granularity, achieved by increasing the internal bucket count from 100 to 100,000.
- API Compatibility Maintained: The existing weight-based API remains unchanged, ensuring backwards compatibility for current configurations.
- Robust Edge Case Handling: New logic addresses various edge cases, including minimum allocation guarantees for variants with positive weights, management of excess buckets, and validation for weight sum overflows.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This is a well-written and thorough ADR that clearly outlines the proposal to enhance the fractional operator. The move to a 100,000-bucket system with a minimum allocation guarantee is a great improvement for fine-grained traffic control. My review includes a few suggestions to address potential issues with implementation details, particularly around ensuring deterministic behavior and handling all allocation scenarios correctly. These points focus on preventing bucket deficits and ensuring cross-language consistency in sorting and arithmetic.
| return nil | ||
| } | ||
|
|
||
| func calculateBucketAllocations(variants []fractionalEvaluationVariant, totalWeight int) []bucketAllocation { |
There was a problem hiding this comment.
The calculateBucketAllocations function handles the case where the sum of allocated buckets exceeds bucketCount (excess > 0). However, it doesn't account for the opposite scenario: when the total allocated buckets is less than bucketCount due to rounding down during the proportional calculation (int(...)). If a deficit of buckets occurs, some hash values in distributeValue will not fall into any variant's bucket range, causing the function to incorrectly return an empty string. The ADR should specify how to handle bucket deficits, for instance, by distributing the remaining buckets among the variants (e.g., starting with the largest ones) to ensure the total is exactly bucketCount.
There was a problem hiding this comment.
Properly supporting guaranteed bucketing may add more complexity than I'd like. I'm sure I can address this issue but I'd like feedback on if it's worth supporting this at all.
The reason I added this is to avoid configurations like ["variant-a", 1], ["variant-b", 1000000], resulting in zero evaluations returning variant-a. You could argue it's a misconfiguration, but it may not be obvious the the user.
| When minimum allocations cause the total to exceed 100,000 buckets, excess buckets are removed from the variant with the largest allocation. | ||
| This approach: |
There was a problem hiding this comment.
The description of how excess buckets are handled is slightly inconsistent. This section states that excess buckets are removed from 'the variant with the largest allocation' (singular), while the 'Edge Case Handling' section on line 127 refers to it as 'Excess distributed fairly among largest variants' (plural). The code example shows a sequential removal process. For clarity and consistency, I suggest refining the description to accurately reflect the implementation, for example: 'Excess buckets are removed sequentially from variants with the largest allocations, starting with the largest, until the total bucket count is exactly 100,000.'
docs/architecture-decisions/high-precision-fractional-bucketing.md
Outdated
Show resolved
Hide resolved
| - Support weight values up to a reasonable maximum that works across multiple languages | ||
| - Maintain current performance characteristics | ||
| - Prevent users from being moved between buckets when only distribution percentages change | ||
| - Guarantee that any variant with weight > 0 receives some traffic allocation |
There was a problem hiding this comment.
I went back and forth on this. It isn't necessary if the flag is configured properly but I'm afraid that it wouldn't be that obvious that there's a misconfiguration. This basically prevents 0% distribution if a weight is defined.
…g.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
…g.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
1 participant
This PR
Notes
Addresses a limitation of the current fractional operator that prevents sub-percent traffic allocations. In high-throughput services, 1% of traffic may represent a significant number of requests.