Sentinel Documentation

A powerful flow control component enabling reliability, resilience and monitoring for microservices. (面向云原生微服务的高可用流控防护组件)

23,105 stars Java Java 1 file · ~8,753 tokens #alibaba#circuit-breaker#cloud-native#java#microservice#microservices#rate-limiting#reliability
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy Sentinel on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name sentinel --restart always alibaba/sentinel:latest

File: README.md

Sentinel: The Sentinel of Your Microservices






Introduction

As distributed systems become increasingly popular, the reliability between services is becoming more important than ever before.
Sentinel takes "flow" as breakthrough point, and works on multiple fields including flow control, traffic shaping,
concurrency limiting, circuit breaking and system adaptive overload protection,
to guarantee reliability and resilience for microservices.

Sentinel has the following features:

  • Rich applicable scenarios: Sentinel has been wildly used in Alibaba, and has covered almost all the core-scenarios in Double-11 (11.11) Shopping Festivals in the past 10 years, such as “Second Kill” which needs to limit burst flow traffic to meet the system capacity, message peak clipping and valley fills, circuit breaking for unreliable downstream services, cluster flow control, etc.
  • Real-time monitoring: Sentinel also provides real-time monitoring ability. You can see the runtime information of a single machine in real-time, and the aggregated runtime info of a cluster with less than 500 nodes.
  • Widespread open-source ecosystem: Sentinel provides out-of-box integrations with commonly-used frameworks and libraries such as Spring Cloud, gRPC, Apache Dubbo and Quarkus. You can easily use Sentinel by simply add the adapter dependency to your services.
  • Polyglot support: Sentinel has provided native support for Java, Go, C++ and Rust.
  • Various SPI extensions: Sentinel provides easy-to-use SPI extension interfaces that allow you to quickly customize your logic, for example, custom rule management, adapting data sources, and so on.

Features overview:

The community is also working on the specification of traffic governance and fault-tolerance.
Please refer to OpenSergo for details.

Documentation

See the Sentinel Website for the official website of Sentinel.

See the 中文文档 for document in Chinese.

See the Wiki for full documentation, examples, blog posts, operational details and other information.

Sentinel provides integration modules for various open-source frameworks
(e.g. Spring Cloud, Apache Dubbo, gRPC, Quarkus, Spring WebFlux, Reactor) and service mesh.
You can refer to the document for more information.

If you are using Sentinel, please leave a comment here to tell us your scenario to make Sentinel better.
It's also encouraged to add the link of your blog post, tutorial, demo or customized components to Awesome Sentinel.

Ecosystem Landscape

Quick Start

Below is a simple demo that guides new users to use Sentinel in just 3 steps. It also shows how to monitor this demo using the dashboard.

1. Add Dependency

Note: Sentinel requires JDK 1.8 or later.

If you're using Maven, just add the following dependency in pom.xml.

xml
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.8.10</version>
</dependency>

If not, you can download JAR in Maven Center Repository.

2. Define Resource

Wrap your code snippet via Sentinel API: SphU.entry(resourceName).
In below example, it is System.out.println("hello world");:

java
try (Entry entry = SphU.entry("HelloWorld")) {
    // Your business logic here.
    System.out.println("hello world");
} catch (BlockException e) {
    // Handle rejected request.
    e.printStackTrace();
}
// try-with-resources auto exit

So far the code modification is done. We've also provided annotation support module to define resource easier.

3. Define Rules

If we want to limit the access times of the resource, we can set rules to the resource.
The following code defines a rule that limits access to the resource to 20 times per second at the maximum.

java
List<FlowRule> rules = new ArrayList<>();
FlowRule rule = new FlowRule();
rule.setResource("HelloWorld");
// set limit qps to 20
rule.setCount(20);
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
rules.add(rule);
FlowRuleManager.loadRules(rules);

For more information, please refer to How To Use.

4. Check the Result

After running the demo for a while, you can see the following records in ~/logs/csp/${appName}-metrics.log.{date} (When using the default DateFileLogHandler).

