VFL Client Java Framework v0.1.0 Alpha

The first alpha release of the Visual Flow Logger (VFL) Client Java Framework - a structured, hierarchical logging solution for Java applications.

What is VFL?

VFL transforms traditional flat logging into a tree-like structure that shows how your application executes. Instead of conventional logging systems, VFL creates a hierarchical view of your application flow for easier debugging, monitoring, and performance analysis.

Key Features

Minimal Integration

Add @SubBlock annotations to existing methods - no major refactoring required
Integrates with existing codebases
Zero-impact when disabled

Hierarchical Logging

View your application flow as a tree structure
Trace nested method calls and their relationships
Clear parent-child relationships between operations

Distributed Tracing

Track operations across multiple services and systems
Maintain trace context across HTTP calls and message queues
Support for continuation blocks and cross-service tracing

Asynchronous Support

Built-in support for CompletableFuture and async operations
Automatic trace context propagation to background threads
Thread-safe execution with proper context isolation

Event-Driven Patterns

Support for pub/sub and event-driven architectures
Link event publishers to their consumers in the trace
Track async event processing across the system

Quick Start

1. Add Repository and Dependency

Maven:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.kuchuk-borom-debbarma</groupId>
    <artifactId>Visual-Flow-Logger-Framework-JAVA</artifactId>
    <version>0.1.0-alpha</version>
</dependency>

Gradle:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.kuchuk-borom-debbarma:Visual-Flow-Logger-Framework-JAVA:0.1.0-alpha'
}

2. Initialize VFL

// Initialize VFL with VFL Hub
VFLFlushHandler flushHandler = new VFLHubFlushHandler(
    URI.create("http://localhost:8080")
);

VFLBuffer buffer = new AsyncBuffer(100, 3000, 1000, flushHandler, 
    Executors.newVirtualThreadPerTaskExecutor(),
    Executors.newSingleThreadScheduledExecutor());

VFLInitializer.initialize(new VFLAnnotationConfig(false, buffer));

3. Add Tracing to Your Code

public class OrderService {
    
    public void processOrder(String orderId) {
        VFLStarter.StartRootBlock("Process Order", () -> {
            validateOrder(orderId);
            chargePayment(orderId);
            createRecord(orderId);
        });
    }
    
    @SubBlock(blockName = "Validate Order {0}")
    private void validateOrder(String orderId) {
        Log.Info("Validating order {}", orderId);
        // Your validation logic
    }
    
    @SubBlock(blockName = "Charge Payment {0}")  
    private void chargePayment(String orderId) {
        Log.Info("Processing payment for {}", orderId);
        // Your payment logic
    }
}

4. View Your Traces

Open your VFL Hub dashboard at http://localhost:8080 to see the hierarchical visualization.

Core Components

VFLStarter - Entry Points

StartRootBlock() - Begin new traces
ContinueFromBlock() - Continue distributed traces
StartEventListener() - Handle async events

@subblock Annotation - Method Tracing

Automatic sub-block creation for annotated methods
Placeholder support: {0}, {1} for arguments, {r} for return values
Optional start/end messages

Log Class - Structured Logging

Log.Info(), Log.Warn(), Log.Error() - Standard logging levels
Log.Publish() - Create event publisher blocks
Log.CreateContinuationBlock() - Cross-service tracing

VFLFutures - Async Operations

VFLFutures.supplyAsync() - Async operations with trace context
VFLFutures.runAsync() - Fire-and-forget async tasks
Automatic context propagation to background threads

Buffer Implementations

AsyncBuffer - High-performance async flushing with background threads
SynchronousBuffer - Simple blocking flush for guaranteed ordering
NoOpsBuffer - Disable all logging (testing/production toggle)

Flush Handlers

VFLHubFlushHandler - Send to VFL Hub server (recommended)
NestedJsonFlushHandler - Generate nested JSON files (development only)
NoOpsFlushHandler - Discard all data

Advanced Features

Distributed Tracing Example

// Service A
public void serviceA() {
    VFLStarter.StartRootBlock("Service A Operation", () -> {
        Log.CreateContinuationBlock("Call Service B", block -> {
            callServiceB(serialize(block));
        });
    });
}

// Service B  
public void serviceB(String serializedBlock) {
    Block block = deserialize(serializedBlock);
    VFLStarter.ContinueFromBlock(block, () -> {
        Log.Info("Processing in Service B");
        // Your service B logic
    });
}

Event-Driven Processing

public void processOrder(String orderId) {
    VFLStarter.StartRootBlock("Order Processing", () -> {
        // Publish event
        EventPublisherBlock event = Log.Publish("Order Created", 
            "Order {} created", orderId);
        
        // Handle event asynchronously  
        handleOrderEvent(event, orderId);
    });
}

private void handleOrderEvent(EventPublisherBlock event, String orderId) {
    VFLStarter.StartEventListener(event, "Order Handler", () -> {
        sendConfirmationEmail(orderId);
        updateInventory(orderId);
    });
}

Alpha Release Notes

This is an alpha release suitable for:

Early adopters and feedback collection
Development and testing environments
Proof of concept implementations
Community evaluation

Not recommended for:

Production systems without thorough testing
Mission-critical applications
High-volume production workloads

Requirements

Java 11+ (Java 21+ recommended for Virtual Threads)
VFL Hub Server running for visualization
Maven or Gradle build system

Documentation

[User Guide](README.md) - Complete usage documentation
[System Overview](documentations/System_OVerview.MD) - Technical deep-dive
[API Reference](documentations/API_REFERENCE.MD) - Complete API documentation

Contributing

Contributions are welcome. This alpha release provides a foundation for further development.

Ways to contribute:

Report bugs and issues
Suggest new features
Improve documentation
Test in different environments
Submit pull requests

What's Next?

Planned for Beta Release:

Performance optimizations and benchmarks
Additional flush handler implementations
Enhanced error handling and recovery
Spring Boot auto-configuration
Metrics and monitoring integration
Comprehensive test coverage improvements

Feedback Needed:

API ergonomics and developer experience
Performance characteristics in various environments
Integration patterns with popular frameworks
Documentation clarity and completeness

Feedback & Support

GitHub Issues: Report bugs or request features
Discussions: Share ideas and ask questions
Documentation: Help improve guides and examples

Acknowledgments

Thanks to early contributors and testers who helped make this alpha release possible.

Get Started

Try VFL Client Java Framework v0.1.0 Alpha:

git clone https://github.com/vfl/java-client
cd java-client  
# Follow the Quick Start guide in README.md

Releases: kuchuk-borom-debbarma/Visual-Flow-Logger-Framework-JAVA

0.1.1-alpha

Uh oh!

0.1.0 ALPHA