JarCastingAutolog
A library providing capabilities for automatic logging in Java applications.
Modules
autolog-core
This is the core module of the library: it provides the core logging features independently of the implementation chosen for automation.
autolog-aspectj
This module provides aspects for logging automation based on AspectJ weaving and using annotations defined in autolog-core module.
autolog-spring
This module is the implementation of the logging automation based on Spring AOP and using annotations defined in autolog-core module. It acts as a Spring Boot starter by providing auto-configuration class for Autolog.
autolog-coverage-reporting
This module is only used to generate a code coverage report for the entire project.
Getting started
Prerequisites
Using Autolog requires JDK 11 or greater.
Installing
The latest release of Autolog is available on Maven Central. You can install Autolog in your application using one of the following Maven dependencies:
- In a Spring application:
<dependency>
<groupId>com.github.maximevw</groupId>
<artifactId>autolog-spring</artifactId>
<version>1.2.0</version>
</dependency>
- In an application using AspectJ weaving for logging automation by AOP:
<dependency>
<groupId>com.github.maximevw</groupId>
<artifactId>autolog-aspectj</artifactId>
<version>1.2.0</version>
</dependency>
- In a classic Java application, you can use logging methods provided by Autolog without automation by AOP (not recommended):
<dependency>
<groupId>com.github.maximevw</groupId>
<artifactId>autolog-core</artifactId>
<version>1.2.0</version>
</dependency>
Usage
Autolog annotations
Basically, Autolog provides two types of annotations used to automatically generates log thanks to AOP (using Spring AOP implementation in the module autolog-spring or AspectJ weaving in the module autolog-aspectj):
@AutoLogMethodInOut,@AutoLogMethodInputand@AutoLogMethodOutput: it helps to log, respectively, the input and output data of methods, the input data only and the output data only. It can also be used to automatically log exceptions.@AutoLogPerformance: it helps to monitor and log the performance (execution time, failures, ...) of invoked methods during the execution of an application. Please note that the usage of this annotation may impact the performance of your application. If you need high performance during the execution of your code, don't use it (especially in production).
These annotations can be located on classes or methods (or both, in this case the configuration of the annotations at method level gets the priority). For further information about the configuration of each annotation, please consult the Javadoc.
@Mask: only located on method arguments, it allows masking (totally or partially) the values of arguments logged thanks to the annotation@AutoLogMethodInOutor@AutoLogMethodInput.
Loggers management
Each time Autolog will log something, it will use the loggers configured in a LoggerManager instance (which is a Spring-managed bean in Spring applications). The LoggerManager maintains a list of all the loggers to use, so Autolog is able to log the information at different places simultaneously. The real loggers instances managed by LoggerManager are wrapped in singleton adapters implementing LoggerInterface. By default, Autolog provides the following adapters:
JavaLoggerAdapter: wraps an instance of the classicjava.util.logging.LoggerLog4j2Adapter: wraps an instance oforg.apache.logging.log4j.LoggerSlf4jAdapter: wraps an instance oforg.slf4j.LoggerLogbackWithLogstashAdapter: wraps an instance oforg.slf4j.Loggerwhich should use Logback implementation with Logstash encoderSystemOutAdapter: wraps the standard output (System.outandSystem.err)XSlf4jAdapter: wraps an instance oforg.slf4j.ext.XLogger- (Experimental)
JdbcAdapter: persists log events into a database using JDBC.
In Spring Boot applications, the LoggerManager can be configured in the application properties (by setting the list of LoggerInterface implementations to register in the property autolog.loggers) thanks to the auto-configuration class AutologAutoConfiguration.
Usage with AspectJ weaving
In order to use AspectJ weaving for logging automation by AOP, in addition to the dependency to autolog-aspectj, ensure to have org.aspectj:aspectjrt in your classpath and to compile your application using AspectJ weaving, including the dependency to autolog-aspectj in the weaved dependencies.
At the starting of your application, insert the following code to instantiate the LoggerManager required by Autolog for logging automation:
public class HelloApplication {
public static void main(final String[] args) {
// Instantiate Autolog.
final LoggerManager loggerManager = new LoggerManager();
// Register any loggers you want to use. See LoggerManager documentation for further details.
// loggerManager.register(...);
AspectJLoggerManager.getInstance().init(loggerManager);
// Put the code of your application here...
}
}
Now, you can use Autolog annotations into your application.
Basic example with a Spring application
Assuming your application is a REST API developed with Spring Web framework using an implementation of Slf4j for logging.
Here is the main class of your application:
@SpringBootApplication
@EnableAspectJAutoProxy
@EnableAutoConfiguration
public class HelloApplication {
public static void main(String[] args) {
SpringApplication.run(HelloApplication.class, args);
}
}
The configuration file of your Spring application contains the following property:
autolog.loggers=Slf4jAdapter
Here is your web controller using Autolog annotations with default configuration:
@RestController
@AutoLogMethodInOut
@AutoLogPerformance
public class HelloWebController {
@Autowired
private HelloService helloService;
@GetMapping("/hello")
public String sayHello(@RequestParam final String name) {
return helloService.sayHello(name);
}
}
Here is the service, called by the web controller, using Autolog annotations with default configuration:
@Service
@AutoLogMethodInOut
@AutoLogPerformance
public class HelloService {
public String sayHello(final String name) {
return "Hello " + name + "!";
}
}
When the API endpoint GET /hello?name=John is called, Autolog produces the following logs:
INFO Entering HelloWebController.sayHello(name=John)
INFO Entering HelloService.sayHello(name=John)
INFO Exiting HelloService.sayHello() returning Hello John!
DEBUG Method HelloService.sayHello executed in 6 ms (started: 2019-12-30 14:30:25.602, ended: 2019-12-30 14:30:25.608).
INFO Exiting HelloWebController.sayHello() returning Hello John!
DEBUG Method [GET] /hello executed in 10 ms (started: 2019-12-30 14:30:25.600, ended: 2019-12-30 14:30:25.610).
DEBUG Performance summary report for /hello:
DEBUG > /hello executed in 10 ms
DEBUG |_ > HelloService.sayHello executed in 6 ms
More examples are available in this GitHub repository.
Contributing
If you want to contribute to Autolog project, please read the content of CONTRIBUTING file.
Versioning
Autolog uses Semantic Versioning.
License
Autolog is distributed under Apache License 2.0.
Next features
Find below a non-exhaustive (and not sorted by priority) list of features we've planned to develop:
-
@AutoLogannotation and logging profilesA new annotation
@AutoLoggrouping the behaviour of both annotations@AutoLogMethodInOutand@AutoLogPerformanceand using a configuration file (classpath:autolog.yamlby default) to define the parameters used to generate logs. For example: using@AutoLog(profile = "customProfile") public void exampleMethod() { }
instead of
@AutoLogMethodInOut(/*custom parameters...*/) @AutoLogPerformance(/*custom parameters...*/) public void exampleMethod() { }
In Spring Boot auto-configuration, the profiles could be directly defined in the application property
autolog.profiles. -
Additional logger
Provide new implementation
KafkaAdapterofLoggerInterfaceto directly publish the generated logs in Kafka topics. -
Log HTTP requests and responses
Automate the logging of HTTP requests and responses for applications providing a REST API (using JAX-RS or Spring Web Framework) by using servlet filters.
-
Loggers configuration by profile
Register different loggers in the different defined logging profiles. For example: a custom profile uses
SystemOutAdapterand another oneSlf4jAdapter.In a given profile, the used loggers could also be different: for example the performance information logging uses
SystemOutAdapterand the logging of input/output data usesLog4j2Adapter.