0
# Sentinel Parameter Flow Control
1
2
Sentinel Parameter Flow Control provides functionality of flow control by frequent ("hot spot") parameters. It enables QPS-based and thread-count-based flow control for specific parameter values, allowing fine-grained traffic shaping based on parameter frequency patterns.
3
4
## Package Information
5
6
- **Package Name**: sentinel-parameter-flow-control
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: com.alibaba.csp
10
- **Artifact ID**: sentinel-parameter-flow-control
11
- **Installation**: Add to `pom.xml`:
12
```xml
13
<dependency>
14
<groupId>com.alibaba.csp</groupId>
15
<artifactId>sentinel-parameter-flow-control</artifactId>
16
<version>1.8.8</version>
17
</dependency>
18
```
19
20
## Core Imports
21
22
```java
23
import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowRule;
24
import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowRuleManager;
25
import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowItem;
26
import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowException;
27
import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowChecker;
28
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
29
import com.alibaba.csp.sentinel.slotchain.ResourceWrapper;
30
import com.alibaba.csp.sentinel.SphU;
31
```
32
33
## Basic Usage
34
35
```java
36
import com.alibaba.csp.sentinel.SphU;
37
import com.alibaba.csp.sentinel.Entry;
38
import com.alibaba.csp.sentinel.EntryType;
39
import com.alibaba.csp.sentinel.slots.block.BlockException;
40
import com.alibaba.csp.sentinel.slots.block.flow.param.*;
41
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
42
import java.util.Collections;
43
44
// Create parameter flow rule
45
ParamFlowRule rule = new ParamFlowRule("resourceName")
46
.setParamIdx(0) // Monitor first parameter
47
.setCount(5) // Allow 5 QPS for each parameter value
48
.setGrade(RuleConstant.FLOW_GRADE_QPS);
49
50
// Add exception for specific parameter value
51
ParamFlowItem item = new ParamFlowItem()
52
.setObject("VIP_USER")
53
.setClassType(String.class.getName())
54
.setCount(10); // VIP users get 10 QPS
55
rule.setParamFlowItemList(Collections.singletonList(item));
56
57
// Load rules
58
ParamFlowRuleManager.loadRules(Collections.singletonList(rule));
59
60
// Use in application code
61
public void processRequest(String userId) {
62
Entry entry = null;
63
try {
64
// Pass parameters to Sentinel
65
entry = SphU.entry("resourceName", EntryType.IN, 1, userId);
66
67
// Your business logic here
68
doBusinessLogic(userId);
69
70
} catch (ParamFlowException ex) {
71
// Handle parameter flow control triggered
72
System.out.println("Parameter flow control triggered for user: " + ex.getLimitParam());
73
} catch (BlockException ex) {
74
// Handle other flow control
75
} finally {
76
if (entry != null) {
77
entry.exit();
78
}
79
}
80
}
81
```
82
83
## Architecture
84
85
Sentinel Parameter Flow Control is built around several key components:
86
87
- **Rule Management**: `ParamFlowRuleManager` provides centralized rule configuration and dynamic updates
88
- **Flow Checking**: `ParamFlowChecker` implements the core flow control logic with support for QPS and thread count modes
89
- **Parameter Slot**: `ParamFlowSlot` integrates with Sentinel's slot chain for transparent parameter monitoring
90
- **Metrics System**: `ParameterMetric` and `ParameterMetricStorage` track parameter usage statistics
91
- **Cluster Support**: Optional cluster mode for distributed parameter flow control
92
93
## Capabilities
94
95
### Rule Management
96
97
Core functionality for defining, loading, and managing parameter flow control rules. This is the primary entry point for configuring parameter-based flow control.
98
99
```java { .api }
100
public static void loadRules(List<ParamFlowRule> rules);
101
public static List<ParamFlowRule> getRulesOfResource(String resourceName);
102
public static List<ParamFlowRule> getRules();
103
public static boolean hasRules(String resourceName);
104
```
105
106
[Rule Management](./rule-management.md)
107
108
### Parameter Flow Rules
109
110
Configuration objects that define how parameter flow control should behave. Rules specify which parameters to monitor, thresholds, and exception handling.
111
112
```java { .api }
113
public class ParamFlowRule extends AbstractRule {
114
public ParamFlowRule();
115
public ParamFlowRule(String resourceName);
116
public ParamFlowRule setParamIdx(Integer paramIdx);
117
public ParamFlowRule setCount(double count);
118
public ParamFlowRule setGrade(int grade);
119
public ParamFlowRule setControlBehavior(int controlBehavior);
120
}
121
```
122
123
[Parameter Flow Rules](./parameter-flow-rules.md)
124
125
### Exception Items
126
127
Special parameter values that have different thresholds than the default rule. Useful for implementing VIP user handling or special case parameters.
128
129
```java { .api }
130
public class ParamFlowItem {
131
public ParamFlowItem();
132
public ParamFlowItem(String object, Integer count, String classType);
133
public static <T> ParamFlowItem newItem(T object, Integer count);
134
public ParamFlowItem setObject(String object);
135
public ParamFlowItem setCount(Integer count);
136
public ParamFlowItem setClassType(String classType);
137
}
138
```
139
140
[Exception Items](./exception-items.md)
141
142
### Flow Control Exceptions
143
144
Exception handling for when parameter flow control is triggered. Provides detailed information about which parameter caused the flow control.
145
146
```java { .api }
147
public class ParamFlowException extends BlockException {
148
public ParamFlowException(String resourceName, String param);
149
public ParamFlowException(String resourceName, String param, ParamFlowRule rule);
150
public String getResourceName();
151
public String getLimitParam();
152
public ParamFlowRule getRule();
153
}
154
```
155
156
[Flow Control Exceptions](./flow-control-exceptions.md)
157
158
### Cluster Mode
159
160
Advanced functionality for distributed parameter flow control across multiple instances. Enables coordinated parameter limits in cluster environments.
161
162
```java { .api }
163
public class ParamFlowClusterConfig {
164
public ParamFlowClusterConfig setFlowId(Long flowId);
165
public ParamFlowClusterConfig setThresholdType(int thresholdType);
166
public ParamFlowClusterConfig setFallbackToLocalWhenFail(boolean fallbackToLocalWhenFail);
167
}
168
```
169
170
[Cluster Mode](./cluster-mode.md)
171
172
### Rule Utilities
173
174
Utility functions for rule validation and management. These functions help with rule processing and validation logic.
175
176
```java { .api }
177
public final class ParamFlowRuleUtil {
178
public static boolean isValidRule(ParamFlowRule rule);
179
public static Map<String, List<ParamFlowRule>> buildParamRuleMap(List<ParamFlowRule> list);
180
public static void fillExceptionFlowItems(ParamFlowRule rule);
181
}
182
```
183
184
### Metrics and Storage
185
186
Core metrics tracking and storage functionality for parameter flow control statistics and performance monitoring.
187
188
```java { .api }
189
public class ParameterMetric {
190
public void clear();
191
public CacheMap<Object, AtomicLong> getRuleTimeCounter(ParamFlowRule rule);
192
public long getThreadCount(int index, Object value);
193
public void addThreadCount(Object... args);
194
public void decreaseThreadCount(Object... args);
195
}
196
197
public final class ParameterMetricStorage {
198
public static ParameterMetric getParamMetric(ResourceWrapper resourceWrapper);
199
public static ParameterMetric getParamMetricForResource(String resourceName);
200
public static void clearParamMetricForResource(String resourceName);
201
}
202
```
203
204
### Command Handlers
205
206
Command handlers for managing parameter flow rules through Sentinel's command interface, supporting dynamic rule retrieval and modification.
207
208
```java { .api }
209
public class GetParamFlowRulesCommandHandler implements CommandHandler<String> {
210
public CommandResponse<String> handle(CommandRequest request);
211
}
212
213
public class ModifyParamFlowRulesCommandHandler implements CommandHandler<String> {
214
public CommandResponse<String> handle(CommandRequest request);
215
public static WritableDataSource<List<ParamFlowRule>> getWritableDataSource();
216
public static void setWritableDataSource(WritableDataSource<List<ParamFlowRule>> dataSource);
217
}
218
```
219
220
## Types
221
222
```java { .api }
223
public interface ParamFlowArgument {
224
Object paramFlowKey();
225
}
226
227
public enum RollingParamEvent {
228
REQUEST_PASSED,
229
REQUEST_BLOCKED
230
}
231
232
public final class ParamFlowChecker {
233
public static boolean passCheck(ResourceWrapper resourceWrapper, ParamFlowRule rule, int count, Object... args);
234
}
235
236
public interface CacheMap<K, V> {
237
boolean containsKey(K key);
238
V get(K key);
239
V put(K key, V value);
240
V putIfAbsent(K key, V value);
241
void clear();
242
long size();
243
}
244
245
public class ParamMapBucket {
246
public static final int DEFAULT_MAX_CAPACITY = 200;
247
public ParamMapBucket();
248
public ParamMapBucket(int capacity);
249
public void reset();
250
public int get(RollingParamEvent event, Object value);
251
}
252
```