Skip to content

Commit 39a7a66

Browse files
xinlian12Annie Liangannie-macannie-macannie-mac
authored
ThroughputControl-Global (Azure#19183)
* ThroughputControl-Global Co-authored-by: Annie Liang <xinlian@microsoft.com> Co-authored-by: annie-mac <annie-mac@s-pkges.redmond.corp.microsoft.com> Co-authored-by: annie-mac <annie-mac@MININT-3IC6M7V.redmond.corp.microsoft.com> Co-authored-by: annie-mac <annie-mac@Gurpreet.fareast.corp.microsoft.com>
1 parent de1c5db commit 39a7a66

File tree

56 files changed

+2339
-838
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+2339
-838
lines changed

‎sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/BridgeInternal.java‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@
3636
import com.azure.cosmos.implementation.query.QueryInfo;
3737
import com.azure.cosmos.implementation.query.metrics.ClientSideMetrics;
3838
import com.azure.cosmos.implementation.routing.PartitionKeyInternal;
39-
import com.azure.cosmos.implementation.throughputControl.ThroughputControlMode;
4039
import com.azure.cosmos.models.CosmosItemResponse;
4140
import com.azure.cosmos.models.CosmosStoredProcedureProperties;
4241
import com.azure.cosmos.models.FeedResponse;
@@ -796,18 +795,13 @@ public static List<PatchOperation> getPatchOperationsFromCosmosPatch(CosmosPatch
796795
return cosmosPatchOperations.getPatchOperations();
797796
}
798797

799-
@Warning(value = INTERNAL_USE_ONLY_WARNING)
800-
public static ThroughputControlMode getThroughputControlMode(ThroughputControlGroup throughputControlGroup) {
801-
return throughputControlGroup.getControlMode();
802-
}
803-
804798
@Warning(value = INTERNAL_USE_ONLY_WARNING)
805799
public static SqlQuerySpec getOfferQuerySpecFromResourceId(CosmosAsyncContainer container, String resourceId) {
806800
return container.getDatabase().getOfferQuerySpecFromResourceId(resourceId);
807801
}
808802

809803
@Warning(value = INTERNAL_USE_ONLY_WARNING)
810-
public static CosmosAsyncContainer getTargetContainerFromThroughputControlGroup(ThroughputControlGroup controlGroup) {
811-
return controlGroup.getTargetContainer();
804+
public static CosmosAsyncContainer getControlContainerFromThroughputGlobalControlConfig(GlobalThroughputControlConfig globalControlConfig) {
805+
return globalControlConfig.getControlContainer();
812806
}
813807
}

‎sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncClient.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
import com.azure.cosmos.implementation.HttpConstants;
1616
import com.azure.cosmos.implementation.TracerProvider;
1717
import com.azure.cosmos.implementation.directconnectivity.rntbd.RntbdMetrics;
18+
import com.azure.cosmos.implementation.throughputControl.config.ThroughputControlGroupInternal;
1819
import com.azure.cosmos.models.CosmosDatabaseProperties;
1920
import com.azure.cosmos.models.CosmosDatabaseRequestOptions;
2021
import com.azure.cosmos.models.CosmosDatabaseResponse;
@@ -23,6 +24,7 @@
2324
import com.azure.cosmos.models.ModelBridgeInternal;
2425
import com.azure.cosmos.models.SqlQuerySpec;
2526
import com.azure.cosmos.models.ThroughputProperties;
27+
import com.azure.cosmos.util.Beta;
2628
import com.azure.cosmos.util.CosmosPagedFlux;
2729
import com.azure.cosmos.util.UtilBridgeInternal;
2830
import io.micrometer.core.instrument.MeterRegistry;
@@ -471,11 +473,23 @@ TracerProvider getTracerProvider(){
471473
*
472474
* @param group Throughput control group going to be enabled.
473475
*/
474-
void enableThroughputControlGroup(ThroughputControlGroup group) {
476+
void enableThroughputControlGroup(ThroughputControlGroupInternal group) {
475477
checkNotNull(group, "Throughput control group cannot be null");
476478
this.asyncDocumentClient.enableThroughputControlGroup(group);
477479
}
478480

481+
/**
482+
* Create global throughput control config builder which will be used to build {@link GlobalThroughputControlConfig}.
483+
*
484+
* @param databaseId The database id of the control container.
485+
* @param containerId The container id of the control container.
486+
* @return A {@link GlobalThroughputControlConfigBuilder}.
487+
*/
488+
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
489+
public GlobalThroughputControlConfigBuilder createGlobalThroughputControlConfigBuilder(String databaseId, String containerId) {
490+
return new GlobalThroughputControlConfigBuilder(this, databaseId, containerId);
491+
}
492+
479493
private CosmosPagedFlux<CosmosDatabaseProperties> queryDatabasesInternal(SqlQuerySpec querySpec, CosmosQueryRequestOptions options){
480494
return UtilBridgeInternal.createCosmosPagedFlux(pagedFluxOptions -> {
481495
pagedFluxOptions.setTracerInformation(this.tracerProvider, "queryDatabases", this.serviceEndpoint, null);

‎sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncContainer.java‎

Lines changed: 20 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@
2121
import com.azure.cosmos.implementation.batch.BatchExecutor;
2222
import com.azure.cosmos.implementation.batch.BulkExecutor;
2323
import com.azure.cosmos.implementation.query.QueryInfo;
24-
import com.azure.cosmos.implementation.throughputControl.ThroughputControlMode;
24+
import com.azure.cosmos.implementation.throughputControl.config.ThroughputControlGroupFactory;
25+
import com.azure.cosmos.implementation.throughputControl.config.GlobalThroughputControlGroup;
26+
import com.azure.cosmos.implementation.throughputControl.config.LocalThroughputControlGroup;
2527
import com.azure.cosmos.models.CosmosChangeFeedRequestOptions;
2628
import com.azure.cosmos.models.CosmosConflictProperties;
2729
import com.azure.cosmos.models.CosmosContainerProperties;
@@ -51,7 +53,6 @@
5153
import static com.azure.core.util.FluxUtil.withContext;
5254
import static com.azure.cosmos.implementation.Utils.getEffectiveCosmosChangeFeedRequestOptions;
5355
import static com.azure.cosmos.implementation.Utils.setContinuationTokenAndMaxItemCount;
54-
import static com.azure.cosmos.implementation.guava25.base.Preconditions.checkArgument;
5556
import static com.azure.cosmos.implementation.guava25.base.Preconditions.checkNotNull;
5657

5758
/**
@@ -1436,65 +1437,35 @@ public Mono<List<FeedRange>> getFeedRanges() {
14361437
}
14371438

14381439
/**
1440+
* Enable the throughput control group with local control mode.
14391441
*
1440-
* @param groupName The throughput control group name.
1441-
* @param targetThroughput The target throughput for the control group.
1442+
* {@codesnippet com.azure.cosmos.throughputControl.localControl}
14421443
*
1443-
* @return A {@link ThroughputControlGroup}.
1444+
* @param groupConfig A {@link ThroughputControlGroupConfig}.
14441445
*/
14451446
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
1446-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, int targetThroughput) {
1447-
return this.enableThroughputLocalControlGroup(groupName, targetThroughput, false);
1447+
public void enableLocalThroughputControlGroup(ThroughputControlGroupConfig groupConfig) {
1448+
LocalThroughputControlGroup localControlGroup = ThroughputControlGroupFactory.createThroughputLocalControlGroup(groupConfig, this);
1449+
this.database.getClient().enableThroughputControlGroup(localControlGroup);
14481450
}
14491451

14501452
/**
1453+
* Enable the throughput control group with global control mode.
1454+
* The defined throughput limit will be shared across different clients.
14511455
*
1452-
* @param groupName The throughput control group name.
1453-
* @param targetThroughput The target throughput for the control group.
1454-
* @param isDefault Flag to indicate whether this group will be used as default.
1456+
* {@codesnippet com.azure.cosmos.throughputControl.globalControl}
14551457
*
1456-
* @return A {@link ThroughputControlGroup}.
1458+
* @param groupConfig The throughput control group configuration, see {@link GlobalThroughputControlGroup}.
1459+
* @param globalControlConfig The global throughput control configuration, see {@link GlobalThroughputControlConfig}.
14571460
*/
14581461
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
1459-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, int targetThroughput, boolean isDefault) {
1460-
return this.enableThroughputControlGroup(groupName, targetThroughput, null, ThroughputControlMode.LOCAL, isDefault);
1461-
}
1462-
1463-
/**
1464-
*
1465-
* @param groupName The throughput control group name.
1466-
* @param targetThroughputThreshold The target throughput threshold for the control group.
1467-
*
1468-
* @return A {@link ThroughputControlGroup}.
1469-
*/
1470-
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
1471-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, double targetThroughputThreshold) {
1472-
return this.enableThroughputLocalControlGroup(groupName, targetThroughputThreshold, false);
1473-
}
1474-
1475-
/**
1476-
*
1477-
* @param groupName The throughput control group name.
1478-
* @param targetThroughputThreshold The target throughput threshold for the control group.
1479-
* @param isDefault Flag to indicate whether this group will be used as default.
1480-
* @return A {@link ThroughputControlGroup}.
1481-
*/
1482-
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
1483-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, double targetThroughputThreshold, boolean isDefault) {
1484-
return this.enableThroughputControlGroup(groupName, null, targetThroughputThreshold, ThroughputControlMode.LOCAL, isDefault);
1485-
}
1486-
1487-
private ThroughputControlGroup enableThroughputControlGroup(
1488-
String groupName,
1489-
Integer targetThroughput,
1490-
Double targetThroughputThreshold,
1491-
ThroughputControlMode controlMode,
1492-
boolean isDefault) {
1462+
public void enableGlobalThroughputControlGroup(
1463+
ThroughputControlGroupConfig groupConfig,
1464+
GlobalThroughputControlConfig globalControlConfig) {
14931465

1494-
ThroughputControlGroup throughputControlGroup = new ThroughputControlGroup(
1495-
groupName, this, targetThroughput, targetThroughputThreshold, controlMode, isDefault);
1496-
this.database.getClient().enableThroughputControlGroup(throughputControlGroup);
1466+
GlobalThroughputControlGroup globalControlGroup =
1467+
ThroughputControlGroupFactory.createThroughputGlobalControlGroup(groupConfig, globalControlConfig, this);
14971468

1498-
return throughputControlGroup;
1469+
this.database.getClient().enableThroughputControlGroup(globalControlGroup);
14991470
}
15001471
}

‎sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosClient.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import com.azure.cosmos.models.CosmosQueryRequestOptions;
1111
import com.azure.cosmos.models.SqlQuerySpec;
1212
import com.azure.cosmos.models.ThroughputProperties;
13+
import com.azure.cosmos.util.Beta;
1314
import com.azure.cosmos.util.CosmosPagedFlux;
1415
import com.azure.cosmos.util.CosmosPagedIterable;
1516
import com.azure.cosmos.util.UtilBridgeInternal;
@@ -213,4 +214,16 @@ public void close() {
213214
private <T> CosmosPagedIterable<T> getCosmosPagedIterable(CosmosPagedFlux<T> cosmosPagedFlux) {
214215
return UtilBridgeInternal.createCosmosPagedIterable(cosmosPagedFlux);
215216
}
217+
218+
/**
219+
* Create global throughput control config builder which will be used to build {@link GlobalThroughputControlConfig}.
220+
*
221+
* @param databaseId The database id of the control container.
222+
* @param containerId The container id of the control container.
223+
* @return A {@link GlobalThroughputControlConfigBuilder}.
224+
*/
225+
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
226+
public GlobalThroughputControlConfigBuilder createGlobalThroughputControlConfigBuilder(String databaseId, String containerId) {
227+
return new GlobalThroughputControlConfigBuilder(this.asyncClientWrapper, databaseId, containerId);
228+
}
216229
}

‎sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosContainer.java‎

Lines changed: 13 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
package com.azure.cosmos;
55

6+
import com.azure.cosmos.implementation.throughputControl.config.GlobalThroughputControlGroup;
67
import com.azure.cosmos.models.CosmosChangeFeedRequestOptions;
78
import com.azure.cosmos.models.CosmosItemIdentity;
89
import com.azure.cosmos.models.CosmosItemResponse;
@@ -744,52 +745,28 @@ public List<FeedRange> getFeedRanges() {
744745
}
745746

746747
/**
748+
* Enable the throughput control group with local control mode.
747749
*
748-
* @param groupName The throughput control group name.
749-
* @param targetThroughput The target throughput for the control group.
750+
* {@codesnippet com.azure.cosmos.throughputControl.localControl}
750751
*
751-
* @return A {@link ThroughputControlGroup}.
752+
* @param groupConfig A {@link GlobalThroughputControlConfig}.
752753
*/
753754
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
754-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, int targetThroughput) {
755-
return this.asyncContainer.enableThroughputLocalControlGroup(groupName, targetThroughput);
755+
public void enableLocalThroughputControlGroup(ThroughputControlGroupConfig groupConfig) {
756+
this.asyncContainer.enableLocalThroughputControlGroup(groupConfig);
756757
}
757758

758759
/**
760+
* Enable the throughput control group with global control mode.
761+
* The defined throughput limit will be shared across different clients.
759762
*
760-
* @param groupName The throughput control group name.
761-
* @param targetThroughput The target throughput for the control group.
762-
* @param isDefault Flag to indicate whether this group will be used as default.
763+
* {@codesnippet com.azure.cosmos.throughputControl.globalControl}
763764
*
764-
* @return A {@link ThroughputControlGroup}.
765+
* @param groupConfig The throughput control group configuration, see {@link GlobalThroughputControlGroup}.
766+
* @param globalControlConfig The global throughput control configuration, see {@link GlobalThroughputControlConfig}.
765767
*/
766768
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
767-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, int targetThroughput, boolean isDefault) {
768-
return this.asyncContainer.enableThroughputLocalControlGroup(groupName, targetThroughput, isDefault);
769-
}
770-
771-
/**
772-
*
773-
* @param groupName The throughput control group name.
774-
* @param targetThroughputThreshold The target throughput threshold for the control group.
775-
*
776-
* @return A {@link ThroughputControlGroup}.
777-
*/
778-
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
779-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, double targetThroughputThreshold) {
780-
return this.asyncContainer.enableThroughputLocalControlGroup(groupName, targetThroughputThreshold);
781-
}
782-
783-
/**
784-
*
785-
* @param groupName The throughput control group name.
786-
* @param targetThroughputThreshold The target throughput threshold for the control group.
787-
* @param isDefault Flag to indicate whether this group will be used as default.
788-
*
789-
* @return A {@link ThroughputControlGroup}.
790-
*/
791-
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
792-
ThroughputControlGroup enableThroughputLocalControlGroup(String groupName, double targetThroughputThreshold, boolean isDefault) {
793-
return this.asyncContainer.enableThroughputLocalControlGroup(groupName, targetThroughputThreshold, isDefault);
769+
public void enableGlobalThroughputControlGroup(ThroughputControlGroupConfig groupConfig, GlobalThroughputControlConfig globalControlConfig) {
770+
this.asyncContainer.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);
794771
}
795772
}

