DEV Community: Said Olano

Distributed Tracing with OpenTelemetry: Observability for Modern Microservices

Said Olano — Tue, 15 Sep 2026 01:38:36 +0000

Introduction: The Observability Crisis in Microservices

A request enters your system. It touches five microservices. One service is slow. Which one? Why? How long does the bottleneck add to the end-to-end latency?

In monolithic applications, you could trace a single execution flow. In distributed systems with hundreds of services communicating asynchronously, that simple trace becomes impossible without proper instrumentation.

Observability is the answer—the ability to understand system behavior based on its external outputs. And OpenTelemetry is the modern, vendor-neutral standard for implementing it across your entire stack.

This article explores distributed tracing, OpenTelemetry's architecture, practical implementation patterns, and how to transform chaotic microservices logs into actionable insights.

The Problem: Why Traditional Logging Fails in Distributed Systems

Lack of Request Context

Traditional logging captures events on a single machine:

logger.info("Processing order: " + orderId);
logger.info("Fetching user from database");
logger.info("Order processed successfully");

In a monolith, these logs are sequential, readable, and correlated. In microservices:

Order service logs: "Processing order: 12345"
User service receives same request → logs separately
Payment service logs independently
These logs are scattered across different servers, files, and logging systems

Problem: You have no way to connect these logs into a single request flow.

The Gap Between Logs, Metrics, and Traces

Traditional monitoring focuses on three separate pillars:

Logs - Event records (text messages)
Metrics - Aggregated counters (response time, CPU usage)
Traces - Request flows (distributed context)

But they don't talk to each other:

Your metrics show elevated latency
Your logs are millions of lines
You can't connect the metric spike to the exact request that caused it

Scale and Cost

APM (Application Performance Monitoring) solutions like Datadog and New Relic are powerful but expensive—often charging per event or trace. At scale (billions of requests/day), these costs become prohibitive.

OpenTelemetry: A Unified Standard for Observability

What is OpenTelemetry?

OpenTelemetry (OTel) is a vendor-neutral, open-source standard for collecting, processing, and exporting telemetry data (traces, metrics, logs). Key characteristics:

Standardized API: Single instrumentation layer across all languages
Vendor-neutral: Export to Jaeger, Prometheus, Datadog, AWS X-Ray, etc.
Language support: Java, Python, Go, JavaScript, .NET, and more
Zero-breaking changes: Built by the observability community (CNCF)
Production-ready: Used at scale by Uber, Netflix, Google, Amazon

Architecture: Signals, Instrumentation, and Exporters

Your Application
    ↓
    ├─ Traces (distributed request paths)
    ├─ Metrics (counters, gauges, histograms)
    └─ Logs (structured events)
    ↓
OpenTelemetry SDK
    ├─ Instrumentation (automatic + manual)
    ├─ Processors (sampling, batching, filtering)
    └─ Exporters (OTLP, Jaeger, Prometheus, etc.)
    ↓
Backend (Jaeger, Tempo, Prometheus, etc.)

Practical Implementation: Setting Up OpenTelemetry in Java

Step 1: Add Dependencies

For Spring Boot 3.x with Maven:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- OpenTelemetry Spring Boot Starter -->
    <dependency>
        <groupId>io.opentelemetry.instrumentation</groupId>
        <artifactId>opentelemetry-spring-boot-starter</artifactId>
    </dependency>

    <!-- OTLP Exporter (exports to Jaeger, Tempo, etc.) -->
    <dependency>
        <groupId>io.opentelemetry.exporter</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

Step 2: Configure Application Properties

# application.yml
spring:
  application:
    name: order-service

management:
  otlp:
    tracing:
      endpoint: http://localhost:4317  # Jaeger OTLP receiver
  tracing:
    sampling:
      probability: 1.0  # 100% sampling (adjust for production)

Step 3: Automatic Instrumentation (Zero Code Changes)

Spring Boot automatically instruments:

✅ HTTP requests (incoming and outgoing)
✅ Database queries (JDBC, JPA)
✅ Message queues (Kafka, RabbitMQ)
✅ Caching (Redis, Caffeine)
✅ HTTP clients (RestTemplate, WebClient)

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @PostMapping
    public ResponseEntity<Order> createOrder(@RequestBody OrderRequest request) {
        // Automatic tracing:
        // - Incoming HTTP request is traced
        // - Span created with trace_id, span_id
        // - All downstream calls inherit this trace_id
        Order order = orderService.processOrder(request);
        return ResponseEntity.ok(order);
    }
}

@Service
public class OrderService {

    @Autowired
    private UserServiceClient userClient;

    @Autowired
    private PaymentServiceClient paymentClient;

    public Order processOrder(OrderRequest request) {
        // Automatic tracing for HTTP calls:
        User user = userClient.getUser(request.getUserId());

        // Automatic tracing for database calls:
        Order order = orderRepository.save(buildOrder(user, request));

        // Automatic tracing for outgoing HTTP:
        PaymentResponse payment = paymentClient.processPayment(order);

        return order;
    }
}

Result: Every request automatically traced with correlation IDs, timing, and dependencies—zero custom code.

Step 4: Custom Spans (When You Need More Granularity)

For business logic not covered by automatic instrumentation:

@Service
public class OrderService {

    @Autowired
    private Tracer tracer;

    public Order processOrder(OrderRequest request) {
        // Automatic spans for HTTP calls
        User user = userClient.getUser(request.getUserId());

        // Create custom span for business logic
        Span validationSpan = tracer.spanBuilder("validate-order")
            .startSpan();

        try (Scope scope = validationSpan.makeCurrent()) {
            validationSpan.addEvent("Validating inventory");
            validateInventory(request.getItems());
            validationSpan.addEvent("Inventory validated");

            // Add attributes for later filtering
            validationSpan.setAttribute("order.item_count", request.getItems().size());
            validationSpan.setAttribute("order.total", calculateTotal(request));
        } finally {
            validationSpan.end();
        }

        return orderRepository.save(buildOrder(user, request));
    }
}

Step 5: Deploy Jaeger for Local Development

Using Docker Compose:

version: '3.8'
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP receiver

Start with: docker-compose up

Access Jaeger UI: http://localhost:16686

Real-World Patterns: Debugging Production Issues

Pattern 1: Finding Slow Requests

Scenario: P99 latency is 5 seconds, but P50 is 200ms. Something occasionally breaks.

Without distributed tracing: Check application logs across 20 services, look for timestamps, hope they're synchronized.

With OpenTelemetry:

Open Jaeger UI → Search for traces with latency > 5s
Click on a slow trace
See exact timeline: User Service (100ms) → Order Service (2000ms) → Payment Service (2800ms)
Payment Service has the bottleneck
Click Payment Service span → See all database queries
Identify slow query, fix database index

Time to resolution: 5 minutes (vs. 1-2 hours debugging)

Pattern 2: Debugging Distributed Failures

Scenario: Payment processing randomly fails, but no error logged.

Without tracing: Applications don't crash, no stack trace, mystery failure.

With OpenTelemetry:

Filter for traces with "error" status
Payment Service spans show HTTP 503 from external gateway
Inspect span attributes: http.status_code = 503, http.url = api.payment.com
External service was down, retry logic should kick in
Fix: Enable exponential backoff in HTTP client configuration

Pattern 3: Understanding Service Dependencies

Scenario: Order Service is slow. Is it our code, or downstream dependencies?

Without tracing: Deploy with more threads, hope it helps.

With tracing:

Open Jaeger → Service dependency graph
See Order Service → User Service, Inventory Service, Payment Service
Click trace → Breakdown:
- Order Service code: 50ms
- User Service: 300ms (slow database query)
- Inventory Service: 800ms (timeout on external API)
- Payment Service: 1500ms (gateway latency)
Optimize User Service query, add caching for Inventory API
Total latency: 2650ms → 450ms (5.8x improvement)

Performance Tuning and Sampling

Sampling Strategies

At high volume (1M requests/day), tracing everything is expensive:

management:
  tracing:
    sampling:
      probability: 0.1  # Trace 10% of requests (100k/day)

But sampling has a problem: You might miss rare errors or slow requests.

Solution: Intelligent sampling:

@Configuration
public class TracingConfig {

    @Bean
    public Sampler customSampler() {
        // Trace 100% of errors, 10% of successful requests
        return new Sampler() {
            @Override
            public SamplingResult shouldSample(
                Context parentContext,
                String traceId,
                String name,
                SpanKind spanKind,
                Attributes attributes,
                List<LinkData> parentLinks) {

                // Check for error signals
                if (name.contains("error") || attributes.get("http.status_code") >= 400) {
                    return SamplingResult.recordAndSample();
                }

                // Default: 10% sampling
                return Math.random() < 0.1 
                    ? SamplingResult.recordAndSample() 
                    : SamplingResult.drop();
            }
        };
    }
}

Exporting to Production Backends

Option 1: Jaeger (Self-Hosted)

management:
  otlp:
    tracing:
      endpoint: http://jaeger-collector.monitoring:4317

Pros: Open source, full control, low cost

Cons: Operational overhead

Option 2: Grafana Tempo (Cloud/Self-Hosted)

management:
  otlp:
    tracing:
      endpoint: https://tempo-distributor.grafana-cloud.com/v1/traces
      headers:
        Authorization: Bearer $GRAFANA_API_TOKEN

Pros: Serverless option, integrates with Grafana dashboards

Cons: Requires Grafana account

Option 3: Datadog

management:
  otlp:
    tracing:
      endpoint: https://opentelemetry-collector-http.us5.datadoghq.com/v1/traces
      headers:
        DD-API-KEY: $DATADOG_API_KEY

Pros: Managed service, excellent UI

Cons: Expensive at scale

Best Practices and Gotchas

✅ DO THIS

Correlate logs with traces: Include trace_id in all logs

@Bean
public LoggingEventListener loggingEventListener() {
    return event -> {
        String traceId = Tracer.current().getSpanContext().getTraceId();
        MDC.put("trace_id", traceId);  // Log Mapped Diagnostic Context
    };
}

Add business context to spans:

span.setAttribute("user.id", user.getId());
span.setAttribute("order.amount", order.getTotal());

Use semantic attribute conventions: Follow OpenTelemetry spec for standardized attributes

span.setAttribute("http.method", "POST");
span.setAttribute("http.url", "/api/orders");
span.setAttribute("http.status_code", 201);

❌ AVOID

Tracing everything at high volume: Use intelligent sampling
Storing PII in traces: Sanitize sensitive data
Ignoring trace context propagation: Ensure trace_id flows through all services

The Future: OpenTelemetry Roadmap

Profiling integration: Link traces directly to CPU profiles
Logs-first observability: Full logs support in OpenTelemetry
Metrics to Traces correlation: Click metric spike → see causing trace
GraphQL instrumentation: Better support for GraphQL APIs
Serverless optimization: Cost-effective tracing for Lambda/Cloud Functions

Conclusion: From Chaos to Clarity

Microservices create complexity. Observability tames it. OpenTelemetry is the modern standard that brings sanity to distributed debugging:

✅ See request flows across your entire system

✅ Identify bottlenecks in milliseconds, not hours

✅ Correlate logs, metrics, and traces in one view

✅ Avoid vendor lock-in with open standards

✅ Scale cost-effectively with intelligent sampling

If you're running microservices without distributed tracing, you're flying blind. OpenTelemetry removes that blindfold.

Start small: Deploy Jaeger locally, add the Spring Boot starter, and watch your observability problems disappear.

Resources

Tags: #Java #Observability #Microservices #Distributed-Tracing #OpenTelemetry #DevOps #Monitoring

Virtual Threads in Java 21: Revolutionizing Concurrency and Scalability

Said Olano — Tue, 15 Sep 2026 01:27:44 +0000

Introduction: The Future of Concurrent Programming in Java

For decades, Java developers have relied on OS-level threads to handle concurrent workloads. The traditional threading model—one thread per task—has served the ecosystem well, but it comes with fundamental limitations. Each thread consumes significant memory (typically 1-2 MB), limiting the number of concurrent tasks to thousands rather than millions. Modern cloud applications, microservices, and real-time systems demand millions of concurrent connections and operations.

Enter Virtual Threads (also called fibers or green threads)—a revolutionary feature introduced in Java 21 that fundamentally changes how we think about concurrency in Java. Virtual Threads are lightweight, managed by the JVM, and allow developers to write simple, sequential code while the runtime handles millions of concurrent tasks efficiently. This article explores the mechanics of Virtual Threads, their impact on application architecture, and practical patterns for leveraging them in production systems.

The Problem with Traditional Threads

Memory Overhead

Each OS-level thread consumes approximately 1-2 MB of memory. A server with 8 GB of RAM can theoretically run only 4,000-8,000 threads before running out of memory. For applications requiring millions of concurrent connections—think IoT platforms, real-time analytics, or high-frequency trading systems—this becomes a critical bottleneck.