plaintext
|--timestamp-|------date time----|-resource-|p |block|s |e|rt  |occupied
1529998904000|2018-06-26 15:41:44|HelloWorld|20|0    |20|0|0   |0
1529998905000|2018-06-26 15:41:45|HelloWorld|20|5579 |20|0|728 |0
1529998906000|2018-06-26 15:41:46|HelloWorld|20|15698|20|0|0   |0
1529998907000|2018-06-26 15:41:47|HelloWorld|20|19262|20|0|0   |0
1529998908000|2018-06-26 15:41:48|HelloWorld|20|19502|20|0|0   |0
1529998909000|2018-06-26 15:41:49|HelloWorld|20|18386|20|0|0   |0

p stands for incoming request, block for blocked by rules, s for success handled by Sentinel, e for exception count, rt for average response time (ms), occupied stands for occupiedPassQps since 1.5.0 which enable us booking more than 1 shot when entering.

This shows that the demo can print "hello world" 20 times per second.

More examples and information can be found in the How To Use section.

The working principles of Sentinel can be found in How it works section.

Samples can be found in the sentinel-demo module.

5. Start Dashboard

Note: Java 8 is required for building or running the dashboard.

Sentinel also provides a simple dashboard application, on which you can monitor the clients and configure the rules in real time.

For details please refer to Dashboard.

Trouble Shooting and Logs

Sentinel will generate logs for troubleshooting and real-time monitoring.
All the information can be found in logs.

Bugs and Feedback

For bug report, questions and discussions please submit GitHub Issues.

Contact us via Gitter or Email.

Contributing

Contributions are always welcomed! Please refer to CONTRIBUTING for detailed guidelines.

You can start with the issues labeled with good first issue.

Enterprise Service

If you need Sentinel enterprise service support (Sentinel 企业版), or purchase cloud product services,
you can join the discussion by the DingTalk group (34754806). It can also be directly activated
and used through the microservice engine (MSE 微服务引擎) provided by Alibaba Cloud.

Credits

Thanks Guava, which provides some inspiration on rate limiting.

And thanks for all contributors of Sentinel!

Who is using

These are only part of the companies using Sentinel, for reference only.
If you are using Sentinel, please add your company here to tell us your scenario to make Sentinel better :)

File: doc/awesome-sentinel.md

Awesome Sentinel

A curated list of awesome things (e.g. samples, third-party extensions, blog posts) for Sentinel.

If you want your component to appear here, feel free to submit a pull request to this repository to add it.
You can refer to the awesome contribution guidelines.

You can also add to sentinel-group/sentinel-awesome.

Contents

Presentations

  • Sentinel 1.6.0 网关流控新特性介绍-Eric Zhao (Dubbo Tech Day-201905-Beijing): PDF
  • Sentinel 微服务流控降级实践-Eric Zhao (Dubbo Tech Day-201907-Shenzhen): PDF
  • Sentinel 1.7.0 新特性展望-Eric Zhao (Dubbo Tech Day-201910-Chengdu): PDF
  • 《微服务容易挂？Sentinel Go 让微服务稳如磐石》-Eric Zhao (Spring Cloud Alibaba Meetup 1205 杭州站): PDF
  • Sentinel 2.0 流量治理全面升级-Eric Zhao (2022中间件开发者大会): PDF

Tutorials/Samples

Polyglot Support

Extensions / Integrations

Blog Posts

File: sentinel-adapter/sentinel-apache-dubbo-adapter/README.md

Sentinel Apache Dubbo Adapter (for 2.7.x+)

Note: 中文文档请见此处。

Sentinel Dubbo Adapter provides service consumer filter and provider filter
for Apache Dubbo services.

Note: This adapter only supports Apache Dubbo 2.7.x and above. For legacy com.alibaba:dubbo 2.6.x,
please use sentinel-dubbo-adapter module instead.

To use Sentinel Dubbo Adapter, you can simply add the following dependency to your pom.xml:

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

The Sentinel 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.
Demos can be found in sentinel-demo-apache-dubbo.

If you don't want the filters enabled, you can manually disable them. For example:

xml
<dubbo:consumer filter="-sentinel.dubbo.consumer.filter"/>

<dubbo:provider filter="-sentinel.dubbo.provider.filter"/>

For more details of Dubbo filter, see Dubbo filter documentation.

Dubbo resources

The resource for Dubbo services has two granularities: 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)

Flow control based on caller

