AddThroughputBucketSupport #46042

xinlian12 · 2025-07-16T20:23:41Z

Description

Added throughput bucket support

Public API

Using throughput bucket only:

        ThroughputControlGroupConfig groupConfig =
            new ThroughputControlGroupConfigBuilder()
                .groupName("group-" + UUID.randomUUID())
                .throughputBucket(1)
                .build();
        container.enableServerThroughputControlGroup(groupConfig);

Using priorityLevel only:

        ThroughputControlGroupConfig groupConfig =
            new ThroughputControlGroupConfigBuilder()
                .groupName("group-" + UUID.randomUUID())
                .priorityLevel(PriorityLevel.LOW)
                .build();
        container.enableServerThroughputControlGroup(groupConfig);

Using priorityLevel and throughputBucket together:

        ThroughputControlGroupConfig groupConfig =
            new ThroughputControlGroupConfigBuilder()
                .groupName("group-" + UUID.randomUUID())
                .priorityLevel(PriorityLevel.LOW)
                .throughputBucket(1)
                .build();
        container.enableServerThroughputControlGroup(groupConfig);

UML

(Note: LocalThroughputControlGroupController & GlobalThroughputControlGroupController are removed from the graph for simplicity)

Sequence flow

Throughput control store flow:

SDK Throughput control store flow:

Server Throughput control store flow:

Diagnostics:

New requestTCG and requestTCGConfig added:

E2E testing:

github-actions · 2025-07-16T21:20:27Z

API Change Check

APIView identified API level changes in this PR and created the following API reviews

com.azure:azure-cosmos

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/ThroughputControlGroupConfigBuilder.java

FabianMeiswinkel · 2025-07-17T13:10:45Z

...s/src/main/java/com/azure/cosmos/implementation/directconnectivity/rntbd/RntbdConstants.java

@@ -598,7 +598,8 @@ public enum RntbdRequestHeader implements RntbdHeader {
        SDKSupportedCapabilities((short) 0x00A2, RntbdTokenType.ULong, false),
        ChangeFeedWireFormatVersion((short) 0x00B2, RntbdTokenType.String, false),
        PriorityLevel((short) 0x00BF, RntbdTokenType.Byte, false),
-        GlobalDatabaseAccountName((short) 0x00CE, RntbdTokenType.String, false);
+        GlobalDatabaseAccountName((short) 0x00CE, RntbdTokenType.String, false),
+        ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false); //TODO: does the throughput bucket supported in thin client


Thin client is a good question. Also GAteway mode is relevant - we would rely on ComputeGateway and Routing Gateway to pass through the header. I would expect this to work in thin client because the rntbd body is passed through opaquely.

will double check the behavior here

FabianMeiswinkel

LGTM - thanks for the well structured API and the great PR description - really helped to review the PR!

Copilot

Pull Request Overview

This PR introduces throughput bucket support to the Azure Cosmos DB Java SDK, enabling server-side throughput control functionality. The key change is adding support for throughput buckets alongside the existing priority level controls, with a new API for enabling server throughput control groups.

Key changes:

Adds throughput bucket support to ThroughputControlGroupConfig and related APIs
Introduces server throughput control store and controllers for bucket-based throughput management
Refactors existing SDK throughput control classes into a dedicated sdk package structure
Adds comprehensive test coverage for the new server throughput control functionality

Reviewed Changes

Copilot reviewed 80 out of 80 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`ThroughputControlGroupConfig.java`	Adds throughput bucket field and getter method
`ThroughputControlGroupConfigBuilder.java`	Adds throughput bucket setter with validation
`CosmosAsyncContainer.java`	Adds `enableServerThroughputControlGroup` method
Server throughput control classes	New implementation for server-side throughput bucket control
SDK throughput control refactor	Moves existing SDK throughput control to dedicated package
Test files	Comprehensive test coverage for new functionality

Comments suppressed due to low confidence (2)

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/throughputControl/sdk/ThroughputRequestThrottler.java:23

Unused import statement should be removed. The UUID import is not used anywhere in this file.

import java.util.concurrent.ConcurrentHashMap;

...smos/implementation/throughputControl/server/controller/ServerThroughputGroupController.java

Copilot · 2025-07-29T06:05:58Z

...s/src/main/java/com/azure/cosmos/implementation/directconnectivity/rntbd/RntbdConstants.java

