Integrations with open-source frameworks

Contents

• Microservices
  • Spring Boot/Spring Cloud
  • Quarkus
• Web frameworks
  • Web Servlet
  • Spring WebFlux
• RPC frameworks
  • Dubbo
  • gRPC
• Reactive support
• API Gateway support
  • Spring Cloud Gateway
  • Zuul 1.x
• Apache RocketMQ

Microservices

Spring Cloud

Spring Cloud Alibaba Sentinel provides out-of-box integration with Sentinel for Spring Cloud applications and services (Spring Web, Spring WebFlux, RestTemplate, Feign, Spring Cloud Gateway, Reactor, Zuul).

Please refer to Spring Cloud Alibaba for more information. Demo: sentinel-guide-spring-cloud

Quarkus

Sentinel provides out-of-box support for Quarkus. See sentinel-quarkus-adapter for more details (since 1.8.0).

Web frameworks

Web Servlet

Sentinel provides Web Servlet filter integration to enable flow control for web requests. Add the following dependency in pom.xml (if you are using Maven):

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-web-servlet</artifactId>
    <version>x.y.z</version>
</dependency>

To use the filter, you can simply configure your web.xml with:

<filter>
    <filter-name>SentinelCommonFilter</filter-name>
    <filter-class>com.alibaba.csp.sentinel.adapter.servlet.CommonFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>SentinelCommonFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

For Spring web applications you can configure with Spring bean:

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean sentinelFilterRegistration() {
        FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new CommonFilter());
        registration.addUrlPatterns("/*");
        registration.setName("sentinelFilter");
        registration.setOrder(1);

        return registration;
    }
}

When a request is blocked, Sentinel servlet filter will give a default page indicating the request blocked. If customized block page is set (via WebServletConfig.setBlockPage(blockPage) method), the filter will redirect the request to provided URL. You can also implement your own block handler (the UrlBlockHandler interface) and register to WebCallbackManager.

The UrlCleaner interface is designed to clean and unify the URL resource. For REST APIs, you have to clean the URL resource (e.g. /foo/1 and /foo/2 -> /foo/:id), or the amount of context and resources will exceed the threshold.

The RequestOriginParser interface is useful for extracting request origin (e.g. IP or appName from HTTP Header) from the HTTP request. You can implement your own RequestOriginParser and register to WebCallbackManager.

Spring WebFlux

Note: supported since Sentinel 1.5.0. This module requires JDK 8 or later versions.

See the document of Sentinel Spring WebFlux Adapter module.

RPC frameworks

Dubbo

Sentinel Dubbo Adapter provides service consumer filter and provider filter for Dubbo services. Since Dubbo 2.7.x is not compatible with the previous version, we provide two modules:

• sentinel-apache-dubbo-adapter (compatible with Apache Dubbo 2.7.x and later version, supported since Sentinel 1.5.1)
• sentinel-dubbo-adapter (compatible with Dubbo 2.6.x and previous version)

If you are using Apache Dubbo 2.7.x and later version, you can add the following dependency:

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-apache-dubbo-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

If you are using Dubbo 2.6.x or previous version, you can add the following dependency:

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-dubbo-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

The adapter filters are enabled by default. Once you add the dependency, the Dubbo services and methods will become protected resources in Sentinel, which can leverage Sentinel's flow control and guard ability when rules are configured.

If you don't want to enable the filter, you can manually disable it. For example:

<!-- disable the Sentinel Dubbo consumer filter -->
<dubbo:consumer filter="-sentinel.dubbo.consumer.filter"/>

The guarded resource can be both service interface and service method:

• Service interface：resourceName format is interfaceName，e.g. com.alibaba.csp.sentinel.demo.dubbo.FooService
• Service method：resourceName format is interfaceName:methodSignature，e.g. com.alibaba.csp.sentinel.demo.dubbo.FooService:sayHello(java.lang.String)

Sentinel Dubbo Adapter supports global fallback configuration. The global fallback will handle exceptions and give the replacement result when blocked by flow control, degrade or system load protection. You can implement your own DubboFallback interface and then register to DubboFallbackRegistry. If no fallback is configured, Sentinel will wrap the BlockException then directly throw it out. Besides, we can also leverage Dubbo mock mechanism to provide the fallback implementation of degraded Dubbo services.

For Sentinel's best practice in Dubbo, please refer to Sentinel: the flow sentinel of Dubbo.

For more details of Dubbo filter, see here.

gRPC

Sentinel provides integration with gRPC Java. Sentinel gRPC Adapter provides client and server interceptor for gRPC services. Add the following dependency in pom.xml (if you are using Maven):

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-grpc-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

To use Sentinel gRPC Adapter, you simply need to register the Interceptor to your client or server. The client sample:

public class ServiceClient {

    private final ManagedChannel channel;

    ServiceClient(String host, int port) {
        this.channel = ManagedChannelBuilder.forAddress(host, port)
            .intercept(new SentinelGrpcClientInterceptor()) // Add the client interceptor.
            .build();
        // Init your stub here.
    }
}

