How-to-tolerate-exceptions.md

How to tolerate custom exceptions

In some codes, the exception is being used as a way of controlling business flow. Skywalking provides 2 ways to tolerate an exception which is traced in a span.

1. Set the names of exception classes in the agent config
2. Use our annotation in the codes.

Set the names of exception classes in the agent config

The property named "statuscheck.ignored_exceptions" is used to set up class names in the agent configuration file. if the exception listed here are detected in the agent, the agent core would flag the related span as the error status.

Demo

1. A custom exception.

   • TestNamedMatchException

   package org.apache.skywalking.apm.agent.core.context.status;
   
   public class TestNamedMatchException extends RuntimeException {
       public TestNamedMatchException() {
       }
       public TestNamedMatchException(final String message) {
           super(message);
       }
       ...
   }

   • TestHierarchyMatchException

   package org.apache.skywalking.apm.agent.core.context.status;
   
   public class TestHierarchyMatchException extends TestNamedMatchException {
       public TestHierarchyMatchException() {
       }
       public TestHierarchyMatchException(final String message) {
           super(message);
       }
       ...
   }

2. When the above exceptions traced in some spans, the status is like the following.

   The traced exception	Final span status
   org.apache.skywalking.apm.agent.core.context.status.TestNamedMatchException	true
   org.apache.skywalking.apm.agent.core.context.status.TestHierarchyMatchException	true

3. After set these class names through "statuscheck.ignored_exceptions", the status of spans would be changed.

   statuscheck.ignored_exceptions=org.apache.skywalking.apm.agent.core.context.status.TestNamedMatchException
   

   The traced exception	Final span status
   org.apache.skywalking.apm.agent.core.context.status.TestNamedMatchException	false
   org.apache.skywalking.apm.agent.core.context.status.TestHierarchyMatchException	false

Use our annotation in the codes.

If an exception has the @IgnoredException annotation, the exception wouldn't be marked as error status when tracing. Because the annotation supports inheritance, also affects the subclasses.

Dependency

• Dependency the toolkit, such as using maven or gradle. Since 8.2.0.

   <dependency>
      <groupId>org.apache.skywalking</groupId>
      <artifactId>apm-toolkit-log4j-1.x</artifactId>
      <version>{project.release.version}</version>
   </dependency>

Demo

1. A custom exception.

   package org.apache.skywalking.apm.agent.core.context.status;
   
   public class TestAnnotatedException extends RuntimeException {
      public TestAnnotatedException() {
      }
      public TestAnnotatedException(final String message) {
          super(message);
      }
      ...
   }

2. When the above exception traced in some spans, the status is like the following.

   The traced exception	Final span status
   org.apache.skywalking.apm.agent.core.context.status.TestAnnotatedException	true

3. However, when the exception annotated with the annotation, the status would be changed.

   package org.apache.skywalking.apm.agent.core.context.status;
   
   @IgnoredException
   public class TestAnnotatedException extends RuntimeException {
   
       public TestAnnotatedException() {
       }
       public TestAnnotatedException(final String message) {
           super(message);
       }
       ...    
   }

   The traced exception	Final span status
   org.apache.skywalking.apm.agent.core.context.status.TestAnnotatedException	false

Recursive check

Due to the wrapper nature of Java exceptions, sometimes users need recursive checking. Skywalking also supports it. Typically, we don't recommend setting this more than 10, which could cause a performance issue. Negative value and 0 would be ignored, which means all exceptions would make the span tagged in error status.

    statuscheck.max_recursive_depth=${SW_STATUSCHECK_MAX_RECURSIVE_DEPTH:1}