Integrate a web application

Procedure

1. Log on to the AHAS console.

2. In the upper-left corner of the AHAS console, select the region where your application is deployed.

3. In the left-side navigation pane, choose Traffic Protection > Application Protection.

4. In the upper-right corner of the Application Protection page, click Add Application. On the Java tab, click SDK Access, and then click Web Application Access.

5. Add the application protection dependency to your web application using one of the following methods.

   • Add the following dependency to your web application's pom.xml file.

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

     On the Web Application Access page, find the latest dependency version in the Step 1: Add Pom Dependency section. Replace x.y.z with the latest version number.

     

   • Add JAR package dependencies.

     On the Web Application Access page, click Download to get the compressed package. Place all JAR files from this package into the classpath directory.

6. In the web.xml file, add the filter and configure it as the first filter. The following code shows an example:

   <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>
   <!-- Configure the URL patterns to intercept. -->
       <url-pattern>/*</url-pattern>
   </filter-mapping>

7. Configure the startup parameters for your application.

   Category	Example configuration
   internal network	-Dproject.name=AppName -Dahas.namespace=default -Dahas.regionId=<RegionId> Note Replace AppName with your application's name. Replace <RegionId> with the ID of the region where your application is deployed. For a list of regions and their corresponding region IDs, see the Regions and region IDs table in this topic.
   public network	-Dproject.name=AppName -Dahas.license=<license> -Dahas.namespace=default -Dahas.regionId=cn-public Note Replace AppName with your application's name and replace <license> with your license key.

   Applications on the public network require a license. Applications on an internal network do not. You can find your license in the Step 3: Configure startup parameters section. For more information, see View the license.

   

8. Optional: You can set a custom redirect URL in the following two ways. When a request triggers traffic control, degradation, or a system protection rule, the request is automatically redirected to the specified URL.

   • Call the WebServletConfig.setBlockPage(blockPage) method to set a custom redirect URL.

   • Implement the UrlBlockHandler interface to define custom blocking logic, and then register the logic with WebCallbackManager. For more information, see Web Servlet Filter extension interface.

   Note

   By default, when a traffic control, degradation, or system protection rule blocks a request, AHAS returns a default page with the following message: Blocked by Sentinel (flow limiting).

9. Optional: You can customize URL cleanup to prevent an excessive accumulation of REST-style URLs, such as /payment/{id}, from affecting system performance. There are two ways to configure URL cleanup:

   • Implement the UrlCleaner interface to define custom URL normalization logic. For more information, see Web Servlet Filter.

   • Configure prefix-based cleaning by using a properties file.

     In the properties file, define rules using the format 'matching prefix=normalized resource name', for example, /payment/=/payment/*. Then, specify the configuration file path by using the -Dcsp.sentinel.url.clean.config.path startup parameter.

     Note

     By default, the startup parameter points to the ahas-sentinel-url-clean.properties file, which is expected to be in the same directory as the JAR package. The startup parameter supports the classpath format. For example: -Dcsp.sentinel.url.clean.config.path=classpath:ahas-sentinel-url-clean.properties.

Verify the integration

Log on to the AHAS console. In the left-side navigation pane, choose Traffic Protection > Application Protection. The integration is successful if the application card for your application appears on the Application Protection page and reports data.

Regions and region IDs