// Traditional Thread Approach - Limited Scalability
public class TraditionalThreadServer {
    public static void main(String[] args) {
        ExecutorService executor = Executors.newCachedThreadPool();

        for (int i = 0; i < 1_000_000; i++) {
            executor.submit(() -> {
                handleClientConnection();
            });
        }
    }

    private static void handleClientConnection() {
        // This will create up to 1 million OS threads
        // Each consuming ~1-2 MB of memory
        // Total: ~1-2 GB just for thread overhead!
    }
}

Context Switching Cost

Operating systems manage thread scheduling by context switching between active threads. With millions of threads, the context switching overhead becomes substantial, reducing overall throughput and increasing latency unpredictably.

Programming Complexity

Traditional concurrency in Java often relies on asynchronous programming patterns (callbacks, Futures, reactive streams), which complicate code readability and error handling:

// Asynchronous Complexity
userService.getUserAsync(userId)
    .thenCompose(user -> orderService.getOrdersAsync(user.getId()))
    .thenCompose(orders -> inventoryService.checkStockAsync(orders))
    .thenApply(stock -> buildResponse(stock))
    .exceptionally(ex -> handleError(ex))
    .whenComplete((result, ex) -> logResult(result, ex));

Virtual Threads: A Paradigm Shift

What Are Virtual Threads?

Virtual Threads are lightweight, managed concurrency units that run on top of OS-level threads through the Structured Concurrency and Project Loom initiatives. Key characteristics:

Lightweight: Each Virtual Thread requires only ~1 KB of memory (1,000x more efficient than OS threads)
Abundant: Your application can create millions of Virtual Threads
Simple: Write sequential code—the JVM handles scheduling
Non-blocking: When a Virtual Thread encounters blocking I/O, it yields to another Virtual Thread automatically

The Virtual Thread Execution Model

Virtual Threads are managed by a Scheduler that maps them onto a pool of Carrier Threads (OS-level threads). When a Virtual Thread performs a blocking operation:

The Virtual Thread is suspended
The Carrier Thread becomes available for other Virtual Threads
When the blocking operation completes, the Virtual Thread resumes (potentially on a different Carrier Thread)

This happens transparently to your code—you write simple, sequential logic while the JVM manages millions of concurrent tasks.

Virtual Threads (millions)
    ↓
Scheduler (JVM)
    ↓
Carrier Threads (small pool, ~CPU count)
    ↓
OS Kernel

Practical Implementation: From Threads to Virtual Threads

Before: Traditional Thread Pool

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @PostMapping
    public ResponseEntity<Order> createOrder(@RequestBody OrderRequest request) {
        // Executes on traditional thread pool
        return ResponseEntity.ok(orderService.processOrder(request));
    }
}

@Service
public class OrderService {

    @Autowired
    private UserRepository userRepository;

    @Autowired
    private InventoryService inventoryService;

    public Order processOrder(OrderRequest request) {
        // Blocking I/O: waits for database response
        User user = userRepository.findById(request.getUserId()).orElseThrow();

        // Blocking I/O: waits for HTTP call to inventory service
        InventoryStatus inventory = inventoryService.checkStock(request.getItems());

        // Process order...
        return buildOrder(user, inventory, request);
    }
}

With traditional threads, this simple code requires careful thread pool configuration. Too few threads = throughput bottleneck. Too many threads = memory exhaustion.

After: Virtual Threads (Java 21+)

The code remains identical, but now:

// application.properties
spring.threads.virtual.enabled=true

// Same controller and service code - no changes needed!

Spring Boot automatically uses Virtual Threads for request handling. Millions of concurrent orders can now be processed with minimal resource overhead.

Creating Virtual Threads Explicitly

public class VirtualThreadExample {

    public static void main(String[] args) throws InterruptedException {
        // Create a Virtual Thread using Thread.ofVirtual()
        Thread virtualThread = Thread.ofVirtual()
            .name("worker-", 0)
            .start(() -> {
                System.out.println("Running on Virtual Thread: " + 
                    Thread.currentThread().getName());
                fetchDataAndProcess();
            });

        virtualThread.join();
    }

    private static void fetchDataAndProcess() {
        // Blocking I/O is fine - Virtual Thread will be suspended
        // and the Carrier Thread will handle other Virtual Threads
        String data = fetchFromDatabase(); // Blocking
        String enriched = callExternalAPI(data); // Blocking
        processAndStore(enriched); // Blocking
    }
}

ExecutorService with Virtual Threads

public class VirtualThreadExecutor {

    public static void main(String[] args) throws Exception {
        // Create an executor backed by Virtual Threads
        ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

        // Submit millions of tasks without worrying about thread exhaustion
        for (int i = 0; i < 10_000_000; i++) {
            final int taskId = i;
            executor.submit(() -> {
                processTask(taskId);
            });
        }

        executor.shutdown();
        executor.awaitTermination(1, TimeUnit.HOURS);
    }

    private static void processTask(int id) {
        // Sequential, blocking code
        String result = fetchDataFromAPI(id);
        storeInDatabase(result);
        notifySubscribers(result);
    }
}

Real-World Patterns and Best Practices

Pattern 1: Web Service Concurrency

@RestController
@RequestMapping("/api/analytics")
public class AnalyticsController {

    @Autowired
    private DataService dataService;

    @GetMapping("/report/{id}")
    public ResponseEntity<Report> generateReport(@PathVariable String id) {
        // With Virtual Threads, one thread per request is feasible
        // even with millions of concurrent users

        Report report = dataService.generateComplexReport(id);
        return ResponseEntity.ok(report);
    }
}

@Service
public class DataService {

    @Autowired
    private DatabaseClient dbClient;

    @Autowired
    private ExternalAnalyticsService analyticsService;

    public Report generateComplexReport(String id) {
        // Multiple blocking I/O operations
        var userData = dbClient.fetchUsers(id);
        var transactions = dbClient.fetchTransactions(id);
        var externalMetrics = analyticsService.getMetrics(id);

        return assembleReport(userData, transactions, externalMetrics);
    }
}

Pattern 2: Batch Processing at Scale

public class BatchProcessor {

    public void processMillionRecords(List<Record> records) 
            throws InterruptedException {

        ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

        for (Record record : records) {
            executor.submit(() -> {
                // Each record gets its own Virtual Thread
                validateRecord(record);
                enrichFromExternalSources(record);
                persistToDataWarehouse(record);
                publishToKafka(record);
            });
        }

        executor.shutdown();
        executor.awaitTermination(1, TimeUnit.DAYS);
    }
}

Pattern 3: Structured Concurrency (Java 19+)

public class StructuredConcurrencyExample {

    public Order processOrderWithRetry(OrderRequest request) 
            throws Exception {

        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {

            // Submit related tasks
            var userFuture = scope.fork(() -> fetchUser(request.getUserId()));
            var inventoryFuture = scope.fork(() -> checkInventory(request.getItems()));
            var pricingFuture = scope.fork(() -> calculatePricing(request.getItems()));

            // Wait for all to complete
            scope.joinUntil(Instant.now().plusSeconds(5));

            if (scope.exception() != null) {
                throw scope.exception();
            }

            return buildOrder(
                userFuture.resultNow(),
                inventoryFuture.resultNow(),
                pricingFuture.resultNow()
            );
        }
    }
}

Performance Benchmarks and Real-World Impact

Memory Efficiency

Metric	OS Threads	Virtual Threads
Memory per thread	1-2 MB	~1 KB
Max concurrent on 8GB	~4,000	~8,000,000
Thread creation cost	High (~ms)	Low (~μs)
Context switch overhead	Significant	Minimal

Throughput Improvement

A benchmark comparing traditional vs Virtual Thread handling of I/O-bound workloads:

Traditional Thread Pool (200 threads):
- Requests/sec: ~2,000
- Latency (p99): 500ms
- Memory: ~400 MB

Virtual Threads:
- Requests/sec: ~50,000 (25x improvement)
- Latency (p99): 50ms
- Memory: ~50 MB (8x reduction)

Real production deployments (e.g., Uber, Netflix) have reported:

40-60% reduction in resource consumption
2-5x improvement in request throughput
Simplified code (no async/await complexity)

Migration Path: Gradual Adoption

Virtual Threads don't require a complete rewrite. Java 21 allows gradual adoption:

Step 1: Enable Virtual Threads in Spring Boot

# application.yml
spring:
  threads:
    virtual:
      enabled: true

Step 2: Update Thread Pool Configuration

@Configuration
public class ThreadPoolConfig {

    @Bean
    public ExecutorService virtualThreadExecutor() {
        // Old way: Executors.newFixedThreadPool(200)
        // New way: Virtual Threads (no limit needed)
        return Executors.newVirtualThreadPerTaskExecutor();
    }
}

Step 3: Remove Reactive Code Where Unnecessary

Virtual Threads make complex reactive code optional:

// Before: Reactive complexity
userService.getUserAsync(id)
    .flatMap(user -> orderService.getOrdersAsync(user.id))
    .subscribe(orders -> process(orders));

// After: Simple sequential code with Virtual Threads
User user = userService.getUser(id);
List<Order> orders = orderService.getOrders(user.id);
process(orders);

Considerations and Limitations

When NOT to Use Virtual Threads

CPU-bound tasks: Virtual Threads excel at I/O-bound work. For CPU-bound operations, traditional thread pools may be more appropriate.
Thread-local state: Excessive thread-local usage can cause issues at scale. Refactor to pass context explicitly.

// Avoid excessive thread-local usage
// private static final ThreadLocal<User> currentUser = new ThreadLocal<>();

// Instead, use context objects
public void handleRequest(Request request, User user) {
    // Pass user explicitly
    processRequest(request, user);
}

Pinning: Certain operations (synchronized blocks, JNI calls) can "pin" a Virtual Thread to its Carrier Thread, blocking other Virtual Threads. Minimize synchronized blocks.

// Avoid
synchronized void criticalSection() {
    // Pins the Virtual Thread!
}

// Prefer
private final ReentrantLock lock = new ReentrantLock();

void criticalSection() {
    lock.lock();
    try {
        // Does not pin
    } finally {
        lock.unlock();
    }
}

The Roadmap: Beyond Java 21

Virtual Threads are here, but the ecosystem continues evolving:

Structured Concurrency (Preview in Java 19+): Better composability and error handling
Scoped Values (Preview): Thread-safe context propagation
Foreign Function & Memory API: Better interop with native code
Project Leyden: Faster startup and lower memory for containerized deployments

Conclusion: A New Era of Concurrency

Virtual Threads represent a fundamental shift in how Java handles concurrency. By abstracting thread management to the JVM layer, they enable:

✅ Scalability: Millions of concurrent tasks on modest hardware

✅ Simplicity: Write sequential, readable code without reactive complexity

✅ Efficiency: 1,000x memory reduction per concurrency unit

✅ Performance: 2-5x throughput improvement on I/O-bound workloads

If you're building cloud-native applications, microservices, or high-concurrency systems in Java, Virtual Threads aren't just an optimization—they're a paradigm shift that modernizes how you architect concurrent systems.

The future of Java concurrency is here. It's time to adopt it.

Resources

Tags: #Java #Concurrency #Performance #Architecture #Threading #Java21 #SpringBoot #HighScalability

Building Production-Ready AI Agents with Spring AI and LangChain: A Practical Guide

Said Olano — Mon, 14 Sep 2026 19:37:40 +0000

Building Production-Ready AI Agents with Spring AI and LangChain: A Practical Guide

Introduction

The convergence of large language models (LLMs) and microservices architecture presents unprecedented opportunities for building intelligent, autonomous systems. However, moving from a chatbot proof-of-concept to a production-grade AI agent requires deep understanding of resilience patterns, tool integration, memory management, and observability.

In this comprehensive guide, we'll explore how to architect and implement production-ready AI agents using Spring AI and LangChain within the Spring Boot ecosystem. Whether you're building customer service agents, autonomous data analysts, or intelligent document processors, the patterns and implementations we'll discuss form the foundation of enterprise-grade AI systems.

What We'll Cover

This guide spans the complete lifecycle of AI agent development:

Architecture foundations – Understanding the difference between chatbots, assistants, and autonomous agents
Spring AI integration – Leveraging Spring's abstraction layers for LLM interactions
Tool calling and function execution – Enabling agents to interact with external systems
Memory and context management – Implementing stateful agents that learn from interactions
Error handling and resilience – Building fault-tolerant systems that gracefully degrade
Observability and monitoring – Instrumenting agents for production visibility
Deployment patterns – Scaling AI agents in containerized environments

Part 1: Understanding AI Agents vs Chatbots

The Spectrum of AI Interaction

Before diving into implementation, let's clarify terminology that's often conflated in the industry:

Chatbots (Reactive):

Respond to user input only
No persistent state beyond the current conversation
Execute pre-defined workflows
Example: Customer support FAQ bots

Assistants (Semi-Autonomous):

Maintain conversation history
Can retrieve contextual information
Guided by prompts but follow scripted paths
Example: Personal productivity assistants (scheduling, email)

Agents (Fully Autonomous):

