How to Use

• Introduction

• Define Resource

  • "try" and "catch" Mode
  • Bool Mode

• Define Rules

  • Definitions of Rule
  • Manage Rules
  • 定制规则推送方式

Introduction

There are mainly 2 steps to use Sentinel:

1. Define resource
2. Define rules

These two steps don’t have to be synchronized. As long as the resources are defined, you can add rules as necessary. Resources can be applied to multiple rules simultaneously.

Sentinel provides adaptions to popular frameworks as well. After introducing these adapters, services and methods provided by these framework are defined as resources by default.

Define Resource

"try" and "catch" mode

  Entry entry = null;
  try{   
      entry = SphU.entry("hellowrold");
    /**
    * code logic
    */
  } catch (BlockException e1) {
    //resource is rejected
    /**
    * logic to handle exception
    */
  }finally{
    if(entry != null){
      entry.exit();
    }
  }
}

Bool Mode

  if(SphO.entry("helloworld")){
    try {
      /**
      * code logic
      */
    } finally {
      SphO.exit();
    }
  }else{
    //resource is rejected
    /**
    * logic to handle exception
    */
  }
}

Adapters to Popular Frameworks

Details please check: Adapters to popular frameworks

Define Rules

Sentinel provides APIs for users to modify their rules which can be integrated with various kinds of rule repository, such as configuration server, sql, etc.

Definitions of Rule

There are 3 kinds：Flow control rule、Circuit breaking rule　and System protection rule。

Flow control rule (FlowRule)

Definition:

key fields：

field	description	default value
resource	resource name, defined in entry()
count	threshold
grade	calculated by QPS or concurrent thread count	QPS
limitApp	refer to specified caller	default
strategy	by resource itself or other resource (refResource)，or entry (refResource)	resource itself
controlBehavior	reject directly，queue，slow start up	reject directly

one resource can apply more than 1 rules

API

API:FlowRuleManager.loadRules() can be used to configure rules.

private static void initFlowQpsRule() {
        List<FlowRule> rules = new ArrayList<FlowRule>();
        FlowRule rule1 = new FlowRule();
        rule1.setResource(KEY);
        // set limit qps to 20
        rule1.setCount(20);
        rule1.setGrade(RuleConstant.FLOW_GRADE_QPS);
        rule1.setLimitApp("default");
        rules.add(rule1);
        FlowRuleManager.loadRules(rules);
    }

More details please refer to: Flow control

Circuit Break (DegradeRule)

Key fields:

field	description	default value
resource	resource name
count	threshold
grade	by response time or exception ratio	response time
timeWindow	degrade time window

one resource can apply more than 1 rules

API

API:DegradeRuleManager.loadRules() can be used to configure rules.

 private static void initDegradeRule() {
        List<DegradeRule> rules = new ArrayList<DegradeRule>();
        DegradeRule rule = new DegradeRule();
        rule.setResource(KEY);
        // set threshold rt, 10 ms
        rule.setCount(10);
        rule.setGrade(RuleConstant.DEGRADE_GRADE_RT);
        rule.setTimeWindow(10);
        rules.add(rule);
        DegradeRuleManager.loadRules(rules);
    }

More details can refer to :Circuit Break

System protection rule (SystemRule)

Key factors

field	description	default value
highestSystemLoad	threshold of Load1	-1(not valid)
avgRt	average response time	-1(not valid)
maxThread	concurrent thread count	-1(not valid)

API

API:SystemRuleManager.loadRules()

 private static void initDegradeRule() {
        List<SystemRule> rules = new ArrayList<SystemRule>();
        SystemRule rule = new SystemRule();
        rule.setHighestSystemLoad(10);
        rules.add(rule);
        DegradeRuleManager.loadRules(rules);
    }

More details you can refer to:System Protection

HTTP Commands for Rules

Sentinel has provided HTTP commands to expose these rules.

To use these commands, make sure that following library has been introduced:

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-transport-simple-http</artifactId>
    <version>x.y.z</version>
</dependency>

Query command:

curl http://localhost:8719/getRules?type=<XXXX>

type=flow for flow rules;type=degrade for circuit breaking rules;type=system for system protection rules. Rules will be returned in JSON format。

Modification command:

curl http://localhost:8719/setRules?type=<XXXX>&data=<DATA>

Integrated with rule repository

DataSource is designed to integrate rules to customized repositories and make rules persistent. With this extension, you can integrate rules with respostories：

More details you can refer to Dynamic Rules