0
# Cluster Mode
1
2
Advanced functionality for distributed parameter flow control across multiple instances. `ParamFlowClusterConfig` enables coordinated parameter limits in cluster environments, allowing flow control decisions to be made globally across all service instances.
3
4
## Capabilities
5
6
### Cluster Configuration
7
8
Configures parameter flow rules for cluster mode operation with distributed coordination.
9
10
```java { .api }
11
/**
12
* Parameter flow rule config in cluster mode
13
*/
14
public class ParamFlowClusterConfig {
15
public ParamFlowClusterConfig();
16
}
17
```
18
19
**Usage Example:**
20
21
```java
22
// Create cluster configuration for distributed parameter flow control
23
ParamFlowClusterConfig clusterConfig = new ParamFlowClusterConfig()
24
.setFlowId(12345L)
25
.setThresholdType(ClusterRuleConstant.FLOW_THRESHOLD_GLOBAL)
26
.setFallbackToLocalWhenFail(true);
27
28
// Apply to parameter flow rule
29
ParamFlowRule rule = new ParamFlowRule("userService")
30
.setParamIdx(0)
31
.setCount(100) // 100 QPS across entire cluster
32
.setClusterMode(true)
33
.setClusterConfig(clusterConfig);
34
```
35
36
### Flow ID Configuration
37
38
Sets a global unique identifier for the parameter flow rule in cluster mode.
39
40
```java { .api }
41
/**
42
* Set global unique ID for cluster flow control
43
* @param flowId global unique identifier
44
* @return this config for method chaining
45
*/
46
public ParamFlowClusterConfig setFlowId(Long flowId);
47
48
/**
49
* Get the global unique ID
50
* @return flow ID
51
*/
52
public Long getFlowId();
53
```
54
55
**Usage Example:**
56
57
```java
58
// Configure unique flow ID for cluster coordination
59
ParamFlowClusterConfig config = new ParamFlowClusterConfig()
60
.setFlowId(1001L); // Unique ID across all cluster instances
61
62
// Different services can use different flow IDs
63
ParamFlowClusterConfig userServiceConfig = new ParamFlowClusterConfig()
64
.setFlowId(2001L);
65
66
ParamFlowClusterConfig productServiceConfig = new ParamFlowClusterConfig()
67
.setFlowId(2002L);
68
```
69
70
### Threshold Type Configuration
71
72
Specifies how the threshold should be calculated across cluster instances.
73
74
```java { .api }
75
/**
76
* Set threshold type (average by local value or global value)
77
* @param thresholdType the threshold calculation type
78
* @return this config for method chaining
79
*/
80
public ParamFlowClusterConfig setThresholdType(int thresholdType);
81
82
/**
83
* Get the threshold type
84
* @return threshold type
85
*/
86
public int getThresholdType();
87
```
88
89
**Usage Example:**
90
91
```java
92
import com.alibaba.csp.sentinel.slots.block.ClusterRuleConstant;
93
94
// Global threshold - 100 QPS across entire cluster
95
ParamFlowClusterConfig globalConfig = new ParamFlowClusterConfig()
96
.setFlowId(1001L)
97
.setThresholdType(ClusterRuleConstant.FLOW_THRESHOLD_GLOBAL);
98
99
// Average local threshold - 100 QPS per instance on average
100
ParamFlowClusterConfig avgLocalConfig = new ParamFlowClusterConfig()
101
.setFlowId(1002L)
102
.setThresholdType(ClusterRuleConstant.FLOW_THRESHOLD_AVG_LOCAL);
103
104
// Example: If you have 4 instances
105
// Global: Total 100 QPS shared across all 4 instances
106
// Average Local: Each instance can handle ~25 QPS (100/4)
107
```
108
109
### Fallback Configuration
110
111
Configures fallback behavior when cluster coordination fails.
112
113
```java { .api }
114
/**
115
* Set fallback behavior when cluster coordination fails
116
* @param fallbackToLocalWhenFail true to fallback to local rules
117
* @return this config for method chaining
118
*/
119
public ParamFlowClusterConfig setFallbackToLocalWhenFail(boolean fallbackToLocalWhenFail);
120
121
/**
122
* Check if fallback to local is enabled
123
* @return true if fallback is enabled
124
*/
125
public boolean isFallbackToLocalWhenFail();
126
```
127
128
**Usage Example:**
129
130
```java
131
// Enable fallback to local rules when cluster fails
132
ParamFlowClusterConfig resilientConfig = new ParamFlowClusterConfig()
133
.setFlowId(1001L)
134
.setFallbackToLocalWhenFail(true); // Fallback to local mode
135
136
// Disable fallback - pass all requests when cluster fails
137
ParamFlowClusterConfig strictConfig = new ParamFlowClusterConfig()
138
.setFlowId(1002L)
139
.setFallbackToLocalWhenFail(false); // Pass all when cluster unavailable
140
141
// Apply to rules
142
ParamFlowRule resilientRule = new ParamFlowRule("criticalService")
143
.setCount(50)
144
.setClusterMode(true)
145
.setClusterConfig(resilientConfig);
146
```
147
148
### Sampling Configuration
149
150
Configures statistical sampling for cluster coordination performance.
151
152
```java { .api }
153
/**
154
* Set sample count for cluster statistics
155
* @param sampleCount number of samples
156
* @return this config for method chaining
157
*/
158
public ParamFlowClusterConfig setSampleCount(int sampleCount);
159
160
/**
161
* Get the sample count
162
* @return sample count
163
*/
164
public int getSampleCount();
165
```
166
167
**Usage Example:**
168
169
```java
170
// Configure sampling for high-performance cluster coordination
171
ParamFlowClusterConfig config = new ParamFlowClusterConfig()
172
.setFlowId(1001L)
173
.setSampleCount(10); // Use 10 samples for statistics
174
175
// Higher sample count for more accurate statistics
176
ParamFlowClusterConfig preciseConfig = new ParamFlowClusterConfig()
177
.setFlowId(1002L)
178
.setSampleCount(20); // More samples, higher accuracy, more overhead
179
```
180
181
### Window Interval Configuration
182
183
Sets the time interval for statistical sliding windows in cluster mode.
184
185
```java { .api }
186
/**
187
* Set the time interval length of the statistic sliding window (in milliseconds)
188
* @param windowIntervalMs window interval in milliseconds
189
* @return this config for method chaining
190
*/
191
public ParamFlowClusterConfig setWindowIntervalMs(int windowIntervalMs);
192
193
/**
194
* Get the window interval
195
* @return window interval in milliseconds
196
*/
197
public int getWindowIntervalMs();
198
```
199
200
**Usage Example:**
201
202
```java
203
// Configure sliding window for cluster statistics
204
ParamFlowClusterConfig config = new ParamFlowClusterConfig()
205
.setFlowId(1001L)
206
.setWindowIntervalMs(1000); // 1-second sliding window
207
208
// Shorter window for more responsive flow control
209
ParamFlowClusterConfig responsiveConfig = new ParamFlowClusterConfig()
210
.setFlowId(1002L)
211
.setWindowIntervalMs(500); // 500ms window, more responsive
212
213
// Longer window for smoother flow control
214
ParamFlowClusterConfig smoothConfig = new ParamFlowClusterConfig()
215
.setFlowId(1003L)
216
.setWindowIntervalMs(2000); // 2-second window, smoother
217
```
218
219
## Complete Cluster Configuration Example
220
221
```java
222
import com.alibaba.csp.sentinel.slots.block.flow.param.*;
223
import com.alibaba.csp.sentinel.slots.block.ClusterRuleConstant;
224
225
// Configure comprehensive cluster parameter flow control
226
ParamFlowClusterConfig clusterConfig = new ParamFlowClusterConfig()
227
.setFlowId(12345L) // Unique cluster flow ID
228
.setThresholdType(ClusterRuleConstant.FLOW_THRESHOLD_GLOBAL) // Global threshold across cluster
229
.setFallbackToLocalWhenFail(true) // Fallback to local when cluster fails
230
.setSampleCount(10) // Use 10 samples for statistics
231
.setWindowIntervalMs(1000); // 1-second sliding window
232
233
// Create parameter flow rule with cluster configuration
234
ParamFlowRule clusterRule = new ParamFlowRule("userService")
235
.setParamIdx(0) // Monitor first parameter (userId)
236
.setCount(200) // 200 QPS across entire cluster
237
.setGrade(RuleConstant.FLOW_GRADE_QPS)
238
.setClusterMode(true) // Enable cluster mode
239
.setClusterConfig(clusterConfig); // Apply cluster configuration
240
241
// Exception items work in cluster mode too
242
ParamFlowItem vipException = ParamFlowItem.newItem("VIP_USER", 500);
243
clusterRule.setParamFlowItemList(Arrays.asList(vipException));
244
245
// Load the cluster rule
246
ParamFlowRuleManager.loadRules(Arrays.asList(clusterRule));
247
```
248
249
## Cluster Architecture
250
251
### Cluster Token Server
252
- Centralized coordination point for flow control decisions
253
- Maintains global statistics and token allocation
254
- Can be embedded or standalone
255
256
### Cluster Token Client
257
- Requests tokens from cluster server before processing requests
258
- Falls back to local mode when server is unavailable
259
- Caches decisions for performance
260
261
### Flow Control Process in Cluster Mode
262
263
1. **Request arrives** at any cluster instance
264
2. **Parameter extracted** from method arguments
265
3. **Token requested** from cluster server with parameter info
266
4. **Global statistics checked** across all instances
267
5. **Decision made** based on global parameter frequency
268
6. **Token granted or denied** and returned to client
269
7. **Local fallback** triggered if cluster server unavailable
270
271
## Configuration Best Practices
272
273
1. **Use unique flow IDs**: Ensure each parameter flow rule has a unique cluster flow ID
274
2. **Configure appropriate fallback**: Enable fallback for critical services
275
3. **Tune sample count**: Balance accuracy vs. performance based on traffic patterns
276
4. **Set reasonable window intervals**: Shorter windows are more responsive but less stable
277
5. **Monitor cluster health**: Ensure cluster server availability for consistent behavior
278
6. **Test fallback scenarios**: Verify local fallback works correctly when cluster fails
279
280
## Cluster Mode vs Local Mode
281
282
| Aspect | Local Mode | Cluster Mode |
283
|--------|------------|--------------|
284
| **Scope** | Per instance | Global across cluster |
285
| **Coordination** | None | Centralized token server |
286
| **Consistency** | Instance-level | Cluster-level |
287
| **Latency** | Low | Higher (network calls) |
288
| **Availability** | High | Depends on cluster server |
289
| **Use Case** | Simple deployments | Distributed systems |