tessl/maven-sentinel-parameter-flow-control

Sentinel Parameter Flow Control provides functionality of flow control by frequent (hot spot) parameters.

—

Pending

Overview

Eval results

Files

Parameter Flow Rules

Name: tessl/maven-sentinel-parameter-flow-control
Author: tessl

Configuration objects that define how parameter flow control should behave. ParamFlowRule specifies which parameters to monitor, thresholds, control behaviors, and exception handling for hot spot parameter flow control.

Capabilities

Basic Rule Creation

Creates parameter flow rules for monitoring specific parameters in method calls.

/**
 * Default constructor for parameter flow rule
 */
public ParamFlowRule();

/**
 * Constructor with resource name
 * @param resourceName the resource name to monitor
 */
public ParamFlowRule(String resourceName);

Usage Example:

// Create rule for monitoring user service
ParamFlowRule rule = new ParamFlowRule("userService");

// Or create empty rule and set resource later
ParamFlowRule rule2 = new ParamFlowRule();
rule2.setResource("productService");

Parameter Index Configuration

Specifies which parameter position to monitor in the method arguments.

/**
 * Set the parameter index to monitor
 * @param paramIdx parameter index (0-based)
 * @return this rule for method chaining
 */
public ParamFlowRule setParamIdx(Integer paramIdx);

/**
 * Get the parameter index
 * @return parameter index
 */
public Integer getParamIdx();

Usage Example:

// Monitor the first parameter (index 0)
ParamFlowRule rule = new ParamFlowRule("userService")
    .setParamIdx(0);

// Monitor the second parameter (index 1)  
ParamFlowRule productRule = new ParamFlowRule("productService")
    .setParamIdx(1);

// For method: processUser(String userId, String productId)
// paramIdx=0 monitors userId, paramIdx=1 monitors productId

Threshold Configuration

Sets the flow control threshold for parameter values.

/**
 * Set the threshold count
 * @param count the threshold count
 * @return this rule for method chaining
 */
public ParamFlowRule setCount(double count);

/**
 * Get the threshold count
 * @return threshold count
 */
public double getCount();

Usage Example:

// Allow maximum 5 requests per second for each parameter value
ParamFlowRule rule = new ParamFlowRule("userService")
    .setParamIdx(0)
    .setCount(5);

// Allow 100 requests per second for product queries
ParamFlowRule productRule = new ParamFlowRule("productService")
    .setParamIdx(0)
    .setCount(100);

Grade Configuration

Specifies the metric type for flow control (QPS or thread count).

/**
 * Set the threshold type of flow control (0: thread count, 1: QPS)
 * @param grade the grade type
 * @return this rule for method chaining
 */
public ParamFlowRule setGrade(int grade);

/**
 * Get the threshold type
 * @return grade type
 */
public int getGrade();

Usage Example:

import com.alibaba.csp.sentinel.slots.block.RuleConstant;

// QPS-based flow control (default)
ParamFlowRule qpsRule = new ParamFlowRule("userService")
    .setParamIdx(0)
    .setCount(10)
    .setGrade(RuleConstant.FLOW_GRADE_QPS);

// Thread count-based flow control
ParamFlowRule threadRule = new ParamFlowRule("heavyService")
    .setParamIdx(0)
    .setCount(5)
    .setGrade(RuleConstant.FLOW_GRADE_THREAD);

Control Behavior Configuration

Configures traffic shaping behavior when flow control is triggered.

/**
 * Set traffic shaping behavior
 * @param controlBehavior the control behavior
 * @return this rule for method chaining
 */
public ParamFlowRule setControlBehavior(int controlBehavior);

/**
 * Get the control behavior
 * @return control behavior
 */
public int getControlBehavior();

Usage Example:

import com.alibaba.csp.sentinel.slots.block.RuleConstant;

// Default behavior - direct rejection
ParamFlowRule defaultRule = new ParamFlowRule("userService")
    .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT);

// Rate limiting with queuing
ParamFlowRule rateLimitRule = new ParamFlowRule("userService")
    .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER)
    .setMaxQueueingTimeMs(500);

Burst and Duration Configuration

Configures burst handling and time window settings.

/**
 * Set burst count for handling traffic spikes
 * @param burstCount burst count
 * @return this rule for method chaining
 */
public ParamFlowRule setBurstCount(int burstCount);

/**
 * Set duration in seconds for the time window
 * @param durationInSec duration in seconds
 * @return this rule for method chaining
 */
public ParamFlowRule setDurationInSec(long durationInSec);