Make independent decisions about which actions to take
Dynamically select from available tools
Iterate through planning → execution → observation cycles
Handle novel situations outside their training
Example: Customer issue resolution agents that can refund orders, escalate to specialists, or adjust billing

Why This Matters for Architecture

The distinction isn't purely semantic—it fundamentally changes how you architect these systems:

Aspect	Chatbot	Assistant	Agent
Decision Logic	Hardcoded rules	Prompt-guided	LLM-driven reasoning
Tool Selection	Fixed pipeline	Limited choices	Dynamic from toolset
State Management	Stateless or simple cache	Session storage	Complex memory structures
Error Recovery	Predefined escalation	Retry logic	Self-correction loops
Latency SLA	<500ms	<2s	<10s (with retries)
Observability	Simple logging	Structured traces	Full reasoning chains

Most business use cases actually require agent-level capabilities for production value, but the added complexity justifies careful architectural consideration.

Part 2: Spring AI Architecture and Core Concepts

The Spring AI Abstraction Model

Spring AI provides a vendor-agnostic abstraction layer over LLM providers. This separation of concerns mirrors Spring's philosophy across data access, messaging, and cloud services:

┌─────────────────────────────────────────────────────┐
│         Application Layer (Your Code)                │
├─────────────────────────────────────────────────────┤
│  ChatClient / AiClient (Spring AI Abstractions)    │
├─────────────────────────────────────────────────────┤
│  Provider-Specific Implementations                  │
│  (OpenAI, Anthropic, Ollama, etc.)                  │
├─────────────────────────────────────────────────────┤
│  LLM Provider APIs (REST/gRPC)                      │
└─────────────────────────────────────────────────────┘

Key Spring AI Components

ChatClient:
The primary interface for interacting with LLMs. It handles prompt construction, tool binding, and response parsing.

@Service
public class CustomerSupportAgent {

    private final ChatClient chatClient;

    @Autowired
    public CustomerSupportAgent(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
            .defaultOptions(options())
            .defaultFunctions("tools")
            .build();
    }

    public String resolveCustomerIssue(String customerMessage) {
        return chatClient.prompt()
            .user(customerMessage)
            .functions("getOrderHistory", "processRefund", "createTicket")
            .call()
            .content();
    }

    private ChatClientRequestOptions options() {
        return ChatClientRequestOptions.builder()
            .withTemperature(0.3)
            .withTopP(0.9)
            .build();
    }
}

ToolContext:
Registers the actual Java methods that become available to the LLM as callable tools.

@Service
public class CustomerServiceTools {

    @Tool(description = "Retrieve customer order history")
    public List<Order> getOrderHistory(
        @ToolParam(description = "Customer ID") String customerId) {
        // Query your order database
        return orderService.findByCustomerId(customerId);
    }

    @Tool(description = "Process a refund for an order")
    public RefundResult processRefund(
        @ToolParam(description = "Order ID") String orderId,
        @ToolParam(description = "Refund reason") String reason) {
        // Execute refund logic
        return orderService.refund(orderId, reason);
    }

    @Tool(description = "Create a support ticket for escalation")
    public Ticket createTicket(
        @ToolParam(description = "Customer ID") String customerId,
        @ToolParam(description = "Issue description") String description) {
        // Create ticket in your support system
        return ticketService.create(customerId, description);
    }
}

Integration with LangChain

LangChain provides the orchestration layer that Spring AI abstracts. When you need advanced patterns (complex chains, recursive reasoning, memory strategies), you can integrate LangChain components:

@Service
public class AdvancedReasoningAgent {

    private final ChatModel chatModel;
    private final ToolProvider toolProvider;

    public String executeComplexTask(String query) {
        // Build a ReAct-style loop
        var tools = toolProvider.getAvailableTools();
        var toolDescriptions = formatToolsForPrompt(tools);

        var systemPrompt = """
            You are an expert problem solver. When faced with a complex task:
            1. Break it into sub-goals
            2. Select appropriate tools for each sub-goal
            3. Execute tools and observe results
            4. Adapt your approach based on observations
            5. Report your final solution

            Available tools:
            %s
            """.formatted(toolDescriptions);

        var messages = List.of(
            new SystemMessage(systemPrompt),
            new UserMessage(query)
        );

        return executionLoop(messages, tools);
    }
}

Part 3: Implementing Tool Calling and Function Execution

Tool Definition Strategy

Effective tool design is critical to agent success. Tools that are poorly specified lead to:

Incorrect tool selection by the LLM
Failed executions due to misunderstood parameters
Cascading errors in multi-step workflows

Rule 1: Specificity
Each tool should have a single, well-defined responsibility:

// ❌ TOO BROAD
@Tool(description = "Manage order")
public OrderResult manageOrder(String action, String orderId, Map<String, Object> params) {
    // This tool does too much!
}

// ✅ FOCUSED
@Tool(description = "Retrieve the complete order details including items, pricing, and shipping status")
public OrderDetails getOrderDetails(
    @ToolParam(description = "The unique order ID (format: ORD-XXXXXX)") String orderId) {
    return orderService.getOrderById(orderId);
}

@Tool(description = "Cancel an order and initiate a refund. Only works for orders in PENDING or CONFIRMED status.")
public CancelResult cancelOrder(
    @ToolParam(description = "The order ID to cancel") String orderId,
    @ToolParam(description = "Reason for cancellation") String reason) {
    return orderService.cancel(orderId, reason);
}

Rule 2: Clear Parameter Contracts
Include validation and type information inline:

@Tool(description = "Process a payment for an invoice")
public PaymentResult processPayment(
    @ToolParam(description = "Invoice ID (format: INV-YYMM-XXXXX)", 
               defaultValue = "") String invoiceId,
    @ToolParam(description = "Payment amount in USD, must be >= 0.01", 
               defaultValue = "0") BigDecimal amount,
    @ToolParam(description = "Payment method: CREDIT_CARD, BANK_TRANSFER, ACH", 
               defaultValue = "CREDIT_CARD") String method) {

    validateInvoiceId(invoiceId);
    validateAmount(amount);
    validatePaymentMethod(method);

    return paymentService.process(invoiceId, amount, method);
}

Rule 3: Atomic Operations
Tools should be atomic—they succeed or fail completely without partial states:

// ❌ RISKY: Multiple database operations, failure mid-way leaves inconsistent state
@Tool
public void updateCustomerAndCreateTicket(String customerId, Map<String, Object> updates) {
    customerService.update(customerId, updates);
    ticketService.create(customerId, "Auto-update initiated");
}

// ✅ SAFE: Single responsibility, transaction boundary clear
@Transactional
@Tool
public void updateCustomerStatus(
    @ToolParam String customerId,
    @ToolParam String newStatus) {
    Customer customer = customerService.getById(customerId);
    customer.setStatus(newStatus);
    customerService.save(customer);
}

Tool Execution Error Handling

The agent needs to understand why a tool failed to make intelligent recovery decisions:

@Service
public class ResilientToolExecution {

    @Tool(description = "Transfer funds between accounts")
    public TransferResult transferFunds(
        @ToolParam String fromAccount,
        @ToolParam String toAccount,
        @ToolParam BigDecimal amount) {

        try {
            return accountService.transfer(fromAccount, toAccount, amount);
        } catch (InsufficientFundsException e) {
            // Provide specific error that agent can reason about
            throw new ToolExecutionException(
                "Transfer failed: insufficient funds. Current balance is: " + 
                accountService.getBalance(fromAccount),
                "INSUFFICIENT_FUNDS",
                Map.of("requiredAmount", amount, 
                       "availableBalance", accountService.getBalance(fromAccount)),
                e
            );
        } catch (AccountLockedException e) {
            throw new ToolExecutionException(
                "Cannot transfer: account is locked. Contact support at support@company.com",
                "ACCOUNT_LOCKED",
                Map.of("lockedUntil", e.getLockExpirationTime()),
                e
            );
        }
    }
}

Part 4: Memory and Conversation State Management

Conversation Context vs. Long-Term Memory

Production agents need to distinguish between:

Conversation context (short-term): Current interaction details
Long-term memory (persistent): Historical patterns, preferences, learned facts

@Service
public class StatefulAgent {

    private final ChatClient chatClient;
    private final ConversationStore conversationStore;
    private final MemoryService memoryService;

    public String processUserMessage(String userId, String message) {
        // Load conversation context
        var conversation = conversationStore.getConversation(userId);

        // Load relevant long-term memory
        var relevantMemory = memoryService.getRelevantMemory(userId, message);

        // Build prompt with both contexts
        var systemPrompt = buildSystemPrompt(conversation, relevantMemory);

        var response = chatClient.prompt()
            .system(systemPrompt)
            .user(message)
            .call()
            .content();

        // Update conversation context
        conversation.addExchange(message, response);
        conversationStore.save(conversation);

        // Learn from this interaction
        memoryService.learn(userId, message, response);

        return response;
    }

    private String buildSystemPrompt(Conversation context, List<MemoryItem> memory) {
        return """
            You are an intelligent agent.

            Recent conversation:
            %s

            Known facts about this user:
            %s

            Use this context to provide personalized, coherent responses.
            """.formatted(formatConversation(context), formatMemory(memory));
    }
}

Vector Databases for Semantic Memory

For agents working with large document sets, semantic search enables intelligent retrieval:

@Service
public class SemanticMemoryAgent {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public String answerDocumentQuestion(String question) {
        // Find semantically similar document chunks
        var results = vectorStore.search(question, 5);

        var context = results.stream()
            .map(doc -> doc.getContent())
            .collect(joining("\n\n"));

        var systemPrompt = """
            Use the following documents to answer the question.
            If the documents don't contain relevant information, say so.

            Documents:
            %s
            """.formatted(context);

        return chatClient.prompt()
            .system(systemPrompt)
            .user(question)
            .call()
            .content();
    }
}

Part 5: Error Handling and Resilience Patterns

Circuit Breaker for Tool Invocations

External tools (APIs, databases, services) can fail. Protect your agent:

@Service
public class ResilientAgent {

    private final CircuitBreaker circuitBreaker;
    private final ChatClient chatClient;

    @Bean
    public CircuitBreaker toolCircuitBreaker() {
        return CircuitBreaker.of("toolExecution",
            CircuitBreakerConfig.custom()
                .failureThreshold(5)
                .waitDurationInOpenState(Duration.ofSeconds(30))
                .recordExceptions(ToolException.class)
                .ignoreExceptions(ToolValidationException.class)
                .build());
    }

    public String executeAgentWithFallback(String userQuery) {
        try {
            return Resilience4j.executeSupplier(circuitBreaker, () ->
                chatClient.prompt()
                    .user(userQuery)
                    .call()
                    .content()
            );
        } catch (CallNotPermittedException e) {
            // Circuit open: use degraded mode
            return "I'm experiencing temporary issues. Can you try again in a moment?";
        }
    }
}

Retry Strategy with Exponential Backoff

@Service
public class RetryableAgent {

    private final Retry retry;
    private final ChatClient chatClient;

    @Bean
    public Retry agentRetry() {
        return Retry.of("agent",
            RetryConfig.custom()
                .maxAttempts(3)
                .intervalFunction(IntervalFunction.ofExponentialBackoff(
                    1000, // initial interval ms
                    2,    // multiplier
                    1000  // max interval ms
                ))
                .recordExceptions(TemporaryFailureException.class)
                .build());
    }

    public String executeWithRetry(String query) {
        return Resilience4j.executeSupplier(retry, () ->
            chatClient.prompt()
                .user(query)
                .call()
                .content()
        );
    }
}

Part 6: Observability and Monitoring

Structured Logging for Agent Decisions

@Service
public class ObservableAgent {

    private static final Logger logger = LoggerFactory.getLogger(ObservableAgent.class);
    private final ChatClient chatClient;

    public String resolveIssue(String userId, String issue) {
        var traceId = UUID.randomUUID().toString();

        logger.info("Agent invoked", Map.of(
            "traceId", traceId,
            "userId", userId,
            "issueCategory", categorizeIssue(issue)
        ));

        try {
            var response = chatClient.prompt()
                .user(issue)
                .call()
                .content();

            logger.info("Agent completed", Map.of(
                "traceId", traceId,
                "status", "SUCCESS",
                "responseLength", response.length()
            ));

            return response;
        } catch (Exception e) {
            logger.error("Agent failed", Map.of(
                "traceId", traceId,
                "error", e.getMessage(),
                "errorType", e.getClass().getSimpleName()
            ), e);

            throw new AgentException("Failed to resolve issue", e);
        }
    }
}

Tracing Tool Execution

@Aspect
@Component
public class ToolExecutionTracing {

    private final MeterRegistry meterRegistry;

