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
```