In many circumstances, it's also significant to control traffic flow based on the caller.
For example, assuming that there are two services A and B, both of them initiate remote call requests to the service provider.
If we want to limit the calls from service B only, we can set the limitApp of flow rule as the identifier of service B (e.g. service name).

Sentinel Dubbo Adapter will automatically resolve the Dubbo consumer's application name as the caller's name (origin),
and will bring the caller's name when doing resource protection.
If limitApp of flow rules is not configured (default), flow control will take effects on all callers.
If limitApp of a flow rule is configured with a caller, then the corresponding flow rule will only take effect on the specific caller.

Note: Earlier Dubbo 2.7.x consumer does not provide its Dubbo application name when doing RPC,
so developers should manually put the application name into attachment at consumer side,
then extract it at provider side. Sentinel Dubbo Adapter has implemented a filter (DubboAppContextFilter)
where consumer can carry application name information to provider automatically.
If the consumer does not use Sentinel Dubbo Adapter but requires flow control based on caller,
developers can manually put the application name into attachment with the key dubboApplication.

Since 1.8.0, the adapter provides support for customizing origin parsing logic. You may register your own DubboOriginParser
implementation to DubboAdapterGlobalConfig.

Global fallback

Sentinel Dubbo Adapter supports global fallback configuration.
The global fallback will handle exceptions and give replacement result when blocked by
flow control, degrade or system load protection. You can implement your own DubboFallback interface
and then register to DubboAdapterGlobalConfig.
If no fallback is configured, Sentinel will wrap the BlockException as the fallback result.

Besides, we can also leverage Dubbo mock mechanism to provide fallback implementation of degraded Dubbo services.

File: sentinel-adapter/sentinel-apache-dubbo3-adapter/README.md

Sentinel Apache Dubbo Adapter (for 3.0.5+)

Note: 中文文档请见此处。

Sentinel Dubbo Adapter provides service consumer filter and provider filter
for Apache Dubbo services.

Note: This adapter only supports Apache Dubbo 3.0.5 and above.
For org.apache:dubbo 2.7.x, please use sentinel-apache-dubbo-adapter module instead.
For legacy com.alibaba:dubbo 2.6.x, please use sentinel-dubbo-adapter module instead.

To use Sentinel Dubbo 3.x Adapter, you can simply add the following dependency to your pom.xml:

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

The Sentinel 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 overload protection ability when rules are configured.
Demos can be found in sentinel-demo-apache-dubbo.

If you don't want the filters enabled, you can manually disable them. For example:

xml
<dubbo:consumer filter="-sentinel.dubbo.consumer.filter"/>

<dubbo:provider filter="-sentinel.dubbo.provider.filter"/>

For more details of Dubbo filter, see Dubbo filter documentation.

Dubbo resources

The resource for Dubbo services has two granularities: 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)

Note: Dubbo group+version+interface level is also supported in Sentinel Apache Dubbo adapter.
You may just add -Dcsp.sentinel.dubbo.interface.group.version.enabled=true JVM property,
then the resource name of the Dubbo interface and method will be prefixed with group and version info.

Flow control based on caller

In many circumstances, it's also significant to control traffic flow based on the caller.
For example, assuming that there are two services A and B, both of them initiate remote call requests to the service provider.
If we want to limit the calls from service B only, we can set the limitApp of flow rule as the identifier of service B (e.g. service name).

Sentinel Dubbo Adapter will automatically resolve the Dubbo consumer's application name as the caller's name (origin),
and will bring the caller's name when doing resource protection.
If limitApp of flow rules is not configured (default), flow control will take effects on all callers.
If limitApp of a flow rule is configured with a caller, then the corresponding flow rule will only take effect on the specific caller.

Note: The adapter provides support for customizing origin parsing logic as well.
You may register your own DubboOriginParser implementation to DubboAdapterGlobalConfig.

Global fallback

Sentinel Dubbo Adapter supports global fallback configuration.
The global fallback will handle exceptions and give replacement result when blocked by
flow control, degrade or system load protection. You can implement your own DubboFallback interface
and then register to DubboAdapterGlobalConfig.

If no fallback is configured, Sentinel will wrap the BlockException with a RuntimeException as the fallback result.

Besides, we can also leverage Dubbo mock mechanism to provide fallback implementation of degraded Dubbo services.

File: sentinel-adapter/sentinel-apache-httpclient-adapter/README.md