    @Around("@annotation(com.example.Tool)")
    public Object traceToolExecution(ProceedingJoinPoint joinPoint) throws Throwable {
        var toolName = joinPoint.getSignature().getName();
        var startTime = System.nanoTime();

        try {
            var result = joinPoint.proceed();
            var duration = System.nanoTime() - startTime;

            meterRegistry.timer("agent.tool.execution", 
                "tool", toolName, 
                "status", "success")
                .record(duration, TimeUnit.NANOSECONDS);

            return result;
        } catch (Exception e) {
            var duration = System.nanoTime() - startTime;

            meterRegistry.counter("agent.tool.errors",
                "tool", toolName,
                "errorType", e.getClass().getSimpleName())
                .increment();

            throw e;
        }
    }
}

Part 7: Deployment and Scaling

Docker-Based Agent Deployment

FROM eclipse-temurin:21-jdk-alpine

WORKDIR /app

COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
COPY src src

RUN ./mvnw clean package -DskipTests -q

FROM eclipse-temurin:21-jre-alpine
RUN apk add --no-cache dumb-init

WORKDIR /app
COPY --from=0 /app/target/*.jar app.jar

# Use dumb-init to properly handle signals
ENTRYPOINT ["dumb-init", "--"]
CMD ["java", "-Xmx512m", "-Xms256m", "-XX:+UseG1GC", "-jar", "app.jar"]

Kubernetes Deployment with Horizontal Scaling

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-agent
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ai-agent
  template:
    metadata:
      labels:
        app: ai-agent
    spec:
      containers:
      - name: agent
        image: myregistry/ai-agent:latest
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
        livenessProbe:
          httpGet:
            path: /actuator/health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /actuator/health/readiness
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

Conclusion and Best Practices Roadmap

The Path to Production AI Agents

Building production-ready AI agents is not simply about integration—it's about thoughtful architecture that balances:

Autonomy vs. Control: Agents need freedom to make decisions, but within guardrails
Speed vs. Safety: Fast response times often conflict with thorough verification
Generalization vs. Reliability: Flexible agents are harder to test than narrow chatbots
Cost vs. Quality: Larger models give better reasoning but higher inference costs

Recommended Implementation Sequence

Phase 1: Start with a single, well-defined use case (e.g., order cancellation)
Phase 2: Add conversation memory and context management
Phase 3: Introduce multiple, carefully specified tools
Phase 4: Implement observability and monitoring
Phase 5: Add resilience patterns (circuit breakers, retries)
Phase 6: Expand to multiple use cases and deploy at scale

Key Takeaways

Use Spring AI abstractions to decouple from specific LLM providers
Design tools to be atomic, specific, and independently testable
Distinguish between conversation context and long-term memory
Implement observability from day one—agent behavior is complex
Protect your system with resilience patterns
Start small, measure carefully, scale gradually

The future of enterprise software involves AI agents seamlessly integrated into business processes. By following these patterns and maintaining discipline around quality and observability, your team can build systems that deliver genuine value while remaining maintainable and trustworthy.

About the Author: Building AI systems at scale for over 5 years. Specialized in Spring Boot microservices, LLM integration, and production resilience patterns.

Next Steps: Share your agent architecture challenges in the comments. What patterns have worked for you?

Invest in People as a Software Engineering Lead: Building High-Performing Teams Through Human-Centric Leadership

Said Olano — Mon, 14 Sep 2026 18:21:55 +0000

Invest in People as a Software Engineering Lead: Building High-Performing Teams Through Human-Centric Leadership

Introduction

After 20+ years in fintech and digital banking, I've learned one immutable truth: the best software is built by great teams, not individual geniuses. Yet many engineering leaders still prioritize infrastructure, processes, and metrics over the humans who create everything.

The paradox is simple: investing in people is the highest ROI decision you can make as a leader. Teams with strong connections, clear growth paths, and psychological safety ship faster, make better decisions, and stay longer. This isn't soft leadership—it's business fundamentals.

1. Understand Your Team's Individual Motivations

Everyone Is Different (Really)

One of the biggest mistakes I made early in my leadership career was assuming everyone was motivated by the same things. Spoiler: they're not.

Some engineers want:

Technical mastery: Deep expertise in their domain
Career progression: Clear path to senior/staff roles
Impact: Shipping features that reach millions
Autonomy: Freedom to make technical decisions
Stability: Predictable work, good WLB, no drama
Mentorship: Teaching and growing others
Compensation: Competitive salary and equity

The Investment: 1-on-1 Discovery

Spend your first month doing exploratory 1-on-1s:

Questions to Ask (Don't Interview—Converse)
1. "What drew you to engineering in the first place?"
2. "What are you really good at that you wish you did more of?"
3. "Where do you see yourself in 3 years? 5 years?"
4. "What would make your work here more fulfilling?"
5. "What's one thing you're struggling with that I can help with?"
6. "If you left here, what would you miss most?"

The goal isn't a data collection exercise. It's building genuine understanding of what makes each person tick. Document this (privately) and refer back to it quarterly.

2. Create Transparent Career Paths

The Problem: Career Ambiguity

Most engineers have no idea how they advance. Is it years of service? Technical skills? Leadership? Politics? When the path is unclear, people assume the worst and start looking elsewhere.

The Solution: Skill Matrix + Career Ladder

Create a transparent framework that shows:

Junior Engineer → Mid-level Engineer → Senior Engineer → Staff Engineer → Architect

For each level, define:
- Technical Skills (Java, Spring, AWS, system design)
- Business Impact (feature ownership, mentoring)
- Communication (documentation, presentations, design reviews)
- Leadership (influencing without authority, unblocking others)
- Reliability (on-call performance, incident response)

Make It Actionable

// Example: What does a Senior Engineer look like?

Public class SeniorEngineerExpectations {

    // Technical: Owns complex systems end-to-end
    - Designs and implements major features (2-3 month scope)
    - Makes database/architecture decisions
    - Mentors 2-3 junior/mid-level engineers
    - Technical decision making (ADRs, design reviews)

    // Impact: Influences across teams
    - Improves processes and tooling
    - Reduces on-call incidents by 30%+
    - Speaks at internal tech talks
    - Owns recruitment for their domain

    // Timeline: 3-5 years of experience typically
    // Next Level: Demonstrated leadership + system design mastery
}

3. Invest in Skill Development Strategically

The 70-20-10 Model (Revisited)

70% Learning: Challenging projects

Don't just assign tickets—assign growth opportunities
Rotate engineers through different systems
Increase complexity gradually
Pair them on hard problems

20% Learning: Peer mentorship

Code reviews (done right)
Pair programming sessions
Design review discussions
Slack-based knowledge sharing

10% Learning: Formal training

Courses (Coursera, Udemy)
Certifications (AWS, Kubernetes)
Conference attendance
Budget: $2-3k per engineer per year

The Investment Budget

Per Engineer Per Year:
- Conference attendance: $1,500 (travel + registration)
- Online courses/certifications: $1,000
- Books and learning materials: $500
- Training workshops: $1,000

Total: ~$4,000 per engineer

ROI: One retained senior engineer saves $150k+ in recruitment/onboarding.
Investing $4k to retain a $150k engineer = 3,600% ROI

4. Compensation and Recognition

Compensation Isn't Everything (But It Matters)

Pay competitively. Don't cheap out. If you can't afford market rate, you won't retain talent.

What to do:

Benchmark salaries annually (Levels.fyi, Blind, company reports)
Review equity annually (RSUs can become worthless)
Give raises—aim for 3-5% annually minimum
Transparent salary bands (reduces resentment)

What NOT to do:

Wait for annual reviews to increase comp
Promise equity that vests over 5 years
Use comp as punishment ("you made a mistake, no raise")
Ignore inflation

Non-Monetary Recognition

Sometimes the most powerful investment is just seeing people:

✅ Celebrate wins publicly
   "Sarah just reduced our API latency by 40%. That's shipping 10ms faster 
    for millions of users. Incredible work."

✅ Give them harder problems
   "I'm putting you on the auth refactor because you've earned it."

✅ Promote visibility
   "Present this at the all-hands—your work deserves the spotlight."

✅ Sponsor them for leadership
   "You're ready to lead. I'm nominating you for tech lead on Platform team."

✅ Defend them
   "That unreasonable deadline? Not happening. My team ships quality."

5. Psychological Safety = Performance

Why Psychological Safety Matters

Teams where people feel safe to:

Take risks without fear of punishment
Speak up in meetings without judgment
Admit mistakes and learn from them
Challenge ideas (including yours)

...Ship faster, catch bugs earlier, and retain talent better.

Building It

From the Top:

Admit your own mistakes publicly
Ask for help ("I'm stuck on this architecture decision, thoughts?")
Respond to bad news with curiosity, not blame
Protect people from unreasonable demands

In Practice:

Scenario: Engineer ships a bug in production

❌ Bad: "How did this get past code review? We need to do better."

✅ Good: "This is a learning opportunity for all of us. Let's do a 
blameless post-mortem and figure out how to prevent it next time. 
Thank you for reporting this quickly."

6. Mentorship: The Ultimate Investment

Be a Mentor (Even If You're Too Busy)

The best leaders I've worked with always had time for mentorship. Not because they had extra time—they didn't. But because they knew it was their job.

Structuring Mentorship

For Junior Engineers:

Weekly 1-on-1s (30 minutes)
Pair program on complex tasks
Review every PR in detail
Teach them "why" not just "what"

For Mid-Level Engineers:

Bi-weekly 1-on-1s (30 minutes)
Assign them a junior to mentor (learning by teaching)
Have them lead design reviews
Expose them to business decisions

For Senior Engineers:

Monthly 1-on-1s (focused on growth)
Prepare them for staff/principal roles
Have them own hiring and promotions
Involve them in strategy decisions

The Multiplier Effect

When you mentor someone and they become great, they mentor others. Your impact compounds:

Year 1: You mentor 2 engineers
Year 2: Those 2 mentor 4 others = 6 total impacted
Year 3: Those 4 mentor 8 others = 14 total impacted
Year 4: Those 8 mentor 16 others = 30 total impacted

One leader, exponential impact.

7. Retention Through Connection

The Hidden Cost of Turnover

When a mid-level engineer leaves:

Direct cost: $150k-200k (recruiting, onboarding)
Lost productivity: 3-6 months ramp time
Institutional knowledge: Gone
Team morale: Shaken

Total cost: ~$500k+

Retention Investments

Stay interviews (before someone leaves):

Quarterly conversation:
"How are you feeling about your role? 
What would make you want to stay and grow here?
What concerns do you have?"

Work-life balance:

No emails on weekends (lead by example)
Mandatory time off (seriously, enforce it)
Flexible hours (trust people)
Remote-first when possible

Growth opportunities:

Rotation programs (experience different domains)
Lead roles on big projects
Internal mobility (don't force people to stay in one spot)
Conference speaking opportunities

8. Measure What Matters

Vanity Metrics (Don't Use These)

❌ Hours worked per week
❌ Lines of code shipped
❌ Number of commits
❌ Meeting attendance

Real Metrics (Track These)

Team Health Indicators:
✅ Retention rate (target: 90%+ annually)
✅ Internal promotions (target: 1 per 5-10 people/year)
✅ Manager satisfaction scores (via survey)
✅ Time from hire to productivity (target: <3 months)
✅ On-call satisfaction (are people burned out?)
✅ Learning investments ($ per person spent)
✅ Mentorship relationships (% with active mentor/mentee)

Business Outcomes:
✅ Feature delivery timeline
✅ Production incident MTTR
✅ Code review quality
✅ System reliability (99.9%+)
✅ Customer satisfaction (CSAT scores)

9. The Compounding Effect of People Investment

Year 1: Foundation

Map individual motivations
Create career paths
Start mentoring programs
Cost: Time + $4k per person in training
Result: Team feels seen and has direction

Year 2: Growth

First promotions happen internally
Junior engineers become mid-level
Retention rate improves to 95%+
Cost: Training + mentorship time
Result: Expertise stays in house, team owns domain deeply

Year 3: Leadership Multiplication

Mentored engineers become mentors
Staff/principal level roles emerge
Culture becomes self-reinforcing
Cost: Same (but payoff is massive)
Result: Exponential team capability

10. The Leadership Paradox

Here's the thing: the more you invest in your people, the more likely they are to leave.

You train them, mentor them, help them grow... and then they get offers from FAANG or startups. That's success.

Your job isn't to keep them—it's to make them great. Some will stay. Some will move on. Both are wins.

The engineers who remember you fondly become your best advocates. They recommend others. They return years later as peers and partners. They become the leaders of the industry.

Conclusion

Investing in people isn't soft. It's not optional. It's the core job of a software engineering leader.

Your technical skills got you promoted. Your people skills determine if you succeed.

Remember:

🎯 Understand individual motivations (they're not all the same)
🎯 Create clear paths (transparency reduces anxiety)
🎯 Invest in skills strategically (70-20-10 model works)
🎯 Pay fairly (can't afford great people on a budget)
🎯 Build psychological safety (risk-taking = innovation)
🎯 Mentor relentlessly (it compounds)
🎯 Retain through connection (not just compensation)
🎯 Measure team health (not just output)
🎯 Play the long game (culture compounds)

The best leaders I know aren't remembered for systems they built—they're remembered for people they developed. Be that leader.

What's your approach to investing in your team? Have you seen a specific investment that paid off? Share in the comments—I'd love to hear your stories.

Software Engineering Best Practices as a Team Lead and Communicator

Said Olano — Mon, 14 Sep 2026 18:16:03 +0000

Software Engineering Best Practices as a Team Lead and Communicator

Introduction

Transitioning from individual contributor to team lead is one of the most rewarding yet challenging journeys in software engineering. Success in this role requires more than technical expertise—it demands exceptional communication, clear vision-setting, and the ability to create a culture where engineers thrive. After 20+ years in IT and fintech, I've learned that the best team leads are those who master the intersection of technical excellence and human-centric leadership.

1. Lead Through Clear Communication

The Foundation: Over-Communicate

As a team lead, you can never over-communicate. What seems obvious to you might be ambiguous to your team. The best practice is to establish multiple communication channels:

Synchronous Communication:

Daily standups (15 minutes max): Focus on blockers, not status updates
1-on-1s (bi-weekly): Individual growth, career development, feedback
Design reviews: Technical decisions made collectively

Asynchronous Communication:

Written documentation for decisions and context
Architecture Decision Records (ADRs) for major technical choices
Slack/Teams channels organized by topic, not by person

The RAS Principle: RACI Without the Chaos

Define roles clearly: Responsible, Accountable, Supporting, Consulted, Informed. This prevents confusion and ensures everyone knows their role in decision-making.

Example: Database Migration Decision
- Responsible: Database Engineer (execution)
- Accountable: You (Team Lead - final decision)
- Supporting: DevOps Engineer (infrastructure)
- Consulted: Architecture Lead (strategic impact)
- Informed: Entire team (awareness)

2. Technical Decision-Making as a Team Lead

Document Everything with ADRs

Architecture Decision Records aren't just for documentation—they're communication tools.

# ADR 001: Use Microservices Over Monolithic Architecture

## Context
Our monolith has grown to 2M+ lines of code. Team velocity is declining.

## Decision
Migrate to microservices with event-driven architecture using Spring Boot + Apache Kafka.

## Consequences
+ Improved scalability and team autonomy
+ Independent deployment pipelines
- Increased operational complexity
- Distributed tracing and debugging challenges

## Alternatives Considered
1. Modular monolith (rejected: insufficient isolation)
2. Serverless approach (rejected: cost at our scale)

Code Review Excellence

Code reviews aren't just quality gates—they're learning opportunities:

Review for impact: Ask "what problem does this solve?"
Mentor through questions: "Have you considered...?" instead of "You should..."
Establish clear standards: Create a CONTRIBUTING.md with your team
Lead by example: Review PRs thoroughly, even from junior engineers

3. Mentorship and Skill Development

Create Growth Paths

Your team's growth is your metric. Establish clear skill progression:

Junior Engineer → Mid-level → Senior → Tech Lead

Skill Areas:
- Technical Depth (language, frameworks, architecture)
- System Design (scalability, reliability)
- Communication (documentation, presentations)
- Leadership (mentoring, decision-making)

The 70-20-10 Learning Model

70%: Learning from challenging work assignments
20%: Learning from mentors and peers (pair programming, code reviews)
10%: Formal training (courses, certifications)

Design your projects with this in mind. Don't just assign tickets—assign growth opportunities.

4. Building Psychological Safety

Foster a "Blameless" Culture

When incidents happen (and they will), focus on:

1. Immediate Response: Fix the issue (30 minutes)
2. Investigation: Root cause analysis (2-3 hours)
3. Post-Mortem: What can we learn? (team meeting)
4. Improvement: System changes to prevent recurrence (ongoing)

NOT: "Who caused this?"
BUT: "Why did our systems allow this to happen?"

Celebrate Failures as Learning

When someone makes a mistake:

Acknowledge courage: "Thank you for taking that risk and learning from it"
Extract lessons: "What would you do differently next time?"
Share knowledge: "This is valuable for the whole team to understand"

5. Technical Depth as a Team Lead

You don't need to be the best coder, but you must stay technical:

Stay Hands-On

Spend 20-30% of your time coding
Review critical PRs in detail
Pair program with engineers on hard problems
Maintain your technical credibility

Know Your Architecture Inside and Out

// Example: Understand your team's core technology deeply
@RestController
@RequestMapping("/api/accounts")
public class AccountController {
    // You should be able to explain:
    // 1. Why we use Spring Boot
    // 2. Our authentication strategy
    // 3. How this scales at our load
    // 4. Monitoring and alerting setup
}

6. Performance Management and Feedback

The SBI Model: Situation, Behavior, Impact

Give feedback that sticks:

❌ Bad: "Your code quality isn't good"

✅ Good: "In the PR yesterday (Situation), 
I noticed 8 edge cases weren't handled (Behavior). 
This could cause production issues and 
requires teammates to add 4+ hours of review time (Impact).
Let's pair program on testing edge cases next time."

Feedback Should Be Regular, Not Annual

Monthly check-ins (5 minutes each)
Specific, actionable, timely
Balance praise and growth areas (70/30 ratio)

7. Strategic Planning and Vision

Communicate the "Why"

Your team needs to understand the business context:

Business Goals: "We need to reduce latency by 40% because customer retention is at risk"
Technical Vision: "We'll achieve this through caching and async processing"
Team Role: "Your work on the search service is critical to this goal"

Create Technical Roadmaps

Don't just manage sprints—manage trajectory:

Q4 2026: Refactor authentication layer
├── Implement OAuth 2.0
├── Migrate from JWT to opaque tokens
└── Reduce security incidents by 60%

Q1 2027: Microservices infrastructure
├── Containerize all services (Docker)
├── Set up Kubernetes deployment
└── Enable independent team deployments

8. Remote Team Best Practices

Over-Document, Over-Share

Record meeting summaries (Loom videos)
Maintain a team wiki
Use video for complex explanations
Time zone friendly async communication

Maintain Team Connection

Virtual coffee chats (30 min, 1-on-1)
Async team retrospectives
Celebrate wins in public channels

9. Measuring Success

Track what matters:

✅ Team Metrics
- Code quality (test coverage, defect rates)
- Delivery velocity (sustainable, not rushed)
- On-call incidents and MTTR
- Knowledge sharing (internal talks, blog posts)

✅ Individual Metrics
- Learning and skill growth
- Career progression
- Internal promotions
- Peer satisfaction scores

✅ Business Metrics
- Feature delivery timeline
- System reliability (99.9%+ uptime)
- Customer satisfaction

Conclusion

Being an effective software engineering team lead means mastering a unique blend of technical expertise, communication skills, and empathy. Remember:

Lead through clarity: Your communication sets the tone
Invest in people: Grow your team, and they'll move mountains
Stay technical: Credibility comes from understanding what you're leading
Build culture: Psychological safety and blameless post-mortems matter
Think strategically: Balance sprint execution with long-term vision

The best teams aren't built on brilliant individuals—they're built on clear communication, psychological safety, and shared purpose. Master these practices, and you'll not only retain top talent but develop the next generation of leaders.

Share your experiences: What practices have worked best for your team? How do you balance technical work with leadership responsibilities? Let me know in the comments!

Java & Elasticsearch: Search Engines

Said Olano — Fri, 11 Sep 2026 19:49:30 +0000

Java & Elasticsearch: Search Engines

Elasticsearch has become the go-to search engine for Java applications, offering lightning-fast full-text search capabilities, powerful aggregations, and real-time analytics.

Why Elasticsearch with Java?

Elasticsearch's REST API makes it language-agnostic, but Java developers benefit from the official Elasticsearch Java API Client. Combined with Spring Boot, this stack provides a robust foundation for building scalable search systems.

Key advantages include:

Near real-time indexing and searching
Horizontal scalability across clusters
Complex queries and aggregations
Full-text search with relevance scoring
Integration with Spring Data Elasticsearch

Getting Started

First, add the dependency to your Maven pom.xml:

<dependency>
  <groupId>co.elastic.clients</groupId>
  <artifactId>elasticsearch-java</artifactId>
  <version>8.11.0</version>
</dependency>

Building a Search Service

Here's a practical example of creating an Elasticsearch client and indexing documents:

import co.elastic.clients.elasticsearch.ElasticsearchClient;

public class ElasticsearchService {
  private final ElasticsearchClient client;

  public void indexDocument(String index, String docId, Object document) throws IOException {
    client.index(i -> i
      .index(index)
      .id(docId)
      .document(document)
    );
  }
}

Spring Data Integration

For a more Spring-native approach:

@Document(indexName = "products")
public class Product {
  @Id  private String id;
  private String name;
  private Double price;
}

Performance Tips

Use bulk APIs for batch indexing
Leverage filters (cached) over queries
Implement pagination with from and size
Monitor your cluster health

Conclusion

Elasticsearch combined with Java creates a powerful platform for building intelligent search experiences. Start small with a single node, then scale horizontally as your data grows.

Happy searching!

Mastering Spring WebFlux: Building Reactive Web Applications in Java

Said Olano — Thu, 10 Sep 2026 18:52:03 +0000

Mastering Spring WebFlux: Building Reactive Web Applications in Java

Introduction: The Reactive Revolution

In the era of cloud-native applications and microservices, traditional request-response blocking models are reaching their limits. As systems scale to handle millions of concurrent connections, the synchronous, thread-per-request paradigm creates bottlenecks that waste resources and limit throughput. This is where Spring WebFlux enters the picture—a non-blocking, reactive web framework that fundamentally changes how we build scalable Java applications.

Spring WebFlux represents a paradigm shift in web development. Instead of dedicating a thread to each request, WebFlux uses a small pool of threads to handle thousands of concurrent connections through asynchronous, event-driven processing. This approach dramatically reduces memory overhead, improves resource utilization, and enables systems to handle unprecedented levels of traffic with modest hardware.

For architects and senior engineers managing fintech platforms, real-time data pipelines, or high-throughput APIs, WebFlux isn't just an incremental improvement—it's a transformative tool that enables building next-generation applications. This comprehensive guide walks you through the core concepts, implementation patterns, best practices, and production-grade strategies for mastering Spring WebFlux.

The Problem with Traditional Blocking Models

The traditional Spring MVC approach (built on Servlet API) assigns one thread per request. This works well for moderate traffic, but reveals critical limitations at scale:

Thread Exhaustion: With millions of potential concurrent users, maintaining one thread per connection consumes enormous memory (typically 1-2MB per thread). A single server can support only thousands of connections.
Context Switching Overhead: OS schedulers context-switch between thousands of threads, wasting CPU cycles that could process actual business logic.
Resource Inefficiency: Threads spend most time waiting (I/O, database queries, external APIs), yet still consume memory and CPU. This is wasteful.
Latency Under Load: As thread pools saturate, requests queue up, causing cascading latency across the system.

For fintech applications handling market data ingestion, payment processing, or real-time trading, these limitations directly impact system reliability and cost.

What WebFlux Solves

Spring WebFlux addresses these challenges by embracing reactive principles:

Non-blocking I/O: Uses Project Reactor (a reactive streams implementation) to handle operations asynchronously.
Efficient Resource Usage: A handful of threads (typically matching CPU cores) can handle thousands of concurrent connections.
Functional Composition: Leverages reactive operators (map, filter, flatMap, etc.) to compose asynchronous pipelines elegantly.
Backpressure Support: Handles demand signaling, preventing overwhelmed systems from consuming unbounded resources.
Observability: Integrates with modern monitoring and tracing tools for production visibility.

Core Concepts: Understanding Reactive Streams

Before diving into WebFlux implementation, understand the reactive foundation it's built upon.

The Reactive Streams Specification

Reactive Streams is a standard for asynchronous, non-blocking processing with backpressure. It defines four key interfaces:

Publisher: A source of data that emits events over time.
Subscriber: Consumes events emitted by publishers.
Subscription: The connection between publisher and subscriber, enabling flow control.
Processor: Acts as both publisher and subscriber in a pipeline.

Project Reactor: WebFlux's Heart

Spring WebFlux uses Project Reactor, a reactive library implementing Reactive Streams. Reactor provides two primary types:

Mono

A Mono emits 0 or 1 element, then completes or errors. Perfect for single-result operations:

Mono<User> getUser(String id) {
    return userRepository.findById(id);
}

// Consuming a Mono
getUser("123")
    .doOnNext(user -> log.info("User: {}", user.getName()))
    .doOnError(error -> log.error("Failed to fetch user", error))
    .subscribe();

Flux

A Flux emits 0 to N elements over time. Ideal for streams of data:

Flux<Order> getOrderStream() {
    return orderRepository.findAll();
}

// Transforming a Flux
getOrderStream()
    .filter(order -> order.getTotal() > 1000)
    .map(order -> new OrderSummary(order.getId(), order.getTotal()))
    .take(100)
    .subscribe(summary -> log.info("Order: {}", summary));

Key Reactive Operators

Reactor provides 200+ operators for composing reactive pipelines:

Transformation:

map(): Transform each element
flatMap(): Flatten nested publishers
switchMap(): Cancel previous subscription when new item arrives

Filtering:

filter(): Keep elements matching predicate
distinct(): Remove duplicates
take(): Limit to N elements

Combining:

merge(): Combine multiple publishers
zip(): Pair elements from multiple sources
concat(): Sequential combination

Error Handling:

onErrorResume(): Provide fallback publisher
retry(): Retry failed operations
timeout(): Enforce time limits

Building with Spring WebFlux: Practical Patterns

Project Setup

Create a Spring Boot project with WebFlux:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-r2dbc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.r2dbc</groupId>
        <artifactId>r2dbc-postgresql</artifactId>
    </dependency>
</dependencies>

Note: R2DBC (Reactive Relational Database Connectivity) provides non-blocking database access, essential for true end-to-end reactivity.

Pattern 1: Building a Reactive REST API

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public Mono<ResponseEntity<UserResponse>> getUser(@PathVariable String id) {
        return userService.getUserById(id)
            .map(user -> ResponseEntity.ok(toResponse(user)))
            .onErrorResume(UserNotFoundException.class, 
                ex -> Mono.just(ResponseEntity.notFound().build()));
    }

    @GetMapping
    public Flux<UserResponse> getAllUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return userService.getAllUsers(page, size)
            .map(this::toResponse);
    }

    @PostMapping
    public Mono<ResponseEntity<UserResponse>> createUser(
            @RequestBody Mono<CreateUserRequest> request) {
        return request
            .flatMap(userService::createUser)
            .map(user -> ResponseEntity.status(HttpStatus.CREATED)
                .body(toResponse(user)));
    }

    private UserResponse toResponse(User user) {
        return new UserResponse(user.getId(), user.getName(), user.getEmail());
    }
}

Pattern 2: Reactive Data Access Layer

@Repository
public class UserRepository extends ReactiveCrudRepository<User, String> {

    Flux<User> findByStatus(String status);

    Flux<User> findByCreatedDateBetween(LocalDateTime start, LocalDateTime end);
}

@Service
public class UserService {

    private final UserRepository repository;
    private final EmailNotificationService emailService;

    public Mono<User> createUser(CreateUserRequest request) {
        return Mono.just(new User(UUID.randomUUID().toString(), 
                                    request.getName(), 
                                    request.getEmail()))
            .flatMap(repository::save)
            .flatMap(user -> sendWelcomeEmail(user).thenReturn(user))
            .tap(user -> log.info("User created: {}", user.getId()));
    }

    public Flux<User> getAllUsers(int page, int size) {
        return repository.findAll()
            .skip((long) page * size)
            .take(size);
    }

    private Mono<Void> sendWelcomeEmail(User user) {
        return emailService.sendAsync(user.getEmail(), "Welcome to our platform!");
    }
}

Pattern 3: Handling Backpressure

Backpressure allows consumers to signal demand, preventing producer overload:

@Service
public class OrderProcessingService {

    private final OrderRepository orderRepository;
    private final PaymentGateway paymentGateway;

    public Flux<ProcessedOrder> processOrderStream() {
        return orderRepository.findNewOrders()
            .onBackpressureBuffer(1000)  // Buffer up to 1000 items
            .flatMap(order -> processOrder(order), 
                    concurrency = 10)     // Process max 10 concurrently
            .doOnError(error -> log.error("Processing failed", error))
            .retry(2);                    // Retry twice on failure
    }

    private Mono<ProcessedOrder> processOrder(Order order) {
        return paymentGateway.authorize(order.getAmount())
            .flatMap(payment -> orderRepository.markAsPaid(order.getId(), payment))
            .map(this::toProcessedOrder);
    }
}

Pattern 4: Server-Sent Events (SSE)

Stream real-time data to clients:

@GetMapping("/events/trades")
public Flux<ServerSentEvent<TradeUpdate>> streamTrades() {
    return tradeService.getTradeFeed()
        .map(trade -> ServerSentEvent.<TradeUpdate>builder()
            .id(UUID.randomUUID().toString())
            .event("trade")
            .data(new TradeUpdate(trade.getId(), trade.getPrice(), trade.getVolume()))
            .build())
        .onErrorResume(error -> {
            log.error("Trade stream error", error);
            return Flux.empty();
        });
}

Pattern 5: Composing Multiple Reactive Sources

Combine data from multiple services efficiently:

@Service
public class EnrichedUserService {

    private final UserRepository userRepository;
    private final OrderService orderService;
    private final AnalyticsService analyticsService;

    public Mono<EnrichedUser> getEnrichedUser(String userId) {
        return userRepository.findById(userId)
            .zipWith(
                orderService.getUserOrderCount(userId),
                analyticsService.getUserMetrics(userId)
            )
            .map(tuple -> {
                User user = tuple.getT1();
                Long orderCount = tuple.getT2();
                UserMetrics metrics = tuple.getT3();

                return new EnrichedUser(user, orderCount, metrics);
            })
            .onErrorResume(error -> {
                log.warn("Failed to enrich user: {}", userId);
                return Mono.empty();
            });
    }
}

Production Patterns: Building Resilient Systems

Timeout & Circuit Breaker Pattern

@Service
public class ResilientPaymentService {

    private final PaymentGateway gateway;
    private final CircuitBreaker circuitBreaker;

    public Mono<PaymentResult> processPayment(PaymentRequest request) {
        return Mono.just(request)
            .timeout(Duration.ofSeconds(5))  // Hard timeout
            .retryWhen(Retry.backoff(3, Duration.ofMillis(100))
                .filter(throwable -> throwable instanceof TimeoutException))
            .transformDeferred(circuitBreaker.decoratePublisher(
                mono -> gateway.charge(request)))
            .onErrorResume(error -> {
                log.error("Payment failed: {}", error.getMessage());
                return Mono.just(PaymentResult.failed("Service temporarily unavailable"));
            });
    }
}

Request/Response Logging with Tap

@Component
public class LoggingWebFilter implements WebFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        return chain.filter(exchange)
            .doOnNext(response -> {
                log.info("Request: {} {}, Status: {}",
                    exchange.getRequest().getMethod(),
                    exchange.getRequest().getPath(),
                    exchange.getResponse().getStatusCode());
            })
            .doOnError(error -> log.error("Request failed", error));
    }
}

Metrics & Observability

@Service
public class MetricsAwareService {

    private final MeterRegistry meterRegistry;

    public Flux<DataPoint> processStream() {
        return dataSource.getStream()
            .tap(point -> meterRegistry.counter("points.processed").increment())
            .doOnError(error -> meterRegistry.counter("points.failed").increment())
            .tap(Operators.lift((scannable, subscriber) -> 
                new LatencyAwareSubscriber(subscriber, meterRegistry)))
            .retry(2);
    }
}

Best Practices & Architecture Guidelines

1. End-to-End Reactivity

Reactivity is only effective when the entire stack is non-blocking:

Web Layer: Spring WebFlux ✓
Data Access: R2DBC or reactive MongoDB driver ✓
External APIs: Use non-blocking HTTP client (WebClient)
Message Queues: Reactive drivers for RabbitMQ/Kafka

Mixed stacks (e.g., WebFlux + blocking JDBC) defeat the purpose.

2. Resource Pooling & Configuration

spring:
  webflux:
    base-path: /api
  reactor:
    netty:
      io-select-count: 8
      tcp:
        port: 8080
        pending-acquire-timeout: 45000

3. Testing Reactive Code

@Test
public void testUserCreation() {
    CreateUserRequest request = new CreateUserRequest("John Doe", "john@example.com");

    userService.createUser(request)
        .as(StepVerifier::create)
        .assertNext(user -> {
            assertThat(user.getName()).isEqualTo("John Doe");
            assertThat(user.getId()).isNotNull();
        })
        .expectComplete()
        .verifyThenAssertThatResult(Duration.ofSeconds(5));
}

4. Avoid Blocking Operations

Never block a reactive thread pool:

// ❌ WRONG
Flux<User> users = Flux.fromIterable(repository.findAll());  // Blocking call!

// ✅ CORRECT
Flux<User> users = repository.findAll();  // Reactive

5. Memory Leaks & Resource Management

Flux<DatabaseConnection> connections = /* ... */;

