How everettsy/log-record works
Main Components
• Core Library: The “log-record-core” module contains the business logic. It holds:
– Custom annotations (e.g., @OperationLog, @LogRecordDiffField, @LogRecordDiffObject, and @LogRecordFunc).
– AOP advice (e.g., SystemLogAspect) that intercepts annotated methods.
– Utility packages (for JSON processing, context management via LogRecordContext, thread pool management, etc.).
– Service interfaces and implementation (e.g., IOperationLogGetService and DataPipelineService implementations for RabbitMQ, RocketMQ, and Spring Cloud Stream).
– “Diff” functionality that computes differences between objects using the built-in _DIFF function.
• Starter Integration Modules: There are different integration modules such as “log-record-starter” (for Spring Boot1 & 2) and “log-record-springboot3-starter” (for Spring Boot3) that provide auto-configuration and seamless integration with Spring Boot. They use Spring’s auto-configuration mechanisms (e.g., configuration files inside META-INF/spring) to provide the required beans.
• External Pipelines: The project is designed to send logs to various outputs. Depending on configuration, the log data (wrapped in a LogDTO) can be:
– Processed by a local log service (via an implementation of IOperationLogGetService).
– Sent to external systems via integrations with RabbitMQ, RocketMQ, or Spring Cloud Stream.
• Custom Function & SpEL Infrastructure: It includes custom function registration (using classes annotated with @LogRecordFunc) so that developers can plug in their own SpEL functions. This also includes use of SpEL for evaluating input parameters, retrieving context values, and even computing object diffs.
• Asynchronous Processing: The project uses its own custom thread pool (provided by ThreadPoolProvider implementations) to asynchronously process and dispatch logs, ensuring minimal impact on application performance.
Component Relationships and Interactions
• The business application (using this library) annotates methods with @OperationLog.
• When these methods are invoked:
– The AOP aspect (SystemLogAspect) intercepts the call.
– Before or after method execution (depending on the “executeBeforeFunc” flag), the aspect triggers the evaluation of SpEL expressions.
– This involves gathering data from method parameters, context variables (via LogRecordContext), and even invoking custom functions.
– Once the log parameters are prepared, a LogDTO is built.
• The built LogDTO then gets handed off to a log handling service:
– Directly processing via a locally implemented IOperationLogGetService or,
– By pushing the log through a selected Data Pipeline (e.g., RabbitMQ, RocketMQ, or Spring Cloud Stream), configured via properties.
– The processing is often done asynchronously using a dedicated thread pool.
• The “starter” modules (log-record-starter and log-record-springboot3-starter) wrap the core functionality in proper auto-configuration for seamless integration.
Important Architectural Patterns and Design Principles
• Separation of Concerns: Logging logic is completely separated from business logic through annotations and AOP.
• Modular Architecture: Different modules for core functionality vs. integration with specific Spring Boot versions.
• Extensibility: Custom functions and configurable pipelines (via properties and SPI mechanisms) allow easy extension.
• Asynchronous Processing: Use of thread pools ensures that log processing does not delay business operations.
• Declarative Programming: Use of annotations and SpEL to minimize code intrusion.
Relevant Technologies and Frameworks
• Java and Spring Boot (supporting versions for Java 8 to Java 21).
• Spring AOP for method interception.
• Spring Expression Language (SpEL) for dynamic log message and parameter resolution.
• Messaging systems (RabbitMQ, RocketMQ, Spring Cloud Stream) for external log pipelines.
• Maven for project building and dependency management.
• JUnit (and other testing frameworks) for testing, as evident from the abundant test directories.