‎sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/GlobalThroughputControlConfig.java‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT License.
3+
4+
package com.azure.cosmos;
5+
6+
import com.azure.cosmos.util.Beta;
7+
8+
import java.time.Duration;
9+
10+
/**
11+
* This configuration is used for throughput global control mode.
12+
* It contains configuration about the extra container which will track all the clients throughput usage for a certain control group.
13+
*/
14+
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
15+
public class GlobalThroughputControlConfig {
16+
private final CosmosAsyncContainer controlContainer;
17+
private final Duration controlItemRenewInterval;
18+
private final Duration controlItemExpireInterval;
19+
20+
GlobalThroughputControlConfig(
21+
CosmosAsyncContainer controlContainer,
22+
Duration controlItemRenewInterval,
23+
Duration controlItemExpireInterval) {
24+
25+
this.controlContainer = controlContainer;
26+
this.controlItemRenewInterval = controlItemRenewInterval;
27+
this.controlItemExpireInterval = controlItemExpireInterval;
28+
}
29+
30+
/**
31+
* Get the control container.
32+
* This is the container to track all other clients throughput usage.
33+
*
34+
* @return The {@link CosmosAsyncContainer}.
35+
*/
36+
CosmosAsyncContainer getControlContainer() {
37+
return controlContainer;
38+
}
39+
40+
/**
41+
* Get the control item renew interval.
42+
*
43+
* This controls how often the client is going to update the throughput usage of itself
44+
* and adjust its own throughput share based on the throughput usage of other clients.
45+
*
46+
* In short words, it controls how quickly the shared throughput will reload balanced across different clients.
47+
*
48+
* By default, it is 5s.
49+
*
50+
* @return The control item renew interval.
51+
*/
52+
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
53+
public Duration getControlItemRenewInterval() {
54+
return this.controlItemRenewInterval;
55+
}
56+
57+
/**
58+
* Get the control item expire interval.
59+
*
60+
* A client may be offline due to various reasons (being shutdown, network issue... ).
61+
* This controls how quickly we will detect the client has been offline and hence allow its throughput share to be taken by other clients.
62+
*
63+
* By default, it is 11s.
64+
*
65+
* @return The control item renew interval.
66+
*/
67+
@Beta(value = Beta.SinceVersion.V4_13_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
68+
public Duration getControlItemExpireInterval() {
69+
return this.controlItemExpireInterval;
70+
}
71+
}

0 commit comments

Comments
 (0)