// Properly dispose resources
connections
    .doOnNext(conn -> log.info("Acquired connection"))
    .doFinally(signal -> log.info("Releasing connection"))
    .doOnCancel(() -> log.warn("Connection stream cancelled"))
    .subscribe();

Migration Strategy: Spring MVC to WebFlux

For teams with existing Spring MVC applications:

Non-Critical Services: Start with new microservices using WebFlux
Gradual Conversion: Migrate components iteratively (data layer → service → controller)
Parallel Deployment: Run both frameworks temporarily during migration
Testing Extensively: Reactive behavior differs significantly; comprehensive testing is essential
Training: Invest in team education on reactive principles and patterns

Conclusion: The Future is Reactive

Spring WebFlux represents a fundamental evolution in how we build scalable, efficient Java applications. By embracing non-blocking I/O and reactive principles, teams can:

Reduce Infrastructure Costs: Handle 10-100x more concurrency with less hardware
Improve Responsiveness: Sub-millisecond latencies under high load
Scale Elegantly: Microservices architectures become truly resilient
Future-Proof Systems: React to emerging needs without architectural redesign

The reactive paradigm is no longer optional in cloud-native development—it's essential. Whether you're building fintech platforms, real-time analytics pipelines, or high-throughput APIs, Spring WebFlux provides the tools and patterns needed to succeed.