@@ -598,7 +598,8 @@ public enum RntbdRequestHeader implements RntbdHeader {
        SDKSupportedCapabilities((short) 0x00A2, RntbdTokenType.ULong, false),
        ChangeFeedWireFormatVersion((short) 0x00B2, RntbdTokenType.String, false),
        PriorityLevel((short) 0x00BF, RntbdTokenType.Byte, false),
-        GlobalDatabaseAccountName((short) 0x00CE, RntbdTokenType.String, false);
+        GlobalDatabaseAccountName((short) 0x00CE, RntbdTokenType.String, false),
+        ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false); //TODO: does the throughput bucket supported in thin client


The TODO comment should be resolved or moved to a proper issue tracker. Comments like this should not remain in production code.

Suggested change

ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false); //TODO: does the throughput bucket supported in thin client

ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false); // Throughput bucket is supported in thin client

will remove this comment later once confirmed the behavior

sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/rx/FullFidelityChangeFeedTest.java

sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/rx/ClientRetryPolicyE2ETests.java

FabianMeiswinkel · 2025-07-29T19:25:20Z

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/ThroughputControlGroupConfig.java

+     * Get the throughput bucket.
+     * <p>
+     * For more information about throughput bucket please visit
+     * <a href="https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/throughput-buckets?tabs=dotnet">Throughput buckets in Azure Cosmos DB</a>


The doc should be extended for Java (min sdk versiona nd how to use the feature - would be better to refernece the java sample than .net - but can be done in separate PR)

FabianMeiswinkel

LGTM - Thx

annie-mac added 3 commits July 16, 2025 10:04

add throughput bucket support

152414b

reconstruct test structure for test

0cbf74d

refactor

eb72c43

github-actions bot added the Cosmos label Jul 16, 2025

refactor

39d69bd

FabianMeiswinkel reviewed Jul 17, 2025

View reviewed changes

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/ThroughputControlGroupConfigBuilder.java Outdated Show resolved Hide resolved

FabianMeiswinkel reviewed Jul 17, 2025

View reviewed changes

FabianMeiswinkel approved these changes Jul 17, 2025

View reviewed changes

annie-mac added 7 commits July 17, 2025 10:45

fix tests

6e3025d

refactor

708dce1

merge from master and resolve conflicts

86bbe8e

change

763f754

Merge branch 'main' into addThroughputBucketSupport

472109d

change

c713a38

add throughput control group config in diagnostics

c965815

xinlian12 force-pushed the addThroughputBucketSupport branch from fa8285b to c965815 Compare July 29, 2025 05:42

fix compile

4d895ee

xinlian12 marked this pull request as ready for review July 29, 2025 06:05

Copilot AI review requested due to automatic review settings July 29, 2025 06:05

xinlian12 requested review from kirankumarkolli and a team as code owners July 29, 2025 06:05

xinlian12 changed the title ~~AddThroughputBucketSupport - [NO REVIEW]~~ AddThroughputBucketSupport Jul 29, 2025

Copilot AI reviewed Jul 29, 2025

View reviewed changes

annie-mac added 2 commits July 29, 2025 09:13

resolve comments

b84e992

Merge branch 'main' into addThroughputBucketSupport

1d9d4d8

FabianMeiswinkel reviewed Jul 29, 2025

View reviewed changes

FabianMeiswinkel approved these changes Jul 29, 2025

View reviewed changes

update javadoc

e934d03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

AddThroughputBucketSupport #46042

AddThroughputBucketSupport #46042

Uh oh!

xinlian12 commented Jul 16, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 16, 2025 •

edited

Loading

Uh oh!

Uh oh!

FabianMeiswinkel Jul 17, 2025

Uh oh!

xinlian12 Jul 17, 2025

Uh oh!

FabianMeiswinkel left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Jul 29, 2025

Uh oh!

xinlian12 Jul 29, 2025

Uh oh!

Uh oh!

Uh oh!

FabianMeiswinkel Jul 29, 2025

Uh oh!

FabianMeiswinkel left a comment

Uh oh!

Uh oh!

	ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false); //TODO: does the throughput bucket supported in thin client
	ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false); // Throughput bucket is supported in thin client

AddThroughputBucketSupport #46042

Are you sure you want to change the base?

AddThroughputBucketSupport #46042

Uh oh!

Conversation

xinlian12 commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Public API

UML

Sequence flow

Diagnostics:

E2E testing:

Uh oh!

github-actions bot commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

Uh oh!

FabianMeiswinkel Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

xinlian12 Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

FabianMeiswinkel left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key changes:

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

xinlian12 Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

FabianMeiswinkel Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

FabianMeiswinkel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

xinlian12 commented Jul 16, 2025 •

edited

Loading

github-actions bot commented Jul 16, 2025 •

edited

Loading