Extension interfaces

Web servlet filter

• Custom throttling pages or processing logic

  By default, a default prompt page is returned when a request is throttled. You can set a custom redirection URL in one of the following three ways:

  • Method 1: Use the WebServletConfig.setBlockPage(blockPage) method.
    Example:

    // This is a global setting. All throttled pages are redirected to this URL.
    WebServletConfig.setBlockPage("https://www.example.test/");

  • Method 2: Use the JVM parameter -Dcsp.sentinel.web.servlet.block.page=xxx
    Example:

    // This is a global setting. All throttled pages are redirected to this URL.
    -Dcsp.sentinel.web.servlet.block.page=https://www.fallback.page.com/

  • Method 3: For more flexibility, you can define the throttling logic by implementing the UrlBlockHandler interface and registering it with WebCallbackManager.
    Example of custom processing logic:

    // Set this globally only once, for example, in a global init() method.
    WebCallbackManager.setUrlBlockHandler(new UrlBlockHandler() {
        @Override
        public void blocked(HttpServletRequest request, HttpServletResponse response, BlockException ex)
            throws IOException {
            // The request object contains all the information for this request. You can parse the URL and request parameters from it.
            logger.info("blocked: " + request.getPathInfo());
            // The response object represents the response. Write the fallback result directly to it.
            response.sendRedirect("https://www.fallback.page.com/"); // Redirect the request to the fallback address.
        }
    });

    Example of returning status 500:

    // Set this globally only once, for example, in a global init() method.
    WebCallbackManager.setUrlBlockHandler(new UrlBlockHandler() {
        @Override
        public void blocked(HttpServletRequest request, HttpServletResponse response, BlockException ex)
            throws IOException {
            // The request object contains all the information for this request. You can parse the URL and request parameters from it.
            logger.info("blocked: " + request.getPathInfo());
            // The response object represents the response. Write the fallback result directly to it.
            response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
            response.getWriter().println("flow control");
        }
    });

• URL resource cleaning

  The Sentinel web servlet filter treats each unique incoming URL as a different resource. For RESTful APIs, you can implement the UrlCleaner interface to clean up the resources. For example, you can group all URLs that match /foo/:id under the /foo/* resource, and then register the implementation with WebCallbackManager. If you do not do this, the number of resources may become too large. If the resource count exceeds the threshold of 6000, the rules for any additional resources will not take effect.

  Example:

  @PostConstruct
  public void init() {
       // Register this globally only once.
      WebCallbackManager.setUrlCleaner(new UrlCleaner() {
          @Override
          public String clean(String originUrl) {
               // Transform originUrl to get the normalized URL.
              if (originUrl == null || originUrl.isEmpty()) {
                  return originUrl;
              }
               // For example, group all URLs that match /foo/:id under /foo/*.
              if (originUrl.startsWith("/foo/")) {
                  return "/foo/*";
              }
              return originUrl;
          }
      });
  }

• Parse request sources

  To throttle HTTP requests based on their source, you can implement the RequestOriginParser interface to parse the source from an HTTP request. Then, you can register the implementation with WebCallbackManager, as shown in the following example:

  WebCallbackManager.setRequestOriginParser(new RequestOriginParser() {
      @Override
      public String parseOrigin(HttpServletRequest request) {
          return request.getRemoteAddr();
      }
  });

Dubbo adapter

The Sentinel Dubbo adapter lets you configure a global fallback function. This function performs fallback processing when a Dubbo service is throttled, degraded, or under load protection. To use this feature, you can implement the custom DubboFallback interface and register it with DubboFallbackRegistry. By default, a BlockException is wrapped and thrown directly.

Other extension interfaces

Sentinel provides various Service Provider Interface (SPI) interfaces that you can use to extend its capabilities. You can extend interface implementations from sentinel-core to add custom logic to Sentinel. Sentinel provides the following extension points:

• Initialization process extension: You can use the InitFunc SPI interface to add custom initialization logic, such as registering dynamic rule sources.
• Slot chain extension: You can add custom features to the Sentinel feature chain and arrange them as required.
• Metric statistics extension (StatisticSlot Callback): You can extend the logic related to metric statistics for StatisticSlot.
• Transport extension: You can use interfaces such as CommandHandler and CommandCenter to extend features such as heartbeat sending and the monitoring API server.