Start small, learn the operators, embrace the functional composition style, and progressively transform your architecture. The effort pays dividends in scalability, maintainability, and operational efficiency.

The reactive revolution is here. Spring WebFlux is your toolkit to lead it.

References & Further Reading

Spring AI + OpenAI: Complete Integration Guide for Java (2026)

Said Olano — Thu, 10 Sep 2026 00:52:18 +0000

Spring AI + OpenAI: Complete Integration Guide for Java Applications

Introduction

Spring AI is an initiative from the Spring ecosystem that provides a unified abstraction for integrating Large Language Models (LLMs) into Java applications. In this article, we'll explore how to build a Spring Boot application that seamlessly integrates with OpenAI, enabling you to create intelligent applications with chat conversations, embeddings generation, and real-time information processing.

In recent years, artificial intelligence has become a fundamental component in software development. However, integrating LLMs into enterprise Java applications has been challenging due to the lack of standard abstractions. Spring AI solves this problem by providing:

Unified abstraction for multiple AI providers (OpenAI, Anthropic, Azure, Google, etc.)
Native support for Spring Boot with autoconfiguration
Context management and conversation memory
RAG integration (Retrieval-Augmented Generation)
Security and output validation
Token management and cost tracking

What is Spring AI?

Spring AI is a Spring framework that simplifies the integration of language models into Java applications. It acts as an abstraction layer between your application and AI providers, allowing you to switch providers without modifying your business logic.

Key Features

1. ChatClient API
The main interface for interacting with LLMs. Provides simple methods to send prompts and receive responses.

2. Multiple Provider Support

OpenAI (GPT-4, GPT-3.5-turbo)
Azure OpenAI
Anthropic Claude
Google Gemini
Ollama (local)

3. Autoconfiguration
Spring Boot automatically detects your API key and configures the client without boilerplate code.

4. Context Management
Maintains conversation history to create more natural chat experiences.

5. Embeddings and Vector Databases
Support for generating embeddings and integrating with vector databases like Weaviate, Milvus, and Chroma.

Prerequisites

Before getting started, you'll need:

