中文

loggable

AOP Log facilities to rescue you from logging java methods

Version changes

• 1.0.0 main features
• 1.0.1 fix autodetecting json frameworks
• 1.1.0 add support for Gson and Log Duration feature
• 1.1.1 fix DurationRecorder prototype
• 1.1.2 remove dependency spring-starter-logging, add support for xml config
• 1.1.3 remove incompatible java.lang.Parameter. fix test facilities.
• 1.2.0 add @LogScript, enhance stability
• 1.3.0 add spring boot support, default level on success from INFO to DEBUG

Set up

• add maven dependency:

   <dependency>
     <groupId>com.github.sea-huang</groupId>
     <artifactId>loggable</artifactId>
     <version>1.3.0</version>
   </dependency>

• optinally dependencies, alibaba's FastJson, Jackson or Gson will be auto detected to seriliaze the arguments and results. If neither found on the path, it will default to Object.toString()

   <dependency>
      <groupId>com.alibaba</groupId>
      <artifactId>fastjson</artifactId>
   </dependency>

   <dependency>
   	<groupId>com.fasterxml.jackson.core</groupId>
   	<artifactId>jackson-databind</artifactId>
   </dependency>

   <dependency>
   	<groupId>com.google.code.gson</groupId>
   	<artifactId>gson</artifactId>
   </dependency>

• Bring in the facilities

  @EnableLoggable
    @Configuration
    public class AnyConfigClass{
    
    }
    

  or XML config

   <bean class="com.github.seahuang.log.spring.LoggableAutoConfiguration">
   	<property name="globalLogDuration" value="true"/><!--optional-->
   </bean>

  for spring boot project, Loggable is auto configuired without any specific declaring. but two optional config available:

    loggable.enabled=false
    loggable.globalLogDuration=true
    

Usage Examples

• Service to be tested

  @Service
    public class TesteeService {
    	@Loggable("Purpose")
    	public String simpleCall(String stringArg, Integer intArg){
    		return "result";
    	}
    }
    

• Just add the @Loggable annotation to the method, and it will log all the arguments and result value as below:

2018-05-15 11:36:21.879  INFO 63398 --- [           main] 
c.g.seahuang.log.stub.TesteeService      :
Purpose Success! TesteeService.simpleCall(stringArg="AA",intArg=10) returns "result"

• On exception case:

ExexptionTest Fail! TesteeService.throwException(stringArg="AA",intArg=10)
	
java.lang.RuntimeException: Intentional Exception
		at com.github.seahuang.log.stub.TesteeService.throwException(TesteeService.java:35) ~[test-classes/:na]
		at com.github.seahuang.log.stub.TesteeService$$FastClassBySpringCGLIB$$5d883f5f.invoke() ~[test-classes/:na]
		at org.springframework.cglib.proxy.MethodProxy.invoke(MethodProxy.java:204) ~[spring-core-4.3.7.RELEASE.jar:4.3.7.RELEASE]
		at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.invokeJoinpoint(CglibAopProxy.java:721) ~[spring-aop-4.3.7.RELEASE.jar:4.3.7.RELEASE]
		at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:157) [spring-aop-4.3.7.RELEASE.jar:4.3.7.RELEASE]
		at org.springframework.validation.beanvalidation.MethodValidationInterceptor.invoke(MethodValidationInterceptor.java:139) ~[spring-context-4.3.7.RELEASE.jar:4.3.7.RELEASE]
		at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:179) [spring-aop-4.3.7.RELEASE.jar:4.3.7.RELEASE]
		at org.springframework.aop.aspectj.MethodInvocationProceedingJoinPoint.proceed(MethodInvocationProceedingJoinPoint.java:85) ~[spring-aop-4.3.7.RELEASE.jar:4.3.7.RELEASE]
		at com.github.seahuang.log.LoggableAspect.log(LoggableAspect.java:18) ~[classes/:na]
		...

• Wanna log only on Exception and keep silence in Success? Set Level.OFF on Success

@Loggable(value="SilenceSuccessTest", onSuccess=Level.OFF)
public String keepSilenceOnSuccess(String one, Integer two){
	return null;
}

• Wanna log warnning on some business exception?

@Loggable(value="Purpose", warningOn=BusinessException.class)
public String logWarnninngOnBusinessException(String one, Integer two){
	return null;
}

• More complicated case:

@Loggable("CustomizedLog")
public @LogLength List customizeLog(@LogIgnore String one
			, @LogFormat(ExceptionTypeFormatter.class) Exception t){
	...
}

• @LogLength only log the length of a collection or array.
• @LogIngore ignore the parameter or result when format the output
• @LogFormat give a self defined implementation class type for TypeFormatter, by which to format the parameter output
• @LogScript use script to customize the format, SPEL for default / javascript and other java supported script engines also included

 	@Loggable("Script log test")
	public @LogScript("#t.size() > 1 ? #t[0] + #t[1] : ''")List logScript(
			@LogScript("'arg1: ' + #t") String one
			,@LogScript("10 + #t") Integer two){
 
 

• Combine with Method Validation

@Loggable("validateMethod")
public @NotNull List validateParameters(@NotEmpty String one, @NotNull Integer two){
		return null;
}

• Log the duration time each method call costs

  • global setting, it will apply all @Loggable methods without specific LogDuration assigned or LogDuration equals to Default

    @EnableLoggable(logDuration=true)
    

  • each method call assign it's own Duration log strategy, which will override the global settings

    @Loggable(logDuration=LogDuration.YES)
    

Customization

• Refer to com.github.seahuang.log.spring.LoggableAutoConfiguration. All classes are connected by interfaces, and can be replaced by your own implementation.
• An important explanation, global customized exception log formatter can be apply by implemnt com.github.seahuang.log.formatter.LogFormatter or extend com.github.seahuang.log.formatter.LogFormatterSupport(should register to spring). the most precise exception formatter will be used.