# everettsy/log-record architecture

> Architecture diagram of the GitHub repository everettsy/log-record, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/everettsy/log-record
- Repository: https://github.com/everettsy/log-record

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    BusinessApp("Business Application (Annotated Methods)"):::client
    AOPAspect("AOP Logging Aspect (SystemLogAspect)"):::aop

    BusinessApp -->|"triggers"| AOPAspect

    subgraph "Log Record Core Module"
        CA("Custom Annotations (@OperationLog, etc.)"):::core
        UT("Utility & Context Management"):::core
        SI("Service Interfaces & Implementations"):::core
        DF("Diff Functionality"):::core
        CF("Custom Function Registration"):::core
        TP("Thread Pool Management"):::core
    end

    AOPAspect -->|"intercepts"| CA
    CA -->|"calls"| UT
    UT -->|"supports"| SI
    SI -->|"builds_LogDTO"| DF
    DF -->|"invokes"| CF
    CF -->|"async_via"| TP

    LDispatch("Log Dispatch / Data Pipeline"):::pipeline
    SI -->|"hands_off_LogDTO"| LDispatch

    subgraph "External Logging Pipelines"
        LLS("Local Log Service (IOperationLogGetService)"):::pipeline
        RMB("RabbitMQ Pipeline"):::pipeline
        RMQ("RocketMQ Pipeline"):::pipeline
        SCS("Spring Cloud Stream Pipeline"):::pipeline
    end

    LDispatch -->|"local"| LLS
    LDispatch -->|"rabbitMQ"| RMB
    LDispatch -->|"rocketMQ"| RMQ
    LDispatch -->|"cloudStream"| SCS

    subgraph "Starter Integration Modules"
        SB12("Spring Boot 1&2 Starter"):::integration
        SB3("Spring Boot 3 Starter"):::integration
    end

    SB12 -->|"auto-configures"| CA
    SB3 -->|"auto-configures"| CA

    click AOPAspect "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/aop/SystemLogAspect.java"
    click CA "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/annotation/OperationLog.java"
    click UT "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/context/LogRecordContext.java"
    click SI "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/service/IOperationLogGetService.java"
    click DF "https://github.com/everettsy/log-record/tree/master/log-record-core/src/main/java/cn/monitor4all/logRecord/bean"
    click CF "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/function/CustomFunctionRegistrar.java"
    click TP "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/thread/ThreadPoolProvider.java"
    click SB12 "https://github.com/everettsy/log-record/blob/master/log-record-starter/src/main/java/cn/monitor4all/logRecord/springboot/LogRecordAutoConfiguration.java"
    click SB3 "https://github.com/everettsy/log-record/blob/master/log-record-springboot3-starter/src/main/java/cn/monitor4all/logRecord/springboot3/LogRecordAutoConfiguration.java"
    click LLS "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/service/IOperationLogGetService.java"
    click RMB "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/service/impl/RabbitMqDataPipelineServiceImpl.java"
    click RMQ "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/service/impl/RocketMqDataPipelineServiceImpl.java"
    click SCS "https://github.com/everettsy/log-record/blob/master/log-record-core/src/main/java/cn/monitor4all/logRecord/service/impl/StreamDataPipelineServiceImpl.java"

    classDef client fill:#f9d6a5,stroke:#333,stroke-width:2px
    classDef aop fill:#c4e17f,stroke:#333,stroke-width:2px
    classDef core fill:#a2d2ff,stroke:#333,stroke-width:2px
    classDef integration fill:#ffb7b2,stroke:#333,stroke-width:2px
    classDef pipeline fill:#ffdfba,stroke:#333,stroke-width:2px
```
