Skip to content

README.md

Latest commit

 

History

History
229 lines (163 loc) · 6.95 KB

README.md

File metadata and controls

229 lines (163 loc) · 6.95 KB

BitDive Java Producer

Java Spring Boot Instrumentation License

Java runtime instrumentation and capture layer for BitDive.

This repository contains the BitDive JVM-side components that observe real application behavior, serialize runtime context, and deliver that data into the BitDive platform. It combines ByteBuddy-based instrumentation, Spring integration, async file buffering, background upload, and JVM metrics collection.

Demo

Watch the BitDive demo

Watch the BitDive product demo on YouTube:

Overview

java-producer is the component that makes BitDive possible inside a running Java application.

From the code in this repository, it currently covers:

  • runtime bytecode instrumentation via ByteBuddy
  • Spring Boot integration for 2.7 and 3.x
  • tracing of method execution, SQL, HTTP, Kafka, and other downstream calls
  • async local buffering to rotating files
  • background upload of archived trace data
  • object serialization controls, masking, and collection limits
  • JVM metrics capture through Micrometer-backed collectors

Modules

Module Role
java-producer-parent Main runtime artifact with shaded agent dependencies and core runtime logic
bitdive-producer-core Core config loader and shared DTO/config contracts
bitdive-producer-spring-2 Spring Boot 2.7 integration
bitdive-producer-spring-3 Spring Boot 3.x integration

What It Captures

Based on the current agent initialization and Spring wiring, this repository instruments or enriches:

  • method execution and call timing
  • method arguments and return values
  • HTTP request and response flow
  • RestTemplate and Feign client traffic
  • JDBC drivers, SQL statements, and result-set reads
  • Kafka producer and consumer flow
  • scheduler execution
  • repository and cache interactions through Spring aspects
  • STOMP messaging handlers
  • Cassandra, MongoDB, Redis, Neo4j, and OpenSearch hooks
  • S3-compatible clients including AWS SDK and MinIO
  • thread context propagation
  • JVM metrics snapshots

Runtime Pipeline

The producer runtime follows this pipeline:

  1. initialize BitDive bootstrap and config
  2. install ByteBuddy instrumentation into the running JVM
  3. capture runtime events from web, DB, messaging, and application code
  4. serialize and filter captured data
  5. write events asynchronously to local rotating files
  6. archive and upload files to the BitDive backend in the background

Spring Integration

The Spring modules do more than expose a dependency.

From the current code and resource metadata:

  • Spring Boot 3 uses AutoConfiguration.imports for io.bitdive.SpringConfigProfiling
  • Spring Boot 2.7 registers ByteBuddyAgentInitializer, SpringConfigProfiling, and BitDiveBootstrapRegistryInitializer through spring.factories
  • conditional aspects are enabled for supported frameworks only

The Spring configuration currently wires aspects for:

  • repositories
  • cacheable methods
  • Feign clients
  • scheduled methods
  • Kafka listeners
  • STOMP message mapping and send-to handlers

Configuration Model

There are two distinct configuration layers in the codebase.

1. Bootstrap discovery config

bitdive-producer-core loads config-profiling-api.yml from the classpath. That file is used to resolve:

  • moduleName
  • serviceName
  • packedScanner
  • serverUrl
  • token

Minimal shape:

bitdive:
  monitoring:
    moduleName: user-api
    serviceName: customer-service
    packedScanner:
      - com.example
    serverUrl: https://your-bitdive-server/monitoring-api
    token: your-token

2. Runtime profiling config

At runtime, the agent loads bundled defaults from config-profiling-default.yml and then:

  • applies local overrides from config-profiling.yml if present, or
  • requests the effective service config remotely via the BitDive API

The runtime config model in code includes:

  • application identity
  • per-profile monitoring config selection
  • log level and monitoring enablement
  • argument and return capture flags
  • SQL driver capture flag
  • serialization exclusions and sensitive keywords
  • local data-file storage settings
  • upload server and proxy settings
  • Vault settings

Dependency Setup

Official setup guide:

Spring Boot 3:

<dependency>
  <groupId>io.bitdive</groupId>
  <artifactId>bitdive-producer-spring-3</artifactId>
  <version>YOUR_VERSION</version>
</dependency>

Spring Boot 2.7:

<dependency>
  <groupId>io.bitdive</groupId>
  <artifactId>bitdive-producer-spring-2</artifactId>
  <version>YOUR_VERSION</version>
</dependency>

Core contract/config artifact:

<dependency>
  <groupId>io.bitdive</groupId>
  <artifactId>bitdive-producer-core</artifactId>
  <version>YOUR_VERSION</version>
</dependency>

Selective Control

The repository also includes opt-in and opt-out annotations:

  • @MonitoringClass
  • @NotMonitoring
  • @NotMonitoringParamsClass
  • @NotMonitoringParamsField

These allow selective inclusion or exclusion for captured types, methods, and serialized fields.

Data Handling Notes

The codebase includes several safeguards and shaping layers around captured runtime data:

  • masking filters for sensitive values
  • serialization modifiers for complex object graphs
  • collection-size limiting
  • Hibernate-aware serialization support
  • placeholder serializers for images, streams, and other heavy objects
  • async queue-based file writing with rotation and gzip archiving

Requirements

  • Java 8+
  • Spring Boot 2.7 or 3.x for the Spring modules
  • access to a BitDive backend endpoint and token

Build

mvn clean package

Repository Scope

This repository is the JVM capture layer.

It does not provide:

  • the MCP bridge for AI agents
  • the BitDive backend UI and storage stack
  • the JUnit replay runner used for trace-based regression tests

Those responsibilities live in other BitDive repositories.

Documentation

License

This repository includes an Elastic License 2.0 license file. The Maven metadata also references BitDive licensing documentation, so if licensing and distribution terms matter for your use case, review both the repository license file and the current BitDive license documentation before redistribution.