/**
 * Set maximum queuing time in milliseconds
 * @param maxQueueingTimeMs max queuing time
 * @return this rule for method chaining
 */
public ParamFlowRule setMaxQueueingTimeMs(int maxQueueingTimeMs);

Usage Example:

// Configure rule with burst handling and custom time window
ParamFlowRule rule = new ParamFlowRule("userService")
    .setParamIdx(0)
    .setCount(10)              // 10 requests per second normally
    .setBurstCount(5)          // Allow burst of 5 extra requests
    .setDurationInSec(2)       // Use 2-second time window
    .setMaxQueueingTimeMs(200); // Queue requests for up to 200ms

Exception Items Configuration

Configures special handling for specific parameter values.

/**
 * Set the exception items of parameter; you can set threshold to a specific parameter value
 * @param paramFlowItemList list of exception items
 * @return this rule for method chaining
 */
public ParamFlowRule setParamFlowItemList(List<ParamFlowItem> paramFlowItemList);

/**
 * Get the exception items
 * @return list of exception items
 */
public List<ParamFlowItem> getParamFlowItemList();

/**
 * Retrieve exclusive item count for a specific parameter value
 * @param value the parameter value
 * @return exclusive count for the value, or null if not found
 */
public Integer retrieveExclusiveItemCount(Object value);

Usage Example:

// Create exception items for VIP users
ParamFlowItem vipItem = new ParamFlowItem()
    .setObject("VIP_USER")
    .setClassType(String.class.getName())
    .setCount(50); // VIP users get 50 QPS instead of default 10

ParamFlowItem adminItem = new ParamFlowItem()
    .setObject("ADMIN_USER")
    .setClassType(String.class.getName())
    .setCount(100); // Admin users get 100 QPS

ParamFlowRule rule = new ParamFlowRule("userService")
    .setParamIdx(0)
    .setCount(10) // Default 10 QPS for regular users
    .setParamFlowItemList(Arrays.asList(vipItem, adminItem));

Cluster Mode Configuration

Enables distributed parameter flow control across multiple instances.

/**
 * Set cluster mode
 * @param clusterMode true to enable cluster mode
 * @return this rule for method chaining
 */
public ParamFlowRule setClusterMode(boolean clusterMode);

/**
 * Check if cluster mode is enabled
 * @return true if cluster mode is enabled
 */
public boolean isClusterMode();

/**
 * Set cluster configuration
 * @param clusterConfig cluster configuration
 * @return this rule for method chaining
 */
public ParamFlowRule setClusterConfig(ParamFlowClusterConfig clusterConfig);

/**
 * Get cluster configuration
 * @return cluster configuration
 */
public ParamFlowClusterConfig getClusterConfig();

Usage Example:

// Configure rule for cluster mode
ParamFlowClusterConfig clusterConfig = new ParamFlowClusterConfig()
    .setFlowId(12345L)
    .setThresholdType(ClusterRuleConstant.FLOW_THRESHOLD_GLOBAL);

ParamFlowRule clusterRule = new ParamFlowRule("userService")
    .setParamIdx(0)
    .setCount(100)
    .setClusterMode(true)
    .setClusterConfig(clusterConfig);

Rule Validation

Parameter flow rules are validated when loaded:

Resource name must not be blank
Count must be non-negative
Parameter index must not be null
Burst count must be non-negative
Duration must be positive
Control behavior must be valid
Cluster configuration must be valid if cluster mode is enabled

Complete Example

import com.alibaba.csp.sentinel.slots.block.flow.param.*;
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
import java.util.Arrays;

// Create comprehensive parameter flow rule
ParamFlowRule rule = new ParamFlowRule("userService")
    .setParamIdx(0)                                    // Monitor first parameter
    .setCount(10)                                      // 10 QPS for regular users
    .setGrade(RuleConstant.FLOW_GRADE_QPS)            // Use QPS mode
    .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT) // Direct rejection
    .setBurstCount(3)                                  // Allow burst of 3
    .setDurationInSec(1);                             // 1-second window

// Add VIP user exception
ParamFlowItem vipException = new ParamFlowItem()
    .setObject("VIP_123")
    .setClassType(String.class.getName())
    .setCount(50);

rule.setParamFlowItemList(Arrays.asList(vipException));

// Load the rule
ParamFlowRuleManager.loadRules(Arrays.asList(rule));

Install with Tessl CLI

npx tessl i tessl/maven-sentinel-parameter-flow-control

docs

cluster-mode.md

exception-items.md

flow-control-exceptions.md

index.md

parameter-flow-rules.md

rule-management.md

tile.json

tessl/maven-sentinel-parameter-flow-control