Auditor-v1

Solves the audit needs for any JVM based application.

Motivation

Auditing is a cross-cutting concerns of many applications supporting business process/workflows. There are some solutions out there like Javers, Audit4J, Log4j Audit etc.. that aims to provide auditing functionality for java applications. However, most of them focus on capturing the audit information and storing in some sort of database or filesystem. While this is desirable in most traditional use cases, it becomes a challenge when microservices are serving high request throughput. There are other challenges when aggregating audit information generated from hundreds of microservices. In such cases, there's a need to decouple audits from business flows yet guarantee eventual consistency and performance. Auditor-v1 is an attempt to solve this.It offers a client library, and an app server that captures audit events at high throughput in distributed way.

Highlights

It's easily pluggable: A client library that can be integrated into any jvm application, directly or via spring boot starter module. Client library offers simple one liner api for seamless integration.
It's async: Auditing happens asynchronously on a separate thread pool with retries to ensure eventual consistency.
It's efficient: Auditor uses Project reactor behind the scene to utilize system's hardware efficiently.
It's performant: Auditor uses jackson-afterburner for serialization needs which is both fast and performant.
It's scalable: It leverages Kafka as event streaming platform so benefit from the inherent scalability feature of kafka.
It's configurable: Highly configurable to meet different application custom needs ranging from logging, filtering, decorating(static data and dynamic templating) audit events. Supports both startup as well as runtime/dynamic configurations.

Architecture

Modules

The project is composed of following modules:

core: Contains reusable code across other modules, primarily mappers, openapi spec auto-generated code etc.
client: Contains API and implementation code for the auditor library that will get plugged into applications thats needs audit feature.
client-spring-boot-starter: It's a spring boot starter over client API(s). Useful for application that uses spring boot.
client-example: Example application to showcase standalone client usage.
client-example-springboot: Example application to showcase spring boot starter usage.
app: Contains deployable app that will listen to kafka and inserts the audit events and logs to elastic search.

Integration:

The modules are available on maven central repo. Just point your maven/gradle to maven central and you should be able to download the relevant modules.

Gradle:

repositories {
    mavenCentral()
}

Maven:

<repositories>
  <repository>
    <id>central</id>
    <name>Maven Central</name>
    <layout>default</layout>
    <url>https://repo1.maven.org/maven2</url>
  </repository>
</repositories>

Using auditor-v1 client library

It can be integrated in either of following two ways.

Standalone mode:
Refer the client module's README.md for how to use the client in standalone mode
Spring boot starter mode:
Spring boot starter module is built for applications that uses spring boot framework and comes with additional benefit of pre-initialized Auditor instance. Refer the client-spring-boot-starter module's README.md for how to use the spring-boot-starter mode

Examples: Integration & Configurations

you can refer to the example modules:

on how to integrate with auditor client APIs. Auditor client configurations: AuditorEventConfig.kt can be provided both at startup time and during runtime. You can also refer the application.yml in example modules to understand how to use different configurations at startup time. Runtime configurations can be also seen in examples modules code.

Refer the client-spring-boot-starter's README.md to see full configuration options.

Using auditor-v1 app server

Auditor server is present inside app module. Refer the app module's README.md for how to use the app server.

Contributing: local-setup, development and testing:

Please refer to our Contributing page for more details.

For any queries/community support reach out to stack overflow channel: <//todo>

Running the app sever

Refer the app module's README.md for how to run the app server locally

lowes / auditor