Java 21+ (recommended)
Maven or Gradle for dependency management
OpenAI API Key (https://platform.openai.com/account/api-keys)
IntelliJ IDEA or VS Code as your IDE
Maven >= 3.6 or Gradle >= 7.0

Project Setup

Step 1: Create the Base Project

mvn archetype:generate -DgroupId=mx.development.josesaid.ai \\
  -DartifactId=spring-ai-openai-demo \\
  -DarchetypeArtifactId=maven-archetype-quickstart

Step 2: Update pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>

    <groupId>mx.development.josesaid.ai</groupId>
    <artifactId>spring-ai-openai-demo</artifactId>
    <version>1.0.0</version>
    <name>spring-ai-openai-demo</name>
    <description>Spring AI + OpenAI Integration Demo</description>

    <properties>
        <java.version>21</java.version>
        <spring-ai.version>1.0.0</spring-ai.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Starters -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring AI OpenAI -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
            <version>${spring-ai.version}</version>
        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Testing -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Step 3: Configure application.yml

spring:
  application:
    name: spring-ai-openai-demo
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.7
          max-tokens: 2048

server:
  port: 8080
  servlet:
    context-path: /api

Implementation: ChatRunner Component

Here's the heart of our Spring AI integration. The ChatRunner component demonstrates how to create a fully functional chat client that interacts with OpenAI through Spring AI. This component leverages Spring Boot's CommandLineRunner to execute custom code when the application starts. The magic happens in the runner() method where we inject the ChatClient.Builder (auto-configured by Spring AI), build the client, and make a call to OpenAI to demonstrate the integration.

Without Spring AI, you'd need to manually manage HTTP calls, JSON serialization, error handling, token management, and authentication configuration. Spring AI abstracts all this complexity, allowing you to focus purely on your business logic. The flow is elegant: you build the client, send a prompt using the fluent API, call .call() for a synchronous request to OpenAI, and extract the response with .content().

package mx.development.josesaid.ai.spring.ai.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;

@Component
public class ChatRunner {

    @Bean
    public CommandLineRunner runner(ChatClient.Builder builder) {
        return (String[] args) -> {
            System.out.println();
            System.out.println("Provider - OpenAI");

            // Build the chat client with Spring AI
            ChatClient chatClient = builder.build();

            // Perform a simple conversation
            String response = chatClient
                .prompt("What is Spring AI?")
                .call()
                .content();

            // Display the response
            System.out.println(response);
        };
    }
}

Building a Complete REST API

While ChatRunner is useful for initial testing, building a real REST API is more practical for production applications:

package mx.development.josesaid.ai.spring.ai.demo.controller;

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/chat")
@RequiredArgsConstructor
public class ChatController {

    private final ChatClient chatClient;

    @PostMapping("/message")
    public ChatResponse sendMessage(@RequestBody ChatRequest request) {
        String response = chatClient
            .prompt(request.getMessage())
            .call()
            .content();

        return new ChatResponse(response);
    }

    @GetMapping("/health")
    public String health() {
        return "Spring AI + OpenAI is running";
    }
}

// DTO Classes
record ChatRequest(String message) {}
record ChatResponse(String message) {}

Error Handling and Validation

In production, you need to handle errors gracefully:

@RestController
@RequestMapping("/chat")
@RequiredArgsConstructor
public class ChatController {

    private final ChatClient chatClient;

    @PostMapping("/message")
    public ResponseEntity<?> sendMessage(@RequestBody ChatRequest request) {
        try {
            if (request.message() == null || request.message().isBlank()) {
                return ResponseEntity.badRequest()
                    .body(new ErrorResponse("Message cannot be empty"));
            }

            String response = chatClient
                .prompt(request.message())
                .call()
                .content();

            return ResponseEntity.ok(new ChatResponse(response));
        } catch (Exception e) {
            return ResponseEntity.status(500)
                .body(new ErrorResponse("Error processing message: " + e.getMessage()));
        }
    }
}

record ErrorResponse(String error) {}

Environment Variable Configuration

To keep your API key secure, use environment variables. In IntelliJ, the best practice is to use VM options:

VM Options (Recommended):

-Dspring.ai.openai.api-key=sk-proj-YOUR_KEY_HERE

Environment Variables:

OPENAI_API_KEY=sk-proj-YOUR_KEY_HERE

application.yml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

Testing with curl

Once the application is running at http://localhost:8080/api:

curl -X POST http://localhost:8080/api/chat/message \\
  -H "Content-Type: application/json" \\
  -d '{"message":"What are the advantages of Spring AI?"}'

Real-World Use Cases

Customer Support Chatbot - Integrate with vector databases for context-aware support
Sentiment Analysis - Process customer reviews automatically
Content Generation - Create product descriptions, articles, and emails
Semantic Search - Implement intelligent search using embeddings
Information Processing - Extract structured data from unstructured text

Best Practices

Never hardcode API keys - always use environment variables
Implement Rate Limiting - OpenAI has request limits
Cache results - reuse responses for identical prompts
Monitor costs - each call has a cost
Validate inputs - sanitize user prompts
Implement timeouts - OpenAI calls can be slow
Use streaming - improve UX for long responses

Conclusion

Spring AI democratizes access to advanced LLMs for Java developers. The combination of Spring Boot with Spring AI creates a powerful stack for building enterprise AI applications. Whether you're building chatbots, recommendation systems, or analysis tools, Spring AI provides the foundation you need.

Next Steps:

Explore RAG (Retrieval-Augmented Generation)
Integrate vector databases (Weaviate, Milvus)
Implement function calling
Experiment with different models

springai #openai #java #springboot #ai #llm #microservices

Deploying Microservices Architectures with AWS and Java: A Complete Guide

Said Olano — Wed, 09 Sep 2026 22:29:25 +0000

Introduction

Microservices architectures have become the gold standard for building scalable, maintainable applications. When combined with AWS's powerful infrastructure and Java's enterprise-grade capabilities, you get a robust platform for modern application development. In this guide, we'll explore the complete journey of deploying microservices on AWS using Java.

Architecture Overview

A typical microservices deployment on AWS consists of:

ECS/EKS for container orchestration
Application Load Balancer (ALB) for traffic distribution
RDS/DynamoDB for data persistence
SQS/SNS for async messaging
CloudWatch for monitoring and logging

Spring Boot Microservice Template

Let's start with a basic Spring Boot microservice:

@SpringBootApplication
@RestController
@RequestMapping("/api/products")
public class ProductServiceApplication {

    @Autowired
    private ProductRepository repository;

    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable String id) {
        return repository.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<Product> createProduct(@RequestBody Product product) {
        return ResponseEntity.ok(repository.save(product));
    }

    public static void main(String[] args) {
        SpringApplication.run(ProductServiceApplication.class, args);
    }
}

Docker Containerization

Containerize your microservice with a multi-stage Dockerfile:

FROM maven:3.8-openjdk-17 AS builder
WORKDIR /app
COPY . .
RUN mvn clean package -DskipTests

FROM openjdk:17-slim
WORKDIR /app
COPY --from=builder /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

AWS ECS Deployment Configuration

Deploy to ECS Fargate using CloudFormation or AWS CDK:

// AWS CDK Java example
Stack stack = new Stack(app, "MicroservicesStack");

Cluster cluster = Cluster.Builder.create(stack, "Cluster")
    .vpc(vpc)
    .build();

FargateService service = FargateService.Builder.create(stack, "Service")
    .cluster(cluster)
    .taskDefinition(taskDefinition)
    .desiredCount(3)
    .publicLoadBalancer(true)
    .build();

service.getTargetGroup().enableCookieStickiness(Duration.hours(1));

Service-to-Service Communication

Implement resilient inter-service calls using Resilience4j:

@Service
public class OrderService {

    private final RestTemplate restTemplate;
    private final CircuitBreaker circuitBreaker;

    @Retry(name = "productService", fallbackMethod = "productFallback")
    @CircuitBreaker(name = "productService", fallbackMethod = "productFallback")
    public Product getProductInfo(String productId) {
        return restTemplate.getForObject(
            "http://product-service:8080/api/products/" + productId,
            Product.class
        );
    }

    public Product productFallback(String productId, Exception ex) {
        return new Product(productId, "Unavailable", 0);
    }
}

Monitoring and Logging

Leverage CloudWatch and Micrometer for comprehensive observability:

@Configuration
public class MetricsConfiguration {

    @Bean
    public MeterBinder customMetrics() {
        return (registry) -> {
            Counter.builder("orders.created")
                .description("Total orders created")
                .register(registry);
        };
    }
}

Key Takeaways

Container-First Approach: Use Docker for consistency across environments
Service Discovery: Leverage AWS service discovery or Consul
Resilience Patterns: Implement circuit breakers, retries, and timeouts
Monitoring: Set up CloudWatch dashboards and alarms early
Auto-Scaling: Configure target tracking policies for dynamic scaling

By following these patterns and leveraging AWS's managed services with Java's enterprise ecosystem, you can build production-ready microservices architectures that scale effortlessly.

Next Steps

Consider exploring AWS Lambda for serverless microservices, implement API Gateway for API management, and set up CI/CD pipelines with AWS CodePipeline for seamless deployments.

Building Python-to-Spring Boot Microservices: A Complete Integration Guide

Said Olano — Tue, 08 Sep 2026 19:22:18 +0000

Building Python-to-Spring Boot Microservices: A Complete Integration Guide

Introduction: The Era of Polyglot Microservices

In modern software architecture, microservices have become the de facto standard for building scalable and maintainable applications. One of the most common challenges in this transition is the need to integrate services written in different programming languages. This article will guide you step-by-step through creating a Python microservice that communicates securely and efficiently with another microservice built in Spring Boot.

Polyglot architecture is not a trend—it's a reality. Organizations adopt the most appropriate language for each task: Python for machine learning and data analysis, Java/Spring Boot for critical and scalable systems, Node.js for real-time applications. The ability for these services to communicate with each other is fundamental.

Why Integrate Python with Spring Boot?

Real-World Use Cases

Real-Time Data Analysis: A Python service with pandas and scikit-learn executes analysis while Spring Boot handles transactions.
Specialized Microservices: Python for NLP and computer vision; Spring Boot for business logic and persistence.
Legacy Systems: Expand capabilities of existing Java systems with new Python functionality.
Distributed Teams: Different teams work with their preferred languages, integrated through REST APIs.

Advantages of This Combination

Technology Flexibility: Choose the right tool for each problem
Independent Scalability: Both services scale according to their needs
Easier Maintenance: Specialized teams for each technology
Gradual Adoption: Migrate or expand capabilities without rewriting everything

Solution Architecture

Our architecture consists of:

┌─────────────────────┐
│   Client/UI         │
└──────────┬──────────┘
           │
      ┌────▼─────────┐
      │  Spring Boot  │ (Port 8080)
      │  Service      │
      │  (Orchestrator)
      └────┬──────────┘
           │ REST Call
           │
      ┌────▼──────────┐
      │  Python       │ (Port 5000)
      │  Microservice │
      │  (Processor)  │
      └────┬──────────┘
           │
      ┌────▼──────────┐
      │  Database     │
      │  (Data)       │
      └───────────────┘

Step 1: Building the Python Microservice

Project Setup

mkdir python-microservice
cd python-microservice
python3 -m venv venv
source venv/bin/activate
pip install flask flask-cors requests python-dotenv

Main Application (app.py)

from flask import Flask, jsonify, request
from flask_cors import CORS
from dotenv import load_dotenv
import os
import logging

load_dotenv()
app = Flask(__name__)
CORS(app)
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

from routes.api import api_bp
app.register_blueprint(api_bp)

@app.route('/health', methods=['GET'])
def health_check():
    return jsonify({
        'status': 'healthy',
        'service': 'python-microservice',
        'version': '1.0.0'
    }), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=int(os.getenv('FLASK_PORT', 5000)))

Core Service (services/processor.py)

import requests
import logging
from typing import Dict, Any, Optional
from config import config

logger = logging.getLogger(__name__)

class DataProcessor:
    def __init__(self):
        self.spring_url = config.SPRING_BOOT_URL
        self.timeout = config.REQUEST_TIMEOUT

    def send_to_spring_boot(self, endpoint: str, data: Dict[str, Any], method: str = 'POST'):
        try:
            url = f"{self.spring_url}{endpoint}"
            if method.upper() == 'POST':
                response = requests.post(url, json=data, timeout=self.timeout)
            else:
                response = requests.get(url, timeout=self.timeout)
            response.raise_for_status()
            return response.json()
        except Exception as e:
            logger.error(f"Error: {str(e)}")
            raise

processor = DataProcessor()

Step 2: Building the Spring Boot Microservice

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>spring-boot-microservice</artifactId>
    <version>1.0.0</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

UserService.java

@Service
public class UserService {
    private final RestTemplate restTemplate;
    @Value("${python.microservice.url}")
    private String pythonMicroserviceUrl;

    public UserResponse processUserData(UserRequest request) {
        try {
            String pythonUrl = pythonMicroserviceUrl + "/api/process";
            UserResponse response = restTemplate.postForObject(
                pythonUrl, request, UserResponse.class
            );
            return new UserResponse(true, request.getUserId(), 
                "Processing completed", response);
        } catch (Exception e) {
            return new UserResponse(false, request.getUserId(), 
                "Error: " + e.getMessage(), null);
        }
    }
}

Step 3: Docker Compose

version: '3.8'
services:
  python-service:
    build:
      context: ./python-microservice
    ports:
      - "5000:5000"
    environment:
      - SPRING_BOOT_URL=http://spring-boot-service:8080
  spring-boot-service:
    build:
      context: ./spring-boot-microservice
    ports:
      - "8080:8080"

Integration Testing

curl -X POST http://localhost:5000/api/process \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123, "action": "update"}'

Production Considerations

Authentication: JWT or OAuth2
Circuit Breaker: Resilience4j for fault tolerance
Rate Limiting: Protect endpoints from abuse
Observability: Distributed logging and tracing
Monitoring: Metrics and alerting

Best Practices

Use API versioning for backward compatibility
Implement proper error handling and logging
Use containerization for consistent deployments
Document API contracts thoroughly
Implement health checks for readiness probes

Conclusion

Integrating Python with Spring Boot empowers you to build modern, scalable microservices. Leverage each language's strengths to create resilient systems. The future of software development is polyglot—choose the right tool for each problem.