Sentinel Apache Httpclient Adapter

Introduction

Sentinel provides integration for OkHttp client to enable flow control for web requests.

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

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

We can use the SentinelApacheHttpClientBuilder when CloseableHttpClient at initialization, for example:

java
CloseableHttpClient httpclient = new SentinelApacheHttpClientBuilder().build();

If we want to add some additional configurations, we can refer to the following code

java
HttpClientBuilder builder = new SentinelApacheHttpClientBuilder();
//builder Other Definitions
CloseableHttpClient httpclient = builder.build();

Configuration

  • SentinelApacheHttpClientConfig configuration:
name description type default value
prefix customize resource prefix String httpclient:
extractor customize resource extractor ApacheHttpClientResourceExtractor DefaultApacheHttpClientResourceExtractor
fallback handle request when it is blocked ApacheHttpClientFallback DefaultApacheHttpClientFallback

extractor (resource extractor)

We can define ApacheHttpClientResourceExtractor to customize resource extractor replace DefaultApacheHttpClientResourceExtractor at SentinelApacheHttpClientBuilder default config, for example: httpclient:GET:/httpclient/back/1 ==> httpclient:GET:/httpclient/back/{id}

java
SentinelApacheHttpClientConfig config = new SentinelApacheHttpClientConfig();
config.setExtractor(new ApacheHttpClientResourceExtractor() {

    @Override
    public String extractor(HttpRequestWrapper request) {
        String contains = "/httpclient/back/";
        String uri = request.getRequestLine().getUri();
        if (uri.startsWith(contains)) {
            uri = uri.substring(0, uri.indexOf(contains) + contains.length()) + "{id}";
        }
        return request.getMethod() + ":" + uri;
    }
});
CloseableHttpClient httpclient = new SentinelApacheHttpClientBuilder(config).build();

fallback (Block handling)

We can define ApacheHttpClientFallback at SentinelApacheHttpClientBuilder default config, to handle request is blocked according to the actual scenario, for example:

java
public class DefaultApacheHttpClientFallback implements ApacheHttpClientFallback {

    @Override
    public CloseableHttpResponse handle(HttpRequestWrapper request, BlockException e) {
        // Just wrap and throw the exception.
        throw new SentinelRpcException(e);
    }
}

File: sentinel-adapter/sentinel-api-gateway-adapter-common/README.md

Sentinel API Gateway Adapter Common

The sentinel-api-gateway-adapter-common module provides common abstraction for
API gateway flow control:

  • GatewayFlowRule: flow control rule specific for route or API defined in API gateway.
    This can be automatically converted to FlowRule or ParamFlowRule.
  • ApiDefinition: gateway API definition with a group of predicates

File: sentinel-adapter/sentinel-dubbo-adapter/README.md

Sentinel Dubbo Adapter

Note: 中文文档请见此处。

Sentinel Dubbo Adapter provides service consumer filter and provider filter
for Dubbo services.

Note: This adapter only supports legacy Dubbo 2.6.x version and below.
For new Apache Dubbo 2.7.x or above version, please use sentinel-apache-dubbo-adapter module instead.

To use Sentinel Dubbo Adapter, you can simply add the following dependency to your pom.xml:

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

The Sentinel 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.
Demos can be found in sentinel-demo-dubbo.

If you don't want the filters enabled, you can manually disable them. For example:

xml
<dubbo:consumer filter="-sentinel.dubbo.consumer.filter"/>

<dubbo:provider filter="-sentinel.dubbo.provider.filter"/>

For more details of Dubbo filter, see here.

Dubbo resources

The resource for Dubbo services has two granularities: 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)

Flow control based on caller

In many circumstances, it's also significant to control traffic flow based on the caller.
For example, assuming that there are two services A and B, both of them initiate remote call requests to the service provider.
If we want to limit the calls from service B only, we can set the limitApp of flow rule as the identifier of service B (e.g. service name).

Sentinel Dubbo Adapter will automatically resolve the Dubbo consumer's application name as the caller's name (origin),
and will bring the caller's name when doing resource protection.
If limitApp of flow rules is not configured (default), flow control will take effects on all callers.
If limitApp of a flow rule is configured with a caller, then the corresponding flow rule will only take effect on the specific caller.