The server sample；

import io.grpc.Server;

Server server = ServerBuilder.forPort(port)
     .addService(new MyServiceImpl()) // Add your service.
     .intercept(new SentinelGrpcServerInterceptor()) // Add the server interceptor.
     .build();

Note that currently the interceptor only supports unary methods in gRPC.

Reactive support

Reactor

Note: supported since Sentinel 1.5.0. This module requires JDK 8 or later versions.

Sentinel provides integration module for Reactor.

Add the following dependency in pom.xml (if you are using Maven):

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-reactor-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

Example:

someService.doSomething() // return type: Mono<T> or Flux<T>
   .transform(new SentinelReactorTransformer<>(resourceName)) // transform here
   .subscribe();

API Gateway support

Spring Cloud Gateway

Note: this module requires Java 8 or later version.

Sentinel provides an integration module with Spring Cloud Gateway, which supports flow control for routes and customized API groups. The integration module is based on the Sentinel Reactor Adapter.

Add the following dependency in pom.xml (if you are using Maven):

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-spring-cloud-gateway-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

Then you only need to inject the corresponding SentinelGatewayFilter and SentinelGatewayBlockExceptionHandler instance in Spring configuration. For example:

@Configuration
public class GatewayConfiguration {

    private final List<ViewResolver> viewResolvers;
    private final ServerCodecConfigurer serverCodecConfigurer;

    public GatewayConfiguration(ObjectProvider<List<ViewResolver>> viewResolversProvider,
                                ServerCodecConfigurer serverCodecConfigurer) {
        this.viewResolvers = viewResolversProvider.getIfAvailable(Collections::emptyList);
        this.serverCodecConfigurer = serverCodecConfigurer;
    }

    @Bean
    @Order(-1)
    public SentinelGatewayBlockExceptionHandler sentinelGatewayBlockExceptionHandler() {
        // Register the block exception handler for Spring Cloud Gateway.
        return new SentinelGatewayBlockExceptionHandler(viewResolvers, serverCodecConfigurer);
    }

    @Bean
    @Order(-1)
    public GlobalFilter sentinelGatewayFilter() {
        return new SentinelGatewayFilter();
    }
}

The gateway adapter will regard all routeId (defined in Spring properties) and all customized API definitions (defined in GatewayApiDefinitionManager of sentinel-api-gateway-adapter-common module) as resources.

You can register various customized callback in GatewayCallbackManager:

• setBlockHandler: register a customized BlockRequestHandler to handle the blocked request. The default implementation is DefaultBlockRequestHandler, which returns default message like Blocked by Sentinel: FlowException.

Zuul 1.x

Sentinel Zuul Adapter provides route level and customized API level flow control for Zuul 1.x. Please refer to the document here.

Apache RocketMQ

In Apache RocketMQ, when message consumers are consuming messages, there may a sudden inflow of messages, whether using pull or push mode. If all the messages were handled at this time, it would be likely to cause the system to be overloaded and then affect stability. However, in fact, there may be no messages coming within a few seconds. If redundant messages are directly discarded, the system's ability to process the message is not fully utilized. We hope that the sudden inflow of messages can be spread over a period of time, so that the system load can be kept on the stable level while processing as many messages as possible, thus achieving the effect of “shaving the peaks and filling the valley”.

Sentinel provides a feature for this kind of scenario: Rate Limiter, which can spread a large number of sudden request inflow in a uniform rate manner, let the request pass at a fixed interval. It is often used to process burst requests instead of rejecting them. This avoids traffic spurs causing system overloaded. Moreover, the pending requests will be queued and processed one by one. When the request is estimated to exceed the maximum queuing timeout, it will be rejected immediately.

For example, we configure the rule with uniform rate limiting mode and QPS count is 5, which indicates messages are consumed at fixed interval (200 ms) and pending messages will wait (virtual queue). We also set the maximum queuing timeout is 5s, then all requests estimated to exceed the timeout will be rejected immediately.

Developer can set rules to different groups and topics (e.g. resouceName is groupName:topicName), set the control behaviour to RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER, then the messages can be handled at a fixed rate. Here is an example for the rule:

private void initFlowControlRule() {
    FlowRule rule = new FlowRule();
    rule.setResource(KEY); // resource name can be `groupName:topicName`
    rule.setCount(5); // Indicates the interval between two adjacent requests is 200 ms.
    rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
    rule.setLimitApp("default");

    // Enable rate limiting (uniform). This can ensure fixed intervals between two adjacent calls.
    // In this example, intervals between two incoming calls (message consumption) will be 200 ms constantly.
    rule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER);
    // If more requests are coming, they'll be put into the waiting queue.
    // In this example, the max timeout is 5s.
    rule.setMaxQueueingTimeMs(5 * 1000);
    FlowRuleManager.loadRules(Collections.singletonList(rule));
}

When using Sentinel with RocketMQ Client, developers should manually wrap their code of handling messages with Sentinel API. Here is a sample for pull consumer: Sentinel RocketMQ Demo.