Integración de Microservicios: Python + Spring Boot (Guía Completa 2026)

Said Olano — Tue, 08 Sep 2026 19:06:59 +0000

Crear un Microservicio en Python que Llama a Otro en Spring Boot

Introducción: La Era de los Microservicios Poliglota

En la arquitectura moderna de software, los microservicios se han convertido en el estándar de facto para construir aplicaciones escalables y mantenibles. Uno de los desafíos más comunes en esta transición es la necesidad de integrar servicios escritos en diferentes lenguajes de programación. Este artículo te guiará paso a paso en cómo crear un microservicio en Python que se comunique de forma segura y eficiente con otro microservicio construido en Spring Boot.

La arquitectura poliglota no es una tendencia, es una realidad. Las organizaciones adoptan el lenguaje más apropiado para cada tarea: Python para machine learning y análisis de datos, Java/Spring Boot para sistemas críticos y escalables, Node.js para aplicaciones en tiempo real. La capacidad de que estos servicios conversen entre sí es fundamental.

¿Por Qué Integrar Python con Spring Boot?

Casos de Uso Reales

Análisis de Datos en Tiempo Real: Un servicio Python con pandas, scikit-learn ejecuta análisis mientras Spring Boot maneja las transacciones.
Microservicios Especializados: Python para NLP, visión por computadora; Spring Boot para lógica de negocio y persistencia.
Sistemas Heredados: Expandir capacidades de sistemas Java existentes con nuevas funcionalidades en Python.
Equipos Distribuidos: Diferentes equipos trabajan con sus lenguajes preferidos, integrados mediante APIs REST.

Ventajas de Esta Combinación

Flexibilidad Tecnológica: Elige la herramienta correcta para cada problema
Escalabilidad Independiente: Ambos servicios escalan según sus necesidades
Mantenimiento Facilitado: Equipos especializados en cada tecnología
Adopción Gradual: Migra o expande capacidades sin reescribir todo

Arquitectura de la Solución

Nuestra arquitectura consta de:

┌─────────────────────┐
│   Cliente/UI        │
└──────────┬──────────┘
           │
      ┌────▼─────────┐
      │  Spring Boot  │ (Puerto 8080)
      │  Service      │
      │  (Orquestador)│
      └────┬──────────┘
           │ REST Call
           │
      ┌────▼──────────┐
      │  Python       │ (Puerto 5000)
      │  Microservicio│
      │  (Procesador) │
      └────┬──────────┘
           │
      ┌────▼──────────┐
      │  BD/Cache     │
      │  (Datos)      │
      └───────────────┘

Paso 1: Crear el Microservicio en Python

1.1 Configuración del Proyecto

mkdir python-microservice
cd python-microservice
python3 -m venv venv
source venv/bin/activate
pip install flask flask-cors requests python-dotenv
pip freeze > requirements.txt

1.2 Archivo Principal (app.py)

from flask import Flask, jsonify, request
from flask_cors import CORS
from dotenv import load_dotenv
import os
import logging

load_dotenv()
app = Flask(__name__)
CORS(app)

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

from routes.api import api_bp
app.register_blueprint(api_bp)

@app.route('/health', methods=['GET'])
def health_check():
    return jsonify({
        'status': 'healthy',
        'service': 'python-microservice',
        'version': '1.0.0'
    }), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=int(os.getenv('FLASK_PORT', 5000)))

1.3 Servicios Principales (services/processor.py)

import requests
import logging
from typing import Dict, Any, Optional
from config import config

logger = logging.getLogger(__name__)

class DataProcessor:
    def __init__(self):
        self.spring_url = config.SPRING_BOOT_URL
        self.timeout = config.REQUEST_TIMEOUT

    def send_to_spring_boot(self, endpoint: str, data: Dict[str, Any], method: str = 'POST') -> Optional[Dict[str, Any]]:
        try:
            url = f"{self.spring_url}{endpoint}"
            logger.info(f"Enviando {method} a {url}")

            if method.upper() == 'POST':
                response = requests.post(url, json=data, timeout=self.timeout)
            elif method.upper() == 'GET':
                response = requests.get(url, timeout=self.timeout)
            else:
                raise ValueError(f"Método no soportado: {method}")

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            logger.error(f"Timeout conectando a {self.spring_url}")
            raise
        except Exception as e:
            logger.error(f"Error: {str(e)}")
            raise

processor = DataProcessor()

Paso 2: Crear el Microservicio en Spring Boot

2.1 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>spring-boot-microservice</artifactId>
    <version>1.0.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

2.2 UserService.java

package com.example.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
import com.example.dto.UserRequest;
import com.example.dto.UserResponse;

@Service
public class UserService {
    private static final Logger logger = LoggerFactory.getLogger(UserService.class);
    private final RestTemplate restTemplate;

    @Value("${python.microservice.url}")
    private String pythonMicroserviceUrl;

    public UserService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    public UserResponse processUserData(UserRequest request) {
        try {
            logger.info("Procesando usuario: {}", request.getUserId());
            String pythonUrl = pythonMicroserviceUrl + "/api/process";

            UserResponse pythonResponse = restTemplate.postForObject(pythonUrl, request, UserResponse.class);
            logger.info("Respuesta Python recibida");

            return new UserResponse(true, request.getUserId(), "Procesamiento completado", pythonResponse);
        } catch (Exception e) {
            logger.error("Error llamando a servicio Python: {}", e.getMessage());
            return new UserResponse(false, request.getUserId(), "Error: " + e.getMessage(), null);
        }
    }
}

2.3 UserController.java

package com.example.controller;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import com.example.dto.UserRequest;
import com.example.dto.UserResponse;
import com.example.service.UserService;

@RestController
@RequestMapping("/api/users")
@CrossOrigin(origins = "*")
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping("/process")
    public ResponseEntity<UserResponse> processUser(@RequestBody UserRequest request) {
        UserResponse response = userService.processUserData(request);
        return ResponseEntity.status(response.isSuccess() ? HttpStatus.OK : HttpStatus.BAD_REQUEST).body(response);
    }
}

Paso 3: Docker Compose

version: '3.8'
services:
  python-service:
    build:
      context: ./python-microservice
    ports:
      - "5000:5000"
    environment:
      - SPRING_BOOT_URL=http://spring-boot-service:8080

  spring-boot-service:
    build:
      context: ./spring-boot-microservice
    ports:
      - "8080:8080"

Paso 4: Testing de la Integración

curl -X POST http://localhost:5000/api/process \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123, "action": "update"}'

Consideraciones de Producción

Autenticación: Implementar JWT o OAuth2
Circuit Breaker: Usar Resilience4j
Rate Limiting: Proteger endpoints
Observabilidad: Logging distribuido y tracing
Configuración: Usar variables de entorno
Pruebas: Aumentar cobertura de tests

Conclusión

Integrar Python con Spring Boot permite construir arquitecturas modernas, escalables y mantenibles. Esta guía te proporciona los fundamentos para empezar. Los microservicios poliglotas son el futuro del desarrollo de software.

Crear un Microservicio en Python que Llama a Otro en Spring Boot

Said Olano — Tue, 08 Sep 2026 19:06:26 +0000

Crear un Microservicio en Python que Llama a Otro en Spring Boot

Introducción: La Era de los Microservicios Poliglota

¿Por Qué Integrar Python con Spring Boot?

Casos de Uso Reales

Análisis de Datos en Tiempo Real: Un servicio Python con pandas, scikit-learn ejecuta análisis mientras Spring Boot maneja las transacciones.
Microservicios Especializados: Python para NLP, visión por computadora; Spring Boot para lógica de negocio y persistencia.
Sistemas Heredados: Expandir capacidades de sistemas Java existentes con nuevas funcionalidades en Python.
Equipos Distribuidos: Diferentes equipos trabajan con sus lenguajes preferidos, integrados mediante APIs REST.

Ventajas de Esta Combinación

Flexibilidad Tecnológica: Elige la herramienta correcta para cada problema
Escalabilidad Independiente: Ambos servicios escalan según sus necesidades
Mantenimiento Facilitado: Equipos especializados en cada tecnología
Adopción Gradual: Migra o expande capacidades sin reescribir todo

Arquitectura de la Solución

Nuestra arquitectura consta de:

┌─────────────────────┐
│   Cliente/UI        │
└──────────┬──────────┘
           │
      ┌────▼─────────┐
      │  Spring Boot  │ (Puerto 8080)
      │  Service      │
      │  (Orquestador)│
      └────┬──────────┘
           │ REST Call
           │
      ┌────▼──────────┐
      │  Python       │ (Puerto 5000)
      │  Microservicio│
      │  (Procesador) │
      └────┬──────────┘
           │
      ┌────▼──────────┐
      │  BD/Cache     │
      │  (Datos)      │
      └───────────────┘

Paso 1: Crear el Microservicio en Python

1.1 Configuración del Proyecto

mkdir python-microservice
cd python-microservice
python3 -m venv venv
source venv/bin/activate
pip install flask flask-cors requests python-dotenv
pip freeze > requirements.txt

1.2 Archivo Principal (app.py)

from flask import Flask, jsonify, request
from flask_cors import CORS
from dotenv import load_dotenv
import os
import logging

load_dotenv()
app = Flask(__name__)
CORS(app)

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

from routes.api import api_bp
app.register_blueprint(api_bp)

@app.route('/health', methods=['GET'])
def health_check():
    return jsonify({
        'status': 'healthy',
        'service': 'python-microservice',
        'version': '1.0.0'
    }), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=int(os.getenv('FLASK_PORT', 5000)))

1.3 Servicios Principales (services/processor.py)

import requests
import logging
from typing import Dict, Any, Optional
from config import config

logger = logging.getLogger(__name__)

class DataProcessor:
    def __init__(self):
        self.spring_url = config.SPRING_BOOT_URL
        self.timeout = config.REQUEST_TIMEOUT

    def send_to_spring_boot(self, endpoint: str, data: Dict[str, Any], method: str = 'POST') -> Optional[Dict[str, Any]]:
        try:
            url = f"{self.spring_url}{endpoint}"
            logger.info(f"Enviando {method} a {url}")

            if method.upper() == 'POST':
                response = requests.post(url, json=data, timeout=self.timeout)
            elif method.upper() == 'GET':
                response = requests.get(url, timeout=self.timeout)
            else:
                raise ValueError(f"Método no soportado: {method}")

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            logger.error(f"Timeout conectando a {self.spring_url}")
            raise
        except Exception as e:
            logger.error(f"Error: {str(e)}")
            raise

processor = DataProcessor()

Paso 2: Crear el Microservicio en Spring Boot

2.1 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>spring-boot-microservice</artifactId>
    <version>1.0.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

2.2 UserService.java

package com.example.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
import com.example.dto.UserRequest;
import com.example.dto.UserResponse;

@Service
public class UserService {
    private static final Logger logger = LoggerFactory.getLogger(UserService.class);
    private final RestTemplate restTemplate;

    @Value("${python.microservice.url}")
    private String pythonMicroserviceUrl;

    public UserService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    public UserResponse processUserData(UserRequest request) {
        try {
            logger.info("Procesando usuario: {}", request.getUserId());
            String pythonUrl = pythonMicroserviceUrl + "/api/process";

            UserResponse pythonResponse = restTemplate.postForObject(pythonUrl, request, UserResponse.class);
            logger.info("Respuesta Python recibida");

            return new UserResponse(true, request.getUserId(), "Procesamiento completado", pythonResponse);
        } catch (Exception e) {
            logger.error("Error llamando a servicio Python: {}", e.getMessage());
            return new UserResponse(false, request.getUserId(), "Error: " + e.getMessage(), null);
        }
    }
}

2.3 UserController.java

package com.example.controller;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import com.example.dto.UserRequest;
import com.example.dto.UserResponse;
import com.example.service.UserService;

@RestController
@RequestMapping("/api/users")
@CrossOrigin(origins = "*")
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping("/process")
    public ResponseEntity<UserResponse> processUser(@RequestBody UserRequest request) {
        UserResponse response = userService.processUserData(request);
        return ResponseEntity.status(response.isSuccess() ? HttpStatus.OK : HttpStatus.BAD_REQUEST).body(response);
    }
}

Paso 3: Docker Compose

version: '3.8'
services:
  python-service:
    build:
      context: ./python-microservice
    ports:
      - "5000:5000"
    environment:
      - SPRING_BOOT_URL=http://spring-boot-service:8080

  spring-boot-service:
    build:
      context: ./spring-boot-microservice
    ports:
      - "8080:8080"

Testing de la Integración

curl -X POST http://localhost:5000/api/process \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123, "action": "update"}'

Consideraciones de Producción

Autenticación: Implementar JWT o OAuth2
Circuit Breaker: Usar Resilience4j
Rate Limiting: Proteger endpoints
Observabilidad: Logging distribuido y tracing
Configuración: Usar variables de entorno
Pruebas: Aumentar cobertura de tests