Note: Dubbo consumer does not provide its Dubbo application name when doing RPC,
so developers should manually put the application name into attachment at consumer side,
then extract it at provider side. Sentinel Dubbo Adapter has implemented a filter (DubboAppContextFilter)
where consumer can carry application name information to provider automatically.
If the consumer does not use Sentinel Dubbo Adapter but requires flow control based on caller,
developers can manually put the application name into attachment with the key dubboApplication.

Since 1.8.0, the adapter provides support for customizing origin parsing logic. You may register your own DubboOriginParser
implementation to DubboAdapterGlobalConfig.

Global fallback

Sentinel Dubbo Adapter supports global fallback configuration.
The global fallback will handle exceptions and give replacement result when blocked by
flow control, degrade or system load protection. You can implement your own DubboFallback interface
and then register to DubboAdapterGlobalConfig.
If no fallback is configured, Sentinel will wrap the BlockException as the fallback result.

Besides, we can also leverage Dubbo mock mechanism to provide fallback implementation of degraded Dubbo services.

File: sentinel-adapter/sentinel-grpc-adapter/README.md

Sentinel gRPC Adapter

Sentinel gRPC Adapter provides client and server interceptor for gRPC services.

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

Client Interceptor

Example:

java
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.
    }
}

Server Interceptor

Example:

java
import io.grpc.Server;

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

File: sentinel-adapter/sentinel-jax-rs-adapter/README.md

Sentinel adapter for JAX-RS

Sentinel provides integration to enable fault-tolerance and flow control for JAX-RS web requests.
Add the following dependency in pom.xml (if you are using Maven):

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

SentinelJaxRsProviderFilter

The SentinelJaxRsProviderFilter is auto activated in pure JAX-RS application.

For Spring web applications you can configure with Spring bean:

java
@Configuration
public class FilterConfig {

    @Bean
    public SentinelJaxRsProviderFilter sentinelJaxRsProviderFilter() {
        return new SentinelJaxRsProviderFilter();
    }
}

DefaultExceptionMapper

Sentinel provides DefaultExceptionMapper to map Throwable to Response (with Status.INTERNAL_SERVER_ERROR),
in order to let SentinelJaxRsProviderFilter to be called and exit the Sentinel entry.

According to 3.3.4 Exceptions of jaxrs-2_1-final-spec:

Checked exceptions and throwables that have not been mapped and cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container.

If WebApplicationException or its subclasses are thrown, they'll be automatically converted to Response and can enter response filter.
If other kind of exceptions were thrown, and not matched by custom exception mapper, then the response filter cannot be called.
For this case, a default exception mapper maybe introduced.

According to 4.4 Exception Mapping Providers of jaxrs-2_1-final-spec:

When choosing an exception mapping provider to map an exception, an implementation MUST use the provider whose generic type is the nearest superclass of the exception. If two or more exception providers are applicable, the one with the highest priority MUST be chosen as described in Section 4.1.3.

If user also provides customized exception mapper of Throwable, then user has the responsibility to convert it to response and then the response filter can be called.

As describe in 6.7.1 exceptions of jaxrs-2_1-final-spec:

A response mapped from an exception MUST be processed using the ContainerResponse filter chain and the WriteTo interceptor chain (if an entity is present in the mapped response).

SentinelJaxRsClientTemplate

For jax-rs client, we provide SentinelJaxRsClientTemplate you can use it like this:

text
Response response = SentinelJaxRsClientTemplate.execute(resourceName, new Supplier<Response>() {
    @Override
    public Response get() {
        return client.target(host).path(url).request()
                .get();
    }
});

or executeAsync like this:

text
Future<Response> future = SentinelJaxRsClientTemplate.executeAsync(resourceName, new Supplier<Future<Response>>() {
    @Override
    public Future<Response> get() {
        return client.target(host).path(url).request()
                .async()
                .get();
    }
});

When a request is blocked, Sentinel JAX-RS filter will return Response with status of TOO_MANY_REQUESTS indicating the request is rejected.

You can customize it by implement your own SentinelJaxRsFallback and register to SentinelJaxRsConfig.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#alibaba Browse alibaba catalog → #circuit-breaker Browse circuit-breaker catalog → #cloud-native Browse cloud-native catalog → #java Browse java catalog → #microservice Browse microservice catalog → #microservices Browse microservices catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →