{"id":15294744,"url":"https://github.com/lowes/auditor","last_synced_at":"2025-04-13T14:54:09.703Z","repository":{"id":42529910,"uuid":"460314173","full_name":"lowes/auditor","owner":"lowes","description":"Solves the audit needs for any JVM based application.","archived":false,"fork":false,"pushed_at":"2024-02-28T05:45:02.000Z","size":398,"stargazers_count":12,"open_issues_count":5,"forks_count":8,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-13T14:54:04.514Z","etag":null,"topics":["audit","audit-log","audit-trail","auditing","java","java-audit","jvm","kafka","kotlin","reactor","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lowes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2022-02-17T06:45:15.000Z","updated_at":"2022-12-15T07:30:03.000Z","dependencies_parsed_at":"2023-01-25T14:15:15.166Z","dependency_job_id":"12e42e61-2234-4571-8fe5-237d6f0a58f9","html_url":"https://github.com/lowes/auditor","commit_stats":{"total_commits":185,"total_committers":9,"mean_commits":"20.555555555555557","dds":"0.15135135135135136","last_synced_commit":"9e995377e5dd8669c96a13d79a196737a41cef2b"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowes%2Fauditor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowes%2Fauditor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowes%2Fauditor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowes%2Fauditor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lowes","download_url":"https://codeload.github.com/lowes/auditor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732512,"owners_count":21152851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit","audit-log","audit-trail","auditing","java","java-audit","jvm","kafka","kotlin","reactor","spring-boot"],"created_at":"2024-09-30T17:06:33.559Z","updated_at":"2025-04-13T14:54:09.680Z","avatar_url":"https://github.com/lowes.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auditor-v1\n[![GitHub Workflow Status (event)](https://img.shields.io/github/workflow/status/lowes/auditor/Gradle%20Package?event=push)](https://github.com/lowes/auditor/actions/workflows/gradle-publish.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.lowes/auditor-core)](https://search.maven.org/search?q=g:io.github.lowes%20AND%20a:auditor*)\n[![GitHub](https://img.shields.io/github/license/lowes/auditor)](https://github.com/lowes/auditor/blob/main/LICENSE)\n![GitHub Release Date](https://img.shields.io/github/release-date/lowes/auditor)\n[![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/io.github.lowes/auditor-core?server=https%3A%2F%2Fs01.oss.sonatype.org%2F)](https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/lowes/auditor-client/)\n[![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/lowes/auditor)](https://github.com/lowes/auditor/pulls?q=is%3Apr+is%3Aclosed)\n[![Code Climate maintainability](https://img.shields.io/codeclimate/maintainability-percentage/lowes/auditor)](https://codeclimate.com/github/lowes/auditor)\n[![Code Climate technical debt](https://img.shields.io/codeclimate/tech-debt/lowes/auditor)](https://codeclimate.com/github/lowes/auditor)\n[![Code Climate issues](https://img.shields.io/codeclimate/issues/lowes/auditor)](https://codeclimate.com/github/lowes/lowes/issues)\n[![Code Climate coverage](https://img.shields.io/codeclimate/coverage/lowes/auditor)](https://codeclimate.com/github/lowes/auditor)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)\n\nSolves the audit needs for any JVM based application.\n### Motivation\nAuditing is a cross-cutting concerns of many applications supporting business process/workflows.\nThere are some solutions out there like [Javers](https://javers.org/), [Audit4J](https://github.com/audit4j), [Log4j Audit](https://logging.apache.org/log4j-audit/latest/index.html) etc.. that aims to provide auditing functionality for java applications. \nHowever, most of them focus on capturing the audit information and storing in some sort of database or filesystem.\nWhile this is desirable in most traditional use cases, it becomes a challenge when microservices are serving high request throughput.\nThere are other challenges when aggregating audit information generated from hundreds of microservices.\nIn such cases, there's a need to decouple audits from business flows yet guarantee eventual consistency and performance.\nAuditor-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.\n\u003cbr/\u003e\u003cbr/\u003e\n### Highlights\n- It's easily pluggable: A client library that can be integrated into any jvm application, directly or via spring boot starter module.\nClient library offers simple one liner api for seamless integration.\n- It's async: Auditing happens asynchronously on a separate thread pool with retries to ensure eventual consistency.\n- It's efficient: Auditor uses [Project reactor](https://projectreactor.io/) behind the scene to utilize system's hardware efficiently.\n- It's performant: Auditor uses [jackson-afterburner](https://github.com/FasterXML/jackson-modules-base/tree/master/afterburner) for serialization needs which is both fast and performant.\n- It's scalable: It leverages [Kafka](https://kafka.apache.org/) as event streaming platform so benefit from the inherent scalability feature of kafka. \n- It's configurable: Highly configurable to meet different application custom needs ranging from logging, filtering, decorating(static data and dynamic templating) audit events.\n Supports both startup as well as runtime/dynamic configurations.\n\u003cbr/\u003e\u003cbr/\u003e\n### Architecture\n![image info](./docs/auditor-v1-architecture.png)\n\u003cbr/\u003e\u003cbr/\u003e\n### Modules\nThe project is composed of following modules:\n- [core](./core): Contains reusable code across other modules, primarily mappers, openapi spec auto-generated code etc.\n- [client](./client): Contains API and implementation code for the auditor library that will get plugged into applications thats needs audit feature.\n- [client-spring-boot-starter](./client-spring-boot-starter): It's a spring boot starter over client API(s). Useful for application that uses spring boot.\n- [client-example](./client-example): Example application to showcase standalone client usage.\n- [client-example-springboot](./client-example-springboot): Example application to showcase spring boot starter usage.\n- [app](./app): Contains deployable app that will listen to kafka and inserts the audit events and logs to elastic search.\n\u003cbr/\u003e\u003cbr/\u003e\n### Integration:\nThe modules are available on [maven central repo](https://search.maven.org/search?q=g:io.github.lowes%20AND%20a:auditor*). Just point your maven/gradle to maven central and you should be able to download the relevant modules.\n##### Gradle:\n```\nrepositories {\n    mavenCentral()\n}\n```\n##### Maven:\n```\n\u003crepositories\u003e\n  \u003crepository\u003e\n    \u003cid\u003ecentral\u003c/id\u003e\n    \u003cname\u003eMaven Central\u003c/name\u003e\n    \u003clayout\u003edefault\u003c/layout\u003e\n    \u003curl\u003ehttps://repo1.maven.org/maven2\u003c/url\u003e\n  \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\u003cbr/\u003e\u003cbr/\u003e\n### Using auditor-v1 client library\nIt can be integrated in either of following two ways.\n- #### Standalone mode:\n   Refer the [client module's README.md](./client/README.md) for how to use the client in standalone mode\n- #### Spring boot starter mode:\n    Spring boot starter module is built for applications that uses spring boot framework and comes with additional benefit of pre-initialized `Auditor` instance.\n    Refer the [client-spring-boot-starter module's README.md](./client-spring-boot-starter/README.md) for how to use the spring-boot-starter mode\n \u003cbr/\u003e\u003cbr/\u003e\n### Examples: Integration \u0026 Configurations\nyou can refer to the example modules:\n- [client-example](./client-example),\n- [client-example-springboot](./client-example-springboot)\n\non how to integrate with auditor client APIs.\nAuditor client configurations: [AuditorEventConfig.kt](./client/src/main/kotlin/com/lowes/auditor/client/entities/domain/AuditorEventConfig.kt)\ncan be provided both at startup time and during runtime.\nYou can also refer the `application.yml` in example modules to understand how to use different configurations at startup time.\nRuntime configurations can be also seen in examples modules code.\n\nRefer the [client-spring-boot-starter's README.md](./client-spring-boot-starter/README.md) to see full configuration options.\n\u003cbr/\u003e\u003cbr/\u003e\n \n### Using auditor-v1 app server\nAuditor server is present inside `app` module. Refer the [app module's README.md](./app/README.md) for how to use the app server.\n\u003cbr/\u003e\u003cbr/\u003e\n\n### Contributing: local-setup, development and testing:\nPlease refer to our [Contributing](./CONTRIBUTING.md) page for more details.\n\nFor any queries/community support reach out to stack overflow channel: \u003c//todo\u003e\n\n\n#### Running the app sever\nRefer the [app module's README.md](./app/README.md) for how to run the app server locally\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowes%2Fauditor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flowes%2Fauditor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowes%2Fauditor/lists"}