DEV Community: Nitish

Spring Boot 3.2 + Docker Multi-Stage Builds: Slim Production Images for Microservices

Nitish — Fri, 19 Jun 2026 05:29:04 +0000

Spring Boot 3.2 + Docker Multi-Stage Builds: Slim Production Images for Microservices

Without optimized Docker builds, your Spring Boot microservices deploy 650MB images containing build tools and debug symbols. Production containers run with unnecessary vulnerabilities and waste storage/bandwidth during scaling events.

Prerequisites

Java 17 SDK (Eclipse Temurin 17.0.9)
Spring Boot 3.2.4
Docker Engine 24.0.6+
Maven 3.9.6
Basic understanding of Dockerfile syntax

Building Fat JARs the Traditional Way

Spring Boot's Maven plugin packages dependencies and application code into a single executable JAR. A naive Dockerfile copies this JAR into a full JDK image:

FROM eclipse-temurin:17-jdk
COPY target/myapp.jar /app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

This creates a 567MB image containing the full JDK, Maven dependencies, and build artifacts - none of which are needed at runtime.

Multi-Stage Build Optimization

Split the Dockerfile into build and runtime phases. The first stage compiles the application, while the final stage copies only necessary artifacts:

# Build stage
FROM eclipse-temurin:17-jdk as builder
WORKDIR /app
COPY .mvn/ .mvn
COPY mvnw pom.xml ./
RUN ./mvnw dependency:go-offline
COPY src/ src/
RUN ./mvnw package -DskipTests

