Integrate applications using custom instrumentation

Procedure

1. Log on to the AHAS console.

2. In the upper-left corner of the AHAS console, select your application's region.

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

4. On the Application Protection page, click New application in the upper-right corner. On the JAVA tab, click SDK, and then click Custom.

5. Add the Application Protection dependency to your application using one of the following methods:

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

     <dependency>
       <groupId>com.alibaba.csp</groupId>
       <artifactId>ahas-sentinel-client</artifactId>
       <!-- You can specify a version. For the latest version, see the New application page for Application Protection in the AHAS console. -->
       <version>x.y.z</version>
     </dependency>

     On the Custom page, find the latest version number in the Step 1: Add the Pom dependency section and replace x.y.z with it.

     

   • Add the dependency by using JAR files.

     On the Custom page, click Download to download the compressed package, and place all JAR files from the package into the classpath directory.

6. To add instrumentation, wrap your business logic in the following code:

   Entry entry = null;
   try {
    // "HelloWorld" is the resource name. This name is used for monitoring and is displayed in the call chain in the console.
    // Rules are configured for specific resource names.
    // EntryType.IN identifies the resource as an inbound resource. System rules apply only to inbound resources.
     entry = SphU.entry("HelloWorld", EntryType.IN);
   
    // Protected business logic.
     System.out.println("Hello Sentinel!");
   } catch (BlockException e) {
    // This block is executed when a throttling or degradation event is triggered. Implement your handling logic here, such as a fallback or logging.
   } finally {
    // Ensure that the exit() method is called here and is paired with SphU.entry().
     if (entry != null) {
     entry.exit();
    }
   }

   Note

   • Use EntryType to distinguish between inbound and outbound traffic. EntryType.IN represents inbound traffic, and EntryType.OUT represents outbound traffic. System rules apply only to inbound resources.

   • The total application traffic shown in the console counts only EntryType.IN traffic.

   • For more information about the SphU API, see Common classes and their methods.

   • Resource names for custom instrumentation cannot exceed 1,024 characters.

7. Configure the startup parameters for your application.

   Type	Parameter example
   private network	-Dproject.name=AppName -Dahas.namespace=default -Dahas.regionId=<RegionId> Note Replace AppName with your application name. Replace <RegionId> with the ID of the region where your application is located. For a list of regions and their corresponding RegionIds, see the Region and RegionId Mapping Table.
   public network	-Dproject.name=AppName -Dahas.license=<license> -Dahas.namespace=default -Dahas.regionId=cn-public Note Replace AppName with a custom application name and <license> with your actual license key.

   A license is required for applications in a public network region but not for those in private network regions. You can find the license key in the Step 3: Configure startup parameters section. For more information, see View a license.

   

8. Restart your application.

9. Optional: Use annotations to configure the handling logic for when your application triggers throttling, degradation, or system protection rules. For more information, see Annotation-based configuration.

   Note

   By default, the application throws a subclass of BlockException when a rule triggers. A FlowException is thrown when a flow control rule triggers, and a DegradeException is thrown when a degradation rule triggers.

Verify the results

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

Region and Region ID mapping