# Runtime stage  
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY --from=builder /app/target/*.jar /app.jar
RUN adduser --system --no-create-home appuser
USER appuser
ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app.jar"]

This reduces image size by 68% (180MB final image) and removes build tools from production. The Alpine-based JRE provides a minimal Linux environment.

Image Size Reduction Techniques

Further optimize by stripping unused dependencies and compressing layers:

# In build stage:
RUN ./mvnw package -DskipTests -Dspring-boot.repackage.excludeDevtools=true

# In runtime stage:
RUN apk add --no-cache libstdc++ # Only if native dependencies exist

Common Mistakes

Mistake 1: Not pruning Maven dependencies in build stage

# Wrong: Copies entire project before resolving dependencies
COPY . .
RUN mvn package

# Fixed: Layer caching for dependencies
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src/ src/
RUN mvn package

Copying the POM first allows Docker to cache dependency downloads separately from source code changes.

Mistake 2: Running as root in production

# Wrong: Defaults to root user
ENTRYPOINT ["java","-jar","/app.jar"]

# Fixed: Non-privileged user
RUN adduser --system --no-create-home appuser
USER appuser
ENTRYPOINT ["java","-jar","/app.jar"]

Root containers pose security risks. Alpine's adduser creates a minimal user account without a home directory.

Mistake 3: Using JDK instead of JRE in runtime

# Wrong: Includes compiler tools
FROM eclipse-temurin:17-jdk

# Correct: Minimal JRE
FROM eclipse-temurin:17-jre-alpine

The JDK adds 140MB of development tools unused in production. Alpine's musl libc further reduces size over glibc.

Summary

Use separate build and runtime stages to exclude development dependencies
Prefer JRE-alpine base images for production deployments
Create non-root users and enable security hardening flags
Layer Dockerfile commands to optimize build caching
Strip debug symbols and exclude devtools from production JARs

The author publishes Spring Boot starter templates at https://gumroad.com

Spring Boot 3.2 + Testcontainers: Reliable Integration Testing with Real Dependencies

Nitish — Fri, 19 Jun 2026 05:21:27 +0000

Spring Boot 3.2 + Testcontainers: Reliable Integration Testing with Real Dependencies

Without Testcontainers, your integration tests might pass locally with H2 but fail in CI when connecting to a mismatched PostgreSQL version. Production database migrations succeed in development but break when applied to a different database engine.

Prerequisites

Java 17 or later
Spring Boot 3.2.x
Docker Engine 24.0+ with Docker Compose
JUnit Jupiter 5.9+
Testcontainers 1.19.3

Configuring Testcontainers for Database Testing

Testcontainers provides disposable database instances for integration tests. Add these dependencies to your pom.xml:

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

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>1.19.3</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>postgresql</artifactId>
        <version>1.19.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Disable the default datasource in test configuration:

# src/test/resources/application.properties
spring.datasource.driver-class-name=org.testcontainers.jdbc.ContainerDatabaseDriver
spring.datasource.url=jdbc:tc:postgresql:15-alpine:///test?TC_DAEMON=true
spring.flyway.enabled=false

Writing a Containerized Integration Test

This test verifies database schema initialization using a real PostgreSQL instance. The container starts before tests and destroys itself afterward:

package com.example.orderservice;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.jdbc.core.JdbcTemplate;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import static org.assertj.core.api.Assertions.assertThat;

@Testcontainers
@SpringBootTest
class OrderRepositoryIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15-alpine")
        .withDatabaseName("test")
        .withUsername("test")
        .withPassword("test");

    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Test
    void should_connect_to_live_database() {
        Integer result = jdbcTemplate.queryForObject("SELECT 1", Integer.class);
        assertThat(result).isEqualTo(1);
    }
}

Run the test with Docker Desktop active. Testcontainers will download the PostgreSQL image on first execution and reuse it for subsequent runs.

Managing Container Lifecycles

Define a base test class to share containers across multiple test classes:

package com.example.shared;

import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@Testcontainers
public abstract class BaseIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15-alpine")
        .withReuse(true);

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }
}

Common Mistakes

Mistake 1: Non-static container field causing multiple instances

@Container // Missing static modifier
PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>();

@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>();

Testcontainers requires static fields for class-level containers. Non-static fields create new containers per test method.

Mistake 2: Hardcoded JDBC URL in test properties

spring.datasource.url=jdbc:postgresql://localhost:5432/test

@DynamicPropertySource
static void registerProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
}

Hardcoded URLs bypass container networking. Use @DynamicPropertySource to inject runtime connection details.

Mistake 3: Missing container reuse configuration

new PostgreSQLContainer<>("postgres:15-alpine");

new PostgreSQLContainer<>("postgres:15-alpine")
    .withReuse(true);

Without reuse, Testcontainers destroys containers after each test class. Enable reuse in .testcontainers.properties and chain withReuse(true).

Summary

Replace in-memory databases with Testcontainers-managed PostgreSQL instances using @Testcontainers and @Container
Inject dynamic connection properties using @DynamicPropertySource registry
Enable container reuse with .withReuse(true) and testcontainers.reuse.enable=true in .testcontainers.properties

The author publishes Spring Boot starter templates at https://gumroad.com

Spring Boot 3 and JVM Resilience in API Development: Avoiding JavaScript’s 2014 Pitfalls

Nitish — Sun, 14 Jun 2026 22:39:13 +0000

Spring Boot 3 and JVM Resilience in API Development: Avoiding JavaScript’s 2014 Pitfalls

Without proper thread pooling and structured error handling, your production APIs might face cascading failures under load—like Node.js applications did during JavaScript’s scalability debates in 2014—while Spring Boot’s thread-per-request model remains unmonitored and unoptimized.

Prerequisites

Java 17 or later
Spring Boot 3.2.4
Spring Web and Spring Data JPA dependencies
Docker 24.0+ and PostgreSQL 15 image
Postman or curl for API testing

Configuring Spring Boot for Concurrent Request Handling

Spring Boot’s default Tomcat configuration handles 100 simultaneous requests, but tuning is critical for high-throughput APIs. Add these dependencies to optimize thread pools and metrics:

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

server.tomcat.threads.max=200
server.tomcat.threads.min-spare=20
management.endpoints.web.exposure.include=health,metrics,threaddump

server.tomcat.threads.max: Maximum worker threads for concurrent requests
management.endpoints.web.exposure.include: Enables actuator metrics for monitoring thread usage

Implementing Resilient Order Processing with @RestController

This REST controller uses Spring’s thread-per-request model to avoid JavaScript-style event-loop blocking, with explicit error handling for database failures:

package com.example.orderservice;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import org.springframework.dao.DataAccessException;

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

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public String createOrder(@RequestBody OrderRequest request) {
        try {
            // Simulate database operation
            processOrder(request);
            return "Order processed";
        } catch (DataAccessException e) {
            throw new ServiceUnavailableException("Database write failed");
        }
    }

    private void processOrder(OrderRequest request) {
        // Business logic here
    }
}

@ResponseStatus(HttpStatus.SERVICE_UNAVAILABLE)
class ServiceUnavailableException extends RuntimeException {
    ServiceUnavailableException(String message) {
        super(message);
    }
}

Test with curl -X POST http://localhost:8080/orders -H "Content-Type: application/json" -d '{"productId": 123}'. Verify thread usage via /actuator/metrics/tomcat.threads.busy.

Dockerizing PostgreSQL for Spring Data JPA

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: orders
      POSTGRES_USER: spring
      POSTGRES_PASSWORD: secure
    ports:
      - "5432:5432"

Run docker-compose up before starting the Spring Boot app to ensure database connectivity.

Common Mistakes

Mistake 1: Blocking the main thread with synchronous I/O

// Wrong: Synchronous HTTP call in controller
String result = restTemplate.getForObject("https://slow-api", String.class);

// Fix: Offload to @Async service
@Async
public CompletableFuture<String> fetchExternalData() {
    return CompletableFuture.completedFuture(restTemplate.getForObject(...));
}

Synchronous calls in controllers exhaust worker threads. Use @Async with a configured task executor.

Mistake 2: Missing retries for transient database errors

// Wrong: No retry for JPA operations
orderRepository.save(order);

// Fix: Spring Retry with exponential backoff
@Retryable(retryFor = DataAccessException.class, maxAttempts = 3)
public void saveOrder(Order order) {
    orderRepository.save(order);
}

Add @EnableRetry and spring-retry dependency to recover from transient database issues.

Mistake 3: Overlooking connection pool limits

# Wrong: Default Hikari pool size
spring.datasource.hikari.maximum-pool-size=10

# Fix: Match pool to thread capacity
spring.datasource.hikari.maximum-pool-size=200

Too few database connections cause thread starvation. Align Hikari pool size to Tomcat’s threads.max.

Summary

Configure server.tomcat.threads.max to match expected concurrent users and monitor via /actuator/metrics
Use @Async with a custom ThreadPoolTaskExecutor for I/O-bound operations to prevent thread blocking
Set spring.datasource.hikari.maximum-pool-size equal to Tomcat threads to avoid database connection starvation

The author publishes Spring Boot starter templates at https://gumroad.com

Spring Boot 3 Virtual Threads with Java 21: Scaling Web Apps Without Thread Pool Exhaustion

Nitish — Sun, 14 Jun 2026 07:37:33 +0000

Spring Boot 3 Virtual Threads with Java 21: Scaling Web Apps Without Thread Pool Exhaustion

Without virtual threads, your Spring Boot application may exhaust its thread pool during high concurrency, causing request timeouts and HTTP 503 errors while CPU sits underutilized. Traditional thread-per-request models waste resources managing OS threads instead of processing actual work.

Prerequisites

Java 21 JDK (OpenJDK 21.0.2 or later)
Spring Boot 3.2.0+
Maven 3.9+ or Gradle 8.4+
Docker 24.0+ (for containerized testing)
IntelliJ IDEA 2023.2+ or VS Code with Java extensions

Enabling Virtual Threads in Spring Boot 3.2

Spring Boot 3.2 introduces first-class support for Java 21's virtual threads through a simple configuration toggle. Add the Spring Boot parent POM and configure the virtual threads property:

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

# Enable Java 21 virtual threads
spring.threads.virtual.enabled=true

This setting replaces the default Tomcat thread pool with a virtual thread executor, allowing millions of concurrent requests without increasing OS thread count.

Implementing Virtual Thread-Powered REST Endpoints

Create non-blocking HTTP handlers that leverage virtual threads for CPU-bound operations. This controller executes parallel image processing using virtual threads:

package com.example.vthreads;

import org.springframework.web.bind.annotation.*;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

@RestController
@RequestMapping("/images")
public class ImageController {

    private final ExecutorService virtualExecutor = 
        Executors.newVirtualThreadPerTaskExecutor();

    @PostMapping("/process")
    public String processImage(@RequestBody byte[] imageData) {
        virtualExecutor.execute(() -> 
            ImageProcessor.applyFilters(imageData)
        );
        return "Processing started in virtual thread";
    }
}

Test with curl -X POST http://localhost:8080/images/process -d @large_image.jpg and monitor thread count in logs. Virtual threads will appear with ForkJoinPool identifiers instead of tomcat threads.

Common Mistakes

Mistake 1: Using Spring Boot 3.1 with Java 21

<!-- WRONG -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.5</version>
</parent>

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

Spring Boot 3.1 doesn’t support the virtual threads property. The 3.2 parent POM adds Java 21 compatibility.

Mistake 2: Missing Virtual Threads Configuration

# WRONG: Property missing
# spring.threads.virtual.enabled=true

# FIX
spring.threads.virtual.enabled=true

Without this flag, Spring Boot uses platform threads even on Java 21. The property activates the virtual thread executor.

Mistake 3: Blocking in Virtual Threads

// WRONG
virtualExecutor.execute(() -> {
    Thread.sleep(1000); // Blocks carrier thread
});

// FIX
virtualExecutor.execute(() -> {
    try {
        Thread.sleep(Duration.ofSeconds(1)); // Yields carrier thread
    } catch (InterruptedException e) { /* ... */ }
});

Use Duration-based sleep instead of millisecond sleep to enable proper thread yielding in virtual threads.

Summary

Activate virtual threads with spring.threads.virtual.enabled=true in Spring Boot 3.2+ applications
Replace @Async and thread pools with Executors.newVirtualThreadPerTaskExecutor() for CPU-bound tasks
Monitor virtual thread behavior using /actuator/metrics/jvm.threads.virtual endpoint

The author publishes Spring Boot starter templates at https://gumroad.com

Spring Boot 3 + Micrometer + Grafana: Metrics That Survive Midnight Deployments

Nitish — Sun, 14 Jun 2026 02:19:05 +0000

Okay, the user wants me to write a technical article about Spring Boot observability with Micrometer and Grafana. Let me start by understanding the structure they provided. The title needs to be specific, including the main names. The example given uses Spring Boot 3 and Micrometer, so I'll follow that format.

The opening should address a real problem developers face in production. Instead of generic statements, I need to mention specific issues like metrics not being exposed or dashboards not updating. That makes it more relatable.

Prerequisites: I need to list specific versions and tools. Java 17, Spring Boot 3.2, Micrometer, Grafana, and maybe Docker. Let me check the latest versions to ensure accuracy.

Section 1 is about core concepts and dependencies. I'll explain Micrometer's role and then provide the pom.xml with Micrometer and Actuator dependencies. Then the application.properties entries to expose metrics and enable Prometheus. Each property needs a brief explanation.

Section 2 is the implementation. I need a Java class that demonstrates custom metrics. A service with a counter and timer makes sense. The code must be complete with package, imports, annotations, and methods. After the code, mention how to test it via the Actuator endpoint.

Section 3 is infrastructure. Since Grafana and Prometheus are involved, I should include a docker-compose.yml to set them up. Also, a Prometheus config file. Then explain how to import the dashboard.

Common Mistakes: Three specific errors. Maybe missing the Prometheus dependency, incorrect meter names, and not starting the registry. Show wrong code, the fix, and explain why it's wrong.

Summary: Three actionable points, like adding dependencies, using custom metrics, and using Docker for Grafana.

I need to ensure all code blocks have the correct language tags. No placeholders, everything compilable. Use Spring Boot 3.x only. Avoid any marketing language, keep it developer-focused.

Let me start drafting each section, making sure to follow the structure exactly. Check that the Java class includes all necessary parts. Verify the dependencies are up-to-date. For the docker-compose, use the latest images. In common mistakes, pick issues that are easy to overlook but critical for functionality.

Finally, the footer with the author's link. Make sure the article is within the word count. Avoid any markdown beyond what's specified. Double-check for any typos or incorrect versions.

Spring Boot 3 + Micrometer + Grafana: Metrics That Survive Midnight Deployments

Production Spring Boot apps fail silently when JVM memory spikes go undetected, custom business metrics aren’t tracked, and Grafana dashboards show stale data from misconfigured Prometheus scrapers. These gaps turn simple outages into all-night debugging sessions.

Prerequisites

Java 17+ SDK
Spring Boot 3.2.x
Micrometer 1.12+ (included via Spring Boot)
Grafana 10.1+ (via Docker)
Prometheus 2.47+ (via Docker)

Section 1 — core concept and dependency setup

Micrometer acts as a metrics facade, exposing Spring Boot's internal metrics while enabling custom instrumentation. Add these dependencies:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

# application.properties
management.endpoints.web.exposure.include=health,metrics,prometheus
management.metrics.export.prometheus.enabled=true
management.server.port=8081

exposure.include: Enables Prometheus scraping endpoint
metrics.export.prometheus: Activates registry
server.port: Separates metrics from main app port

Section 2 — the implementation

Create a service tracking order processing metrics with custom counter and timer. The @MeterBinder annotation registers metrics at startup:

package com.example.orderservice;

import io.micrometer.core.instrument.*;
import org.springframework.stereotype.Service;
import org.springframework.context.annotation.Bean;

@Service
public class OrderMetrics {

    private final Counter ordersCreated;
    private final Timer orderProcessingTime;

    public OrderMetrics(MeterRegistry registry) {
        ordersCreated = Counter.builder("orders.created")
                .description("Total completed orders")
                .register(registry);

        orderProcessingTime = Timer.builder("orders.processing.time")
                .description("Order fulfillment latency")
                .publishPercentiles(0.95)
                .register(registry);
    }

    @Bean
    public MeterBinder cacheMetrics() {
        return registry -> Gauge.builder("orders.queue.size", this::simulateQueue)
                .register(registry);
    }

    private Double simulateQueue() {
        return Math.random() * 100;
    }

    public void recordOrder() {
        ordersCreated.increment();
        orderProcessingTime.record(() -> {
            try { Thread.sleep((long)(Math.random() * 200)); } 
            catch (InterruptedException ignored) {}
        });
    }
}

Test by hitting /actuator/prometheus and searching for orders_created_total. Call recordOrder() from a controller to generate metrics.

Section 3 — infrastructure or integration

Create docker-compose.yml for observability stack:

version: '3'
services:
  prometheus:
    image: prom/prometheus:v2.47.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:10.1.5
    ports:
      - "3000:3000"

# prometheus.yml
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: 'spring'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8081']

Run docker compose up, then import dashboard ID 4701 in Grafana for Spring Boot metrics.

Common Mistakes

Mistake 1: Missing Prometheus registry dependency

Wrong:

<!-- Only actuator present -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Fix:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Prometheus metrics won't appear without the registry implementation.

Mistake 2: Incorrect meter name casing

Wrong:

Counter.builder("Orders_Created") // Upper case

Fix:

Counter.builder("orders.created") // Lowercase with dots

Prometheus requires snake_case metrics - Micrometer auto-converts dots to underscores.

Mistake 3: Not starting meter registry

Wrong:

public OrderMetrics() { 
    // No MeterRegistry injection
}

Fix:

public OrderMetrics(MeterRegistry registry) {
    // Use injected registry
}

Metrics won't be registered without binding to the active MeterRegistry.

Summary

Expose Prometheus endpoint with actuator and registry dependency
Instrument custom business logic with @MeterBinder and Timer/Counter builders
Configure Docker-based Grafana with host.docker.internal for local dev scraping

The author publishes Spring Boot starter templates at https://gumroad.com

Spring Boot Observability: Real-Time Monitoring with Micrometer and Grafana

Nitish — Sat, 13 Jun 2026 06:25:26 +0000

Okay, I need to write a technical article about Spring Boot observability with Micrometer and Grafana. The user specified a specific structure, so I should follow that closely. Let me start by understanding the requirements.

First, the title needs to be SEO-friendly and specific. Maybe something like "Spring Boot Observability: Real-Time Monitoring with Micrometer and Grafana". That's clear and includes the main keywords.

The pain points: Developers struggle with monitoring Spring Boot apps in production, lack real-time insights, and have difficulty setting up dashboards. I need to phrase this in two sentences.

Prerequisites: Java 17, Spring Boot 3.x, Docker, Grafana and Prometheus setup, basic Micrometer knowledge. That's three to five bullet points.

Main section: Explaining how to integrate Micrometer, export to Prometheus, and visualize in Grafana. Need a complete code example. Let me outline the steps. Create a Spring Boot app, add Micrometer and Prometheus dependencies, configure properties, create a sample controller with metrics, set up Prometheus and Grafana via Docker Compose, and create a dashboard.

Common mistakes: Three mistakes. Maybe not configuring the actuator endpoints, not registering custom metrics correctly, and incorrect Grafana configuration. For each mistake, explain what's wrong and show the fix.

Summary: Key takeaways about the importance of observability, avoiding common mistakes, and leveraging Grafana for visualization.

Now, let me structure each part. The code examples need to be complete and compilable. For the main code example, a controller with a custom metric. The dependencies in build.gradle or pom.xml. Since the user didn't specify build tool, maybe use Maven as it's common. But wait, the user mentioned "exact code example". Let me check the Spring Boot 3.x setup. The main class is straightforward. The controller should have a counter metric. Also, the application.properties for enabling actuator endpoints.

For common mistakes:

Mistake 1: Not exposing actuator endpoints. The fix is adding management.endpoints.web.exposure.include=prometheus,metrics in properties.

Mistake 2: Incorrect metric registration. Using Metrics.globalRegistry instead of MeterRegistry. Show the wrong code and then the corrected version with @Autowired MeterRegistry.

Mistake 3: Not configuring Grafana data source properly. The fix is ensuring Prometheus URL is correct in Grafana's data source config.

I need to make sure all code snippets have the correct imports. For example, the controller imports io.micrometer.core.instrument.Counter and MeterRegistry.

Also, the Docker Compose file for Prometheus and Grafana. The Prometheus config file needs to target the Spring Boot app. Grafana's default credentials.

Check word count. The article should be between 950-1200 words. Each section needs to be concise but thorough.

Let me start drafting each part step by step, ensuring all rules are followed. No placeholders, all code must be complete. Make sure to use Spring Boot 3.x APIs. For example, in the controller, use @RestController and @GetMapping with Spring Web.

Double-check the Prometheus configuration YAML file. The scrape config should point to localhost:8080/actuator/prometheus.

In the Grafana section, explain importing the dashboard ID 4701, which is the Micrometer dashboard.

For common mistake 2, the incorrect code would be using a global registry without injection, and the fix is using the MeterRegistry bean provided by Spring.

Alright, putting it all together now. Make sure each code block has the correct language tag. Java for Java code, yaml for application.properties and Prometheus config, and text for Docker Compose maybe? Wait, Docker Compose is YAML as well. So all YAML files use yaml tags.

Check that all code is correct. For example, the Maven dependencies for Spring Boot Actuator and Micrometer Registry Prometheus.

Yes, the dependencies would be:

org.springframework.boot
spring-boot-starter-actuator

io.micrometer
micrometer-registry-prometheus

In the application.properties, management.endpoints.web.exposure.include=prometheus,metrics.

The controller code with a counter that increments on each request.

The Prometheus config scrape job.

Docker Compose file with Prometheus and Grafana services, volumes for config and data.

Grafana setup steps: login, add data source, import dashboard.

Common mistakes with code examples showing the wrong and right way.

Finally, the summary with key points.

I think that covers all the requirements. Now, write the article following this structure and content.

Spring Boot Observability: Real-Time Monitoring with Micrometer and Grafana

Production debugging without metrics is like flying blind. This guide solves two critical pain points: instrumenting Spring Boot applications for meaningful metrics collection, and transforming raw data into actionable Grafana dashboards without complex infrastructure.

Prerequisites

Java 17+ and Spring Boot 3.x
Docker installed for monitoring stack
Basic understanding of Micrometer metrics
Grafana Cloud account or local installation
curl/postman for endpoint testing

Implementing Metrics Export with Micrometer

First, create a new Spring Boot 3.x application with these dependencies:

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

Configure actuator endpoints in application.properties:

# application.properties
management.endpoints.web.exposure.include=health,info,prometheus,metrics
management.metrics.export.prometheus.enabled=true
server.port=8080

Create a controller with custom metrics:

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class OrderController {

    private final Counter orderCounter;

    public OrderController(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.total")
                                  .description("Total orders processed")
                                  .register(registry);
    }

    @GetMapping("/order")
    public String placeOrder() {
        orderCounter.increment();
        return "Order placed!";
    }
}

Run the application and verify metrics at http://localhost:8080/actuator/prometheus.

Monitoring Stack Setup

Create a Docker compose file:

# docker-compose.yml
version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana-enterprise:latest
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana

volumes:
  grafana_data:

Configure Prometheus scraping:

# prometheus.yml
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: 'spring-boot'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8080']

Start the stack with docker-compose up -d. Access Prometheus at http://localhost:9090 and Grafana at http://localhost:3000.

Common Mistakes

Mistake 1: Missing Actuator Exposure

Developers enable Micrometer but forget to expose endpoints:

# Wrong configuration
management.endpoints.web.exposure.include=health,info

Fix by including Prometheus endpoint:

# application.properties
management.endpoints.web.exposure.include=health,info,prometheus,metrics

Mistake 2: Manual Metric Registration

Creating metrics without proper Spring integration:

// Wrong approach
Counter counter = Counter.builder("api.calls").register(Metrics.globalRegistry);

Inject MeterRegistry instead:

// Correct implementation
private final Counter apiCounter;

public OrderController(MeterRegistry registry) {
    this.apiCounter = Counter.builder("api.calls")
                            .register(registry);
}

Mistake 3: Grafana Data Source Misconfiguration

Using localhost in Prometheus URL inside Docker:

# Wrong Grafana data source
http://localhost:9090

Use Docker's internal networking:

# Correct configuration
http://prometheus:9090

Summary

Micrometer provides standardized metrics collection across JVM applications
Proper actuator configuration is crucial for Prometheus scraping
Grafana dashboards require correct data source networking in containerized environments

The author publishes Spring Boot starter templates at https://gumroad.com