DEV Community: Matheus Bernardes Spilari

Creating Log-Based Alerts with Grafana, Loki, and Promtail

Matheus Bernardes Spilari — Mon, 04 Aug 2025 13:00:00 +0000

Monitoring is great, but alerting is what actually wakes us up. In this post, I’ll show how we built a log-based alerting pipeline using Grafana, Loki, and Promtail, running entirely in containers.

Yes, alerts triggered from log patterns, not metrics. This approach is especially useful when monitoring behaviors like rate-limiter violations that may not expose traditional metrics.

Why Log-Based Alerts?

We were facing a challenge: we implemented a rate limiter in Nginx to prevent abuse, but traditional metrics collection (via Prometheus) couldn't capture rate-limit violations (HTTP 429 responses), because those were handled entirely at the reverse proxy level, not within the app itself.

The solution? Log everything. Then alert from logs.

🛠️ Tools Used

Grafana
Loki
Promtail
Nginx (with rate limiting configured)
Docker Compose
Mailtrap (for testing alert emails)
Alertmanager (for email delivery)

Configuring Custom Access Logs in Nginx

In Nginx, you can define a custom log format using the log_format directive and then tell Nginx to use it with the access_log directive. Here's an example configuration:

http {

    log_format structured '$remote_addr - $remote_user [$time_local] '
                          '"$request" $status $body_bytes_sent '
                          '"$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log structured;
}

Explanation:

log_format structured: This defines a custom log format named structured. The format includes common fields such as client IP address, username, timestamp, request line, HTTP status code, response size, referrer, and user agent.
access_log: This tells Nginx to write access logs to /var/log/nginx/access.log using the structured format defined above.

This setup allows you to customize what gets logged in each request, which is useful for debugging, analytics, or integrating with log management systems.

💡 Tip: The name structured is just a label. You can name your format anything you'd like, such as custom, detailed, or json_logs depending on its purpose.

Set Up the Stack (Grafana, Loki, Promtail)

Our stack uses docker-compose to orchestrate services.

Loki Configuration

At the root of our project we create a folder called loki, inside of that, we gonna have two files, config.yaml and Dockerfile.

You can find this file here
config.yaml

auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9096
  log_level: debug
  grpc_server_max_concurrent_streams: 1000

common:
  instance_addr: 127.0.0.1
  path_prefix: /tmp/loki
  storage:
    filesystem:
      chunks_directory: /tmp/loki/chunks
      rules_directory: /tmp/loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

query_range:
  results_cache:
    cache:
      embedded_cache:
        enabled: true
        max_size_mb: 100

limits_config:
  metric_aggregation_enabled: true

schema_config:
  configs:
    - from: 2020-10-24
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h

pattern_ingester:
  enabled: true
  metric_aggregation:
    loki_address: localhost:3100

ruler:
  alertmanager_url: http://alertmanager:9093

frontend:
  encoding: protobuf

# By default, Loki will send anonymous, but uniquely-identifiable usage and configuration
# analytics to Grafana Labs. These statistics are sent to https://stats.grafana.org/
#
# Statistics help us better understand how Loki is used, and they show us performance
# levels for most users. This helps us prioritize features and documentation.
# For more information on what's sent, look at
# https://github.com/grafana/loki/blob/main/pkg/analytics/stats.go
# Refer to the buildReport method to see what goes into a report.
#
# If you would like to disable reporting, uncomment the following lines:
#analytics:
#  reporting_enabled: false

💡 Tip: The alertmanager we configured in the last post, we are using his docker url.

Dockerfile

FROM grafana/loki:latest

COPY config.yaml /etc/loki/config.yml

ENTRYPOINT ["/usr/bin/loki", "--config.file=/etc/loki/config.yml", "--config.expand-env=true"]

Promtail Configuration

Promtail tails the access.log file in the Nginx container and pushes it to Loki.
We are going to create a folder at the root called promtailand inside of that two files config.yaml and Dockerfile.

config.yaml

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: nginx-logs
    static_configs:
      - targets:
          - localhost
        labels:
          job: nginx
          __path__: /var/log/nginx/access.log

💡 Tip: You can find the config file right here.

Dockerfile:

FROM grafana/promtail:latest

COPY config.yaml /etc/promtail/config.yml

ENTRYPOINT ["/usr/bin/promtail", "-config.file=/etc/promtail/config.yml"]

Explore Logs in Grafana

In the grafana dashboard, go to Connections > Data Sources > Add Data Source > Seach for: Loki

Configure the connection url to http://loki:3100

Once Loki is added as a data source, you can use Explore in Grafana to query for specific patterns like:

{job="nginx"} |= "429"

We tested the rate limiter by sending many requests to the same endpoint — triggering 429s — and confirming they were logged.

Create Alerts on Rate Limit Violations

Now the cool part — alerting when rate limiting is consistently violated:

Loki Query (in Grafana alert):

count_over_time({job="nginx"} |= "429" [1m]) > 5

This triggers an alert if more than 5 requests per minute result in a 429 status.

Alert description:

Summary: Rate limiter triggered
Description: The rate limiter was triggered more than 5 times in the last minute.

Send Alerts via Alertmanager

Alerts from Grafana are routed to Alertmanager, which is configured to send emails via Mailtrap:

global:
  smtp_smarthost: 'sandbox.smtp.mailtrap.io:2525'
  smtp_from: 'alertmanager@email.com'
  smtp_auth_username: '<your_username>'
  smtp_auth_password: '<your_password>'

route:
  receiver: email-alert

receivers:
  - name: email-alert
    email_configs:
      - to: 'devs@yourcompany.com'
        send_resolved: true

In Grafana, configure a Contact Point that targets Alertmanager.

Improving Email Content

We customized our email template in Alertmanager to include meaningful data, especially since log-based alerts can have dynamic labels like:

html: |
  <h2>[{{ .Status | toUpper }}] {{ .CommonAnnotations.summary }}</h2>
  <p>{{ .CommonAnnotations.description }}</p>
  <ul>
    {{ range .Alerts }}
      <li>
        <strong>Alert:</strong> {{ .Labels.alertname }}<br/>
        <strong>Filename:</strong> {{ .Labels.filename }}<br/>
        <strong>Service:</strong> {{ .Labels.service_name }}<br/>
        <strong>Time:</strong> {{ .StartsAt }}
      </li>
    {{ end }}
  </ul>

This ensures that alerts triggered by logs still include all the context needed to debug them.

Update our docker compose

promtail:
    container_name: promtail
    build:
      context: ./promtail
    networks:
      - app_network
    ports:
      - "9094:9094"
    volumes:
      - ./nginx/logs:/var/log/nginx

  loki:
    container_name: loki
    build:
      context: ./loki
    networks:
      - app_network
    ports:
      - "3100:3100"
    volumes:
      - ./loki:/loki
      - loki_data:/var/loki
    depends_on:
      - promtail

Final Result

With this setup:

Nginx limits abusive traffic and logs violations.
Promtail forwards those logs to Loki.
Grafana detects violations with log queries and fires alerts.
Alertmanager sends customized emails to our dev team.

No code change in the app. Just pure log power.

Conclusion

Using Grafana and Loki for log-based alerting opened up an entire layer of observability for us. It’s especially powerful when paired with infrastructure-level tools like Nginx rate limiting.

📍 Reference

💻 Project Repository

Project Repository on Github

👋 Talk to me

Observability 101: Metrics, Logs, and Traces. What’s the Difference ?

Matheus Bernardes Spilari — Mon, 28 Jul 2025 13:00:00 +0000

As modern applications become more distributed and complex, observability becomes critical. But observability isn’t just one thing — it’s a combination of metrics, logs, and traces, each with a unique purpose.

In this post, we’ll break down:

What each of these pillars does ?
Why they matter ?
When to use them ?
Tools you can use for each

Metrics: The Pulse of Your System

Metrics are numerical representations of system state over time. They provide real-time, aggregated insights into how your system is performing.

What They Do:

Show trends over time (e.g. CPU usage, request rates)
Enable alerting when thresholds are crossed
Power dashboards and health checks

Examples:

HTTP requests per second
Error rate over the last 5 minutes
Memory or disk usage

Common Tools:

Prometheus (most popular in the OSS world)
Grafana (for visualization)
Datadog, New Relic, CloudWatch

When to Use:

Alerting on thresholds (e.g. 500 errors > 1%)
Monitoring performance trends
Capacity planning

Logs: The Forensic Evidence

Logs are timestamped, textual records of events emitted by your applications or systems. They give detailed, context-rich insights into what happened — and why.

What They Do:

Help debug specific issues
Provide context that metrics lack
Useful for audit trails and compliance

Examples:

POST /api/v1/login - 401 Unauthorized
Exception: NullPointerException at Line 42
Custom business logic messages

Common Tools:

Loki (Grafana’s log aggregation system)
ELK Stack (Elasticsearch + Logstash + Kibana)
Fluentd, Filebeat, Graylog

When to Use:

Troubleshooting specific incidents
Digging deep into application behavior
Correlating events with metrics

Tracing: The Full Journey of a Request

Traces follow the path of a single request as it travels through your system. Tracing helps you understand how long each step takes, where failures occur, and where your bottlenecks are.

What They Do:

Show end-to-end request flow across services
Reveal performance bottlenecks
Help identify latency and dependency issues

Examples:

API call takes 4s → 3.5s spent in a slow DB query
Request touches service A → B → C

Common Tools:

OpenTelemetry (standard library for instrumentation)
Grafana Tempo
Jaeger
Zipkin
Lightstep, Honeycomb, AWS X-Ray

When to Use:

Diagnosing latency or slowness
Visualizing service-to-service communication
Improving request performance

How They Work Together

Feature	Metrics	Logs	Traces
Format	Time-series numbers	Structured/unstructured text	Spans with context
Scope	System-wide	Event-specific	Request-level
Good for	Alerting, trends	Debugging, context	Latency, dependencies
Retention	Aggregated, long	High volume, filtered	Short-term, sampled

Together, these three form the pillars of observability and a healthy, production-grade system should leverage all of them.

Final Thoughts: Tooling for a Full Observability Stack

A modern stack might look like this:

📈 Metrics: Prometheus + Grafana
📝 Logs: Promtail + Loki
🧭 Traces: OpenTelemetry SDK + Grafana Tempo
📬 Alerting: Alertmanager

Add instrumentation to your apps, monitor via dashboards, and receive alerts before your users do. That’s observability done right.

Wrapping Up

Understanding the difference between metrics, logs, and traces helps you make better decisions about what to monitor, where to look during incidents, and how to build more resilient systems.

📍 Reference

👋 Talk to me

How to Send Email Alerts for Failures in Spring Boot Using Prometheus and Alertmanager

Matheus Bernardes Spilari — Mon, 21 Jul 2025 13:00:00 +0000

Monitoring resilience patterns like Circuit Breakers is critical to detect downstream failures early. In this tutorial, we’ll walk through a real-world setup using Prometheus and Alertmanager to send email alerts when a Circuit Breaker is frequently triggered in a Spring Boot application.

Stack Overview

Spring Boot: exposes metrics via /actuator/prometheus
Resilience4j: manages the Circuit Breaker
Prometheus: collects metrics
Alertmanager: triggers email alerts
Mailtrap: email sandbox (SMTP server)

Configuration

The circuit breaker configuration is here on this post
The Prometheus configuration is here on this post

1. Create Alert manager container

In our docker-compose.yaml file, add this:

prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    networks:
      - app_network
    volumes:
      - ./prometheus/prometheus.yaml:/etc/prometheus/prometheus.yml
      - ./alertManager/alerts.yaml:/etc/prometheus/alerts.yaml
      - prometheus_data:/prometheus

alertmanager:
    image: prom/alertmanager:latest
    container_name: alertmanager
    networks:
      - app_network
    ports:
    - "9093:9093"
    volumes:
    - ./alertManager/alertManager.yaml:/etc/alertmanager/alertmanager.yml

2. Configuring Prometheus

In prometheus.yaml file, add:


alerting:
  alertmanagers:
    - static_configs:
        - targets: 
          - alertmanager:9093

rule_files:
  - "alerts.yaml"

3. Create Alert Rules

Create a file alerts.yaml:

groups:
  - name: spring-boot-alerts
    rules:
      - alert: HighErrorRate
        expr: rate(http_server_requests_seconds_count{status=~"5.."}[1m]) > 0.5
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "Tax error 5xx too high"
          description: "More than 50% of the requests on the last 1 minute return error 5xx."

      - alert: InstanceDown
        expr: up{job="spring-boot-app"} == 0
        for: 30s
        labels:
          severity: critical
        annotations:
          summary: "Spring Boot instance is down."
          description: "One of the instances of the application is not responding."

      - alert: CircuitBreakerTripped
        expr: rate(http_server_requests_seconds_count{status="503"}[1m]) > 0.2
        for: 30s
        labels:
          severity: warning
        annotations:
          summary: "Circuit Breaker frequently activated."
          description: "The application is respondig with status 503 frequently, this means internal server issues."

      - alert: RateLimitExceeded
        expr: rate(http_server_requests_seconds_count{status="429"}[1m]) > 0
        for: 30s
        labels:
          severity: info
        annotations:
          summary: "Rate Limit exceed."
          description: "The NGINX return 429(Too Many Requests), this means that the tax of requests was exceeded."

4. Configure Alertmanager with Mailtrap

In alertmanager.yml:

global:
  smtp_smarthost: 'sandbox.smtp.mailtrap.io:2525'
  smtp_from: 'alertmanager@demo.com'
  smtp_auth_username: 'your_mailtrap_username'
  smtp_auth_password: 'your_mailtrap_password'

route:
  receiver: email-alert

receivers:
  - name: email-alert
    email_configs:
      - to: 'devs@empresa.com'
        send_resolved: true
        headers:
          subject: '[Application Alert] {{ .CommonAnnotations.summary }}'
        html: |
          <h2>[{{ .Status | toUpper }}] {{ .CommonAnnotations.summary }}</h2>
          <p>{{ .CommonAnnotations.description }}</p>
          <hr />
          <ul>
          {{ range .Alerts }}
            <li>
              <strong>Alert:</strong> {{ .Labels.alertname }}<br/>
              <strong>Instance:</strong> {{ .Labels.instance }}<br/>
              <strong>Severity:</strong> {{ .Labels.severity }}<br/>
              <strong>Starts at:</strong> {{ .StartsAt }}
            </li>
          {{ end }}
          </ul>

✅ Tip: You can test it with Mailtrap (https://mailtrap.io) before connecting to a real SMTP provider.

5. Testing the Alert

Simulate downstream failure in your Spring Boot service and trip the circuit breaker.

Then check:

Prometheus UI (http://localhost:9090) → Alerts tab
Alertmanager UI (http://localhost:9093) → Firing alerts
Mailtrap inbox → you should receive an email

Conclusion

With this setup, you now have a powerful and flexible way to monitor Circuit Breaker activity in your Spring Boot applications using Prometheus and Alertmanager.

By combining metrics from resilience4j with alerting rules, you can detect fault patterns early and react quickly to downstream issues—before they escalate.

While we used Mailtrap as a safe sandbox to test email alerts, you can easily switch to real-world notification channels by updating your alertmanager.yml. For example:

Gmail: for production email notifications using app passwords
Slack: for team-wide real-time alerting
Microsoft Teams, Opsgenie, or PagerDuty for advanced incident management

This flexibility makes the Prometheus + Alertmanager stack a reliable choice for both development and production observability.

📍 Reference

💻 Project Repository

Project Repository on Github

👋 Talk to me

French Barber – A Modern Barber Shop Web App with Next.js and Cal.com Integration

Matheus Bernardes Spilari — Mon, 23 Jun 2025 13:00:00 +0000

As developers, we often seek projects that challenge us to apply our front-end knowledge while also creating something beautiful and functional. That was my goal with French Barber — a fictional barber shop website I built to improve my skills with Next.js, TypeScript, and Tailwind CSS.

In this blog post, I’ll walk you through the key features of the project, the tech stack I used, and how I recently integrated Cal.com (formerly Calendso) to allow users to book appointments online.

About the Project

French Barber is not a real business. It's a web design and development exercise inspired by a beautiful UI I found on Figma. The site replicates a clean, modern barber shop landing page, complete with service highlights, imagery, and — now — an embedded booking experience.

I designed this app to be deployed and easily accessible online, using Vercel for continuous deployment.

🔗 Live demo

Tech Stack

Next.js – for server-side rendering and routing
TypeScript – for type safety and scalability
Tailwind CSS – for utility-first styling
Cal.com – for real-time appointment scheduling
Vercel – for effortless deployment and hosting

Appointment Scheduling with Cal.com

One of the most exciting recent additions to the project is the integration of Cal.com, which allows users to schedule appointments seamlessly.

Instead of building a backend scheduling system from scratch, I opted for a modern SaaS solution that handles availability, calendar syncing, and email notifications — all in one.

Users can now:

Book their haircut online
Select available time slots
Get reminders and confirmations

Adaptable for Any Service Business

While the current design is tailored to a barber shop, this project can be easily adapted to other service-based businesses, such as:

💼 Psychologists or therapists
🦷 Dentists and doctors
✂️ Hairdressers and beauticians
💆 Aesthetic or wellness clinics
🧑‍🏫 Coaches or consultants

With Cal.com, scheduling isn't limited to physical appointments. It can be fully integrated with Google Calendar, and supports platforms like Zoom, Google Meet, and Microsoft Teams — making it perfect for online consultations or meetings.

This opens the door to use this template as a base for:

Booking online therapy sessions
Scheduling medical appointments
Managing spa and salon services
Organizing remote consultations or coaching calls

All with automatic calendar syncing and video conferencing links sent to the user.

📸 Screenshots

🧪 Running Locally

Want to test it out or build on top of it? Here's how you can run it locally:

git clone https://github.com/MSpilari/barber-shop.git
cd barber-shop
npm install
npm run dev

Open http://localhost:3000 in your browser.

📍 Reference

Calendso/Cal

💻 Project Repository

Project Repository on Github

👋 Talk to me

Facade Design Pattern in Java

Matheus Bernardes Spilari — Mon, 16 Jun 2025 13:00:00 +0000

When working with object-oriented design, it's common to face complex systems composed of many interdependent classes. Sometimes, you just want a simple way to use them without worrying about the internal details.

This is where the Facade Pattern comes in.

What is the Facade Pattern?

The Facade Pattern provides a unified and simplified interface to a set of interfaces in a subsystem. It helps hide the complexities of the subsystem from the client and provides a higher-level interface that makes the subsystem easier to use.

It’s like having a remote control for your home theater — instead of turning on each device one by one, adjusting the settings, and starting the movie manually, you just press a single button.

Let’s bring this analogy to code.

Example: Home Theater System in Java

We’re going to simulate a simple home theater system using three components: an amplifier, a projector, and a DVD player. Then, we’ll create a facade that makes it easy to start and stop a movie night.

1. Subsystems – Complex Components

// Amplifier
public class Amplifier {
    public void on() {
        System.out.println("Amplifier turned on.");
    }

    public void off() {
        System.out.println("Amplifier turned off.");
    }

    public void setVolume(int level) {
        System.out.println("Volume set to " + level);
    }
}

// Projector
public class Projector {
    public void on() {
        System.out.println("Projector turned on.");
    }

    public void off() {
        System.out.println("Projector turned off.");
    }
}

// DVD Player
public class DvdPlayer {
    public void on() {
        System.out.println("DVD Player turned on.");
    }

    public void play(String movie) {
        System.out.println("Playing movie: " + movie);
    }

    public void off() {
        System.out.println("DVD Player turned off.");
    }
}

2. Facade Class – Simplifying the Interface

public class HomeTheaterFacade {
    private Amplifier amp;
    private Projector projector;
    private DvdPlayer dvd;

    public HomeTheaterFacade(Amplifier amp, Projector projector, DvdPlayer dvd) {
        this.amp = amp;
        this.projector = projector;
        this.dvd = dvd;
    }

    public void watchMovie(String movie) {
        System.out.println("Get ready to watch a movie...");
        amp.on();
        amp.setVolume(5);
        projector.on();
        dvd.on();
        dvd.play(movie);
    }

    public void endMovie() {
        System.out.println("Shutting down movie theater...");
        dvd.off();
        projector.off();
        amp.off();
    }
}

3. Client Code – Using the Facade

public class Main {
    public static void main(String[] args) {
        Amplifier amp = new Amplifier();
        Projector projector = new Projector();
        DvdPlayer dvd = new DvdPlayer();

        HomeTheaterFacade homeTheater = new HomeTheaterFacade(amp, projector, dvd);
        homeTheater.watchMovie("The Lord of the Rings");
        homeTheater.endMovie();
    }
}

Benefits of the Facade Pattern

Simplifies usage of complex systems
Encapsulates interactions between subsystems
Improves readability and usability for clients
Helps promote loose coupling

Conclusion

The Facade pattern is a great tool when you want to provide a cleaner API over a set of complex classes. In real-world applications, this might mean creating a simplified interface for a library, an SDK, or even wrapping legacy code.

Whenever you find yourself writing repeated setup/teardown code that spans multiple components, consider wrapping it in a Facade.

Let the client press one button and enjoy the show.

📍 Reference

Facade in Java

💻 Project Repository

Project Repository on Github

👋 Talk to me

Spring Boot with WebSocket

Matheus Bernardes Spilari — Mon, 09 Jun 2025 13:00:00 +0000

In this post, I’ll walk you through the backend of a real-time album-sharing application that I built using Spring Boot, WebSocket, and LocalStack.

This was a great opportunity to build a hands-on POC (proof of concept) that mimics how modern real-time apps interact, while keeping things affordable and dev-friendly.

Tech Stack Used

Java + Spring Boot: Backend framework to handle REST and WebSocket communication
- Spring Web(spring-boot-starter-web).
Spring WebSocket (STOMP): For real-time communication with the frontend
- WebSocket(spring-boot-starter-websocket).
S3 (via LocalStack): To store and retrieve uploaded images
- Spring Cloud AWS S3(spring-cloud-aws-starter-s3)
DynamoDB (via LocalStack): To persist album metadata
- Spring Cloud DynamoDB(spring-cloud-aws-starter-dynamodb)
LocalStack: A local AWS cloud emulator (explained in my other post)

To use Spring Cloud AWS follow these docs here

🎯 The Goal

Users can:

Upload images and create albums
Receive real-time updates when new albums are created
View all existing albums — including their images

The key part: everything happens in real time, powered by WebSocket using the STOMP protocol.

Configs

AWS Config file

First, let's write a AWS config file:

@Configuration
public class AwsServicesConfigs {

    private static final Logger logger = LoggerFactory.getLogger(AwsServicesConfigs.class);

    @Value("${spring.cloud.aws.credentials.access-key}")
    private String accessKey;

    @Value("${spring.cloud.aws.credentials.secret-key}")
    private String secretKey;

    @Value("${spring.cloud.aws.region.static}")
    private String region;

    @Value("${spring.cloud.aws.s3.endpoint}")
    private String cloudEndpoint;

    @Value("${spring.cloud.aws.s3.bucket-name}")
    private String bucketName;

    @Value("${spring.cloud.aws.dynamodb.table-name}")
    private String tableName;

    @Bean
    public S3Client s3Client() {

        return S3Client.builder()
                .endpointOverride(URI.create(cloudEndpoint))
                .region(Region.of(region))
                .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretKey)))
                .serviceConfiguration(S3Configuration.builder()
                        .pathStyleAccessEnabled(true) // Força compatibilidade de caminho
                        .build())
                .build();
    }

    @Bean
    public DynamoDbClient dynamoDbClient() {
        return DynamoDbClient.builder()
                .endpointOverride(URI.create(cloudEndpoint))
                .region(Region.of(region))
                .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretKey)))
                .build();
    }

    @Bean
    public DynamoDbEnhancedClient dynamoDbEnhancedClient(DynamoDbClient dynamoDbClient) {
        return DynamoDbEnhancedClient.builder()
                .dynamoDbClient(dynamoDbClient)
                .build();
    }

    @Bean
    public CommandLineRunner initializeAwsServices(S3Client s3Client, DynamoDbClient dynamoDbClient) {
        return args -> {
            createTableIfNotExists(dynamoDbClient);
            createBucketIfNotExists(s3Client);
        };
    }

    private void createBucketIfNotExists(S3Client s3Client) {
        logger.info("Trying to create a bucket on S3...");
        if (!doesBucketExist(s3Client)) {
            logger.info("Creating bucket with name: " + bucketName);
            s3Client.createBucket(CreateBucketRequest.builder().bucket(bucketName).build());
        } else {
            logger.info("Bucket " + bucketName + " already exists !");
        }
    }

    private boolean doesBucketExist(S3Client s3Client) {
        ListBucketsResponse listOfBuckets = s3Client.listBuckets();
        return listOfBuckets.buckets().stream().anyMatch(bucket -> bucket.name().equals(bucketName));
    }

    private void createTableIfNotExists(DynamoDbClient dynamoDbClient) {
        logger.info("Trying to create a table in DynamoDb...");
        if (!doesTableExist(dynamoDbClient)) {

            CreateTableRequest createTableRequest = CreateTableRequest.builder()
                    .tableName(tableName)
                    .keySchema(KeySchemaElement.builder()
                            .attributeName("album_id")
                            .keyType(KeyType.HASH)
                            .build())
                    .attributeDefinitions(AttributeDefinition.builder()
                            .attributeName("album_id")
                            .attributeType(ScalarAttributeType.S)
                            .build())
                    .billingMode(BillingMode.PAY_PER_REQUEST)
                    .build();
            logger.info("Creating a table with name: " + tableName + " in DynamoDb.");
            dynamoDbClient.createTable(createTableRequest);
        } else {
            logger.info("Table with name: " + tableName + " already exists.");
        }
    }

    private boolean doesTableExist(DynamoDbClient dynamoDbClient) {
        ListTablesResponse listOfTables = dynamoDbClient.listTables();

        return listOfTables.tableNames().stream().anyMatch(name -> name.equalsIgnoreCase(tableName));
    }
}

⚠️ Note: In this project, we are programmatically creating the AWS resources (S3 bucket and DynamoDB table) using the AWS SDK inside a Spring @Configuration class. This approach is totally fine for educational purposes, quick prototyping, or proof of concepts (POCs), especially when working with tools like LocalStack.

However, in a real-world production scenario, the most professional and maintainable way to provision AWS infrastructure is by using Infrastructure as Code (IaC) tools like Terraform. In an upcoming post, I’ll walk you through how to replace this manual setup with a proper Terraform configuration — giving you more control, versioning, and automation in your infrastructure deployment.

Cors Configs

Now, let's write the cors configuration:

package dev.MSpilari.webSocketBackend.configs;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class CorsConfigs {

    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {

            @Override
            public void addCorsMappings(CorsRegistry corsRegistry) {
                corsRegistry.addMapping("/**")
                        .allowedOrigins("http://localhost:5173")
                        .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
                        .allowedHeaders("*")
                        .allowCredentials(true);
            }
        };
    }
}

Code explanation

corsRegistry.addMapping("/**")

Applies this CORS configuration to all routes in your application (i.e., /**).

.allowedOrigins("http://localhost:5173")

Allows cross-origin requests only from http://localhost:5173, which is your front-end running on Vite during development.

⚠️ This value is hardcoded and not ideal for different environments (dev, staging, prod).

.allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")

Specifies which HTTP methods are allowed from cross-origin requests.

.allowedHeaders("*")

Allows all HTTP headers in cross-origin requests, including custom headers like Authorization.

.allowCredentials(true);

Enables cookies and authentication headers (like tokens) to be included in CORS requests.

WebSocket Config

import org.springframework.messaging.simp.config.MessageBrokerRegistry;
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic");
        config.setApplicationDestinationPrefixes("/app");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws").setAllowedOrigins("http://localhost:5173").withSockJS();
    }
}

Code explanation

`@EnableWebSocketMessageBroker`

Enables WebSocket message handling, backed by a message broker. It tells Spring that we want to use STOMP over WebSockets to send and receive messages.

`configureMessageBroker()`

config.enableSimpleBroker("/topic");

This enables a simple in-memory message broker and sets the destination prefix /topic. This is where the client can subscribe to receive messages.

For example, your front-end might subscribe to /topic/albums.

config.setApplicationDestinationPrefixes("/app");

This defines the prefix used for messages that are sent from the client to the server. When your front-end sends a message to /app/albums, it will be routed to a corresponding method in a Spring controller (like @MessageMapping("/albums")).

`registerStompEndpoints()`

registry.addEndpoint("/ws")

This exposes a WebSocket endpoint at /ws that clients will use to establish a connection with the backend.

.setAllowedOrigins("http://localhost:5173")

Allows cross-origin requests from your front-end (running on Vite at port 5173).

💡 As mentioned in the CORS section, it’s better to extract this into a configuration property for production environments.

.withSockJS();

Enables SockJS as a fallback option. SockJS allows the client to simulate a WebSocket connection using HTTP when WebSockets are not supported by the browser or blocked by a firewall.

Model with DynamoDB Mapping in Spring Boot

Here’s the full class:

package dev.MSpilari.webSocketBackend.models;

import java.util.List;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

@DynamoDbBean
public class Album {

    private String albumId;
    private String albumName;
    private List<String> picturesUrl;

    public Album() {
    }

    public Album(String albumId, String albumName, List<String> picturesUrl) {
        this.albumId = albumId;
        this.albumName = albumName;
        this.picturesUrl = picturesUrl;
    }

    @DynamoDbPartitionKey
    @DynamoDbAttribute("album_id")
    public String getAlbumId() {
        return albumId;
    }

    public void setAlbumId(String albumId) {
        this.albumId = albumId;
    }

    @DynamoDbAttribute("album_name")
    public String getAlbumName() {
        return albumName;
    }

    public void setAlbumName(String albumName) {
        this.albumName = albumName;
    }

    @DynamoDbAttribute("pictures_url")
    public List<String> getPicturesUrl() {
        return picturesUrl;
    }

    public void setPicturesUrl(List<String> picturesUrl) {
        this.picturesUrl = picturesUrl;
    }

    @Override
    public String toString() {
        return "Album [albumId=" + albumId + ", albumName=" + albumName + ", picturesUrl=" + picturesUrl + "]";
    }
}

🔖 Annotations Explained

`@DynamoDbBean`

Declares that this class can be used with DynamoDB Enhanced Client. It tells the SDK how to serialize and deserialize the object.

`@DynamoDbPartitionKey`

Specifies the primary key of the DynamoDB table. In this case, albumId is the partition key for the album data.

`@DynamoDbAttribute("album_id")`

Maps the Java field albumId to the DynamoDB attribute named "album_id". This is useful when your DynamoDB field names follow snake_case, while your Java fields use camelCase.

The same logic applies to:

albumName ➝ "album_name"
picturesUrl ➝ "pictures_url"

This mapping is super helpful for keeping your backend clean and idiomatic while remaining compatible with database naming conventions.

WebSocket Service Layer

In this part of our backend, we're using Spring’s WebSocket support to send data in real-time from the server to all connected clients. The class below is responsible for managing the real-time communication of our albums via WebSockets.

package dev.MSpilari.webSocketBackend.services;

import java.util.List;

import org.springframework.messaging.simp.SimpMessagingTemplate;
import org.springframework.stereotype.Service;

import dev.MSpilari.webSocketBackend.models.Album;
import dev.MSpilari.webSocketBackend.repositories.AlbumRepository;

@Service
public class AlbumWebSocketServices {

    private final SimpMessagingTemplate messagingTemplate;
    private final AlbumRepository albumRepository;

    public AlbumWebSocketServices(SimpMessagingTemplate messagingTemplate, AlbumRepository albumRepository) {
        this.albumRepository = albumRepository;
        this.messagingTemplate = messagingTemplate;
    }

    public void sendAllAlbumsToClients() {
        List<Album> allAlbums = albumRepository.getAllAlbums();
        messagingTemplate.convertAndSend("/topic/albums", allAlbums);
    }

    public void broadcastNewAlbum(Album album) {
        messagingTemplate.convertAndSend("/topic/albums", album);
    }
}

What This Class Does

This is a Spring @Service component that handles broadcasting data over WebSockets using SimpMessagingTemplate. It communicates with both the repository layer (to fetch album data) and the WebSocket broker (to send messages to clients).

Dependencies

private final SimpMessagingTemplate messagingTemplate;
private final AlbumRepository albumRepository;

SimpMessagingTemplate is a Spring utility for sending messages to WebSocket clients.
AlbumRepository is where we fetch album data from DynamoDB (or any data source backing our albums).

`sendAllAlbumsToClients()`

public void sendAllAlbumsToClients() {
    List<Album> allAlbums = albumRepository.getAllAlbums();
    messagingTemplate.convertAndSend("/topic/albums", allAlbums);
}

Fetches all albums from the repository.
Sends them to all clients subscribed to /topic/albums.

This is useful, for example, when a client connects and you want to immediately push all existing albums to them.

`broadcastNewAlbum(Album album)`

public void broadcastNewAlbum(Album album) {
    messagingTemplate.convertAndSend("/topic/albums", album);
}

Sends just one album to all clients.
Called when a new album is created and you want to broadcast it in real-time to all listeners.

Messaging Destination: `/topic/albums`

This matches what we defined in our WebSocketConfig class (/topic is the broker prefix).
Any client subscribed to this topic will receive the messages (e.g., your frontend with SockJS and STOMP).

WebSocket Controller

This controller acts as the entry point for WebSocket messages sent by the client. It's responsible for listening to incoming messages and delegating the logic to the appropriate service.

Let’s break down what this class does:

package dev.MSpilari.webSocketBackend.controllers;

import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.stereotype.Controller;

import dev.MSpilari.webSocketBackend.services.AlbumWebSocketServices;

@Controller
public class AlbumWebSocketController {

    private final AlbumWebSocketServices webSocketService;

    public AlbumWebSocketController(AlbumWebSocketServices webSocketService) {
        this.webSocketService = webSocketService;
    }

    @MessageMapping("/albums")
    public void handleGetAlbumsRequest() {
        webSocketService.sendAllAlbumsToClients();
    }
}

What Is This?

This is a Spring @Controller that specifically listens to WebSocket messages (not HTTP requests).

When a client sends a message to the destination /app/albums (based on the prefix defined in your WebSocket configuration), this controller receives it and triggers the appropriate action.

Dependencies

private final AlbumWebSocketServices webSocketService;

This is the service responsible for sending album data back to the WebSocket clients.
It was explained in detail in the previous post (AlbumWebSocketServices).

`@MessageMapping("/albums")`

This annotation works similarly to @PostMapping or @GetMapping in regular REST controllers — but it's used for WebSockets.

It maps to messages sent to /app/albums (because /app is the application prefix you defined in WebSocketConfig).
When the frontend sends a message to this route, the method handleGetAlbumsRequest() is invoked.

`handleGetAlbumsRequest()`

public void handleGetAlbumsRequest() {
    webSocketService.sendAllAlbumsToClients();
}

This method delegates the logic to the service layer.
It fetches all albums from the database and broadcasts them to every connected WebSocket client subscribed to /topic/albums.

Real-World Usage Flow

The frontend (e.g., a React app) sends a message to /app/albums — usually to request all existing albums.
This controller method is triggered.
It uses AlbumWebSocketServices to fetch and send all albums via WebSocket to /topic/albums.
Every client listening to /topic/albums receives the data in real time.

💡 Pro Tip

If you plan to expand this project, this is the perfect place to add more WebSocket endpoints, such as:

Creating an album via WebSocket.
Listening to album deletion events.
Handling private user notifications or activity streams.

Conclusion

This backend was built with scalability and modularity in mind. It’s ideal for:

Learning how WebSocket works in Spring Boot
Working with AWS services without real cloud dependencies
Experimenting with real-time systems

If you want a clean, full-stack example of WebSocket + AWS emulation, this backend setup is a solid foundation.

See the GitHub Repository of the code here.

📍 Reference

💻 Project Repository

Project Repository on Github

👋 Talk to me

Why I'm Using LocalStack in My Project (And Why You Might Want to Too)

Matheus Bernardes Spilari — Mon, 02 Jun 2025 13:00:00 +0000

TL;DR: I’m using LocalStack to emulate AWS services locally, mainly because I don’t want to wake up to a surprise credit card bill 😅 — but also because it's fast, easy to integrate with Docker, and helps me stay productive without needing real cloud resources.

💳 Let's Get Real — AWS Billing Is Scary

If you’ve ever added a real AWS key to a pet project and forgot to delete a bucket, or left something running overnight...

You know the fear. I didn’t want to risk seeing a three-digit charge on my card just for experimenting with S3 and DynamoDB.

And honestly, not everyone even has a credit card to begin with ,especially students or people just getting started.

That’s when I found LocalStack.

What is LocalStack?

LocalStack is a fully functional local AWS cloud emulator. It allows you to develop and test cloud applications entirely on your local machine, without connecting to actual AWS infrastructure.

Even with the free tier, you get access to several core AWS services locally, including:

S3
DynamoDB
Lambda
SNS / SQS
API Gateway

And a bunch more.

🤔 Why I Chose LocalStack

In my case, I’m building a POC(Proof of Concept) of a full-stack app (React + Spring Boot), with websockets, that stores albums and pictures using AWS-like services:

S3 for image storage
DynamoDB for metadata

I wanted to mimic an AWS-based architecture without actually connecting to AWS, because:

I don’t want unexpected billing
I’m still exploring how AWS services work
I wanted full control of my stack locally
I didn't want to put my card at risk
And yes... I really didn’t want to add a credit card to AWS just to test things 😅

🔍 Friendly Web UI to Monitor Services

Even on the free plan, LocalStack provides a very intuitive web interface where you can inspect your services. You can:

Check which buckets you've created in S3
Browse DynamoDB tables and data
See logs and API calls
Monitor services running

Beautiful UI from LocalStack

It’s like having your own local AWS Console — and it’s amazing for debugging and learning.

🐳 How I’m Using LocalStack with Docker Compose

Here’s how I set it up in my docker-compose.yml, located inside the /webSocketBackend directory:

services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack
    ports:
      - "4566:4566"
    environment:
      - SERVICES=s3,dynamodb
      - DEBUG=1
    volumes:
      - "localstack_data:/var/lib/localstack"

volumes:
  localstack_data:

Once it's running, I can start the backend and point my AWS SDK to http://localhost:4566. Everything behaves just like AWS — but it’s all running on my machine.

✅ Benefits of Using LocalStack (Even on the Free Plan)

1. No Credit Card Needed

You can build and test AWS-based apps with zero billing worries — perfect for students or devs without a card.

2. Safe Learning Environment

If you're just starting out with AWS, LocalStack is the perfect sandbox to learn S3, DynamoDB, and more without fear.

3. Blazing Fast Feedback Loop

No internet lag. No real deployments. Just run, test, fix — all locally.

4. Cloud-Like Testing for Free

You can simulate real AWS workflows and catch bugs before going to production.

5. Easy Integration with Docker

Thanks to Docker Compose, LocalStack fits right into your containerized workflow.

6. No Surprise Bills

Enough said 😂

Tips

Use the AWS CLI with --endpoint-url=http://localhost:4566 to manage your mock services.
Make sure your SDK is pointed to the same local endpoint.
Create your buckets/tables at startup via CLI, code, or scripts.

Conclusion

LocalStack gave me the confidence to build AWS-style applications without worrying about billing, credentials, or account limits. Whether you're experimenting, learning, or working in a team without AWS access — it just makes sense.

If you're cloud-curious but want to stay local for now, I can’t recommend LocalStack enough. Especially if you’re like me and still not ready to hand your credit card over to Jeff Bezos 😅

📍 Reference

💻 Project Repository

Project Repository on Github

👋 Talk to me

The Singleton Design Pattern

Matheus Bernardes Spilari — Mon, 26 May 2025 13:00:00 +0000

Have you ever been in a house with just one remote control for the TV? No matter who wants to change the channel or adjust the volume, everyone has to use that one single remote. That’s exactly the idea behind the Singleton Design Pattern.

Let’s explore this concept in the simplest way possible.

What is the Singleton Pattern?

The Singleton pattern makes sure that a class has only one instance, and it provides a global way to access it. Think of it like that single remote control in your living room — there's only one, and everyone shares it.

Real-Life Analogy: The Remote Control

Imagine you have a house with multiple family members. Instead of giving each person a different remote (which could get chaotic), you keep just one that everyone uses.

Why? Because having one remote:

Saves money (no need for 5 remotes),
Keeps things in sync (everyone controls the same device),
Avoids confusion.

This is exactly why we use the Singleton pattern in programming!

Java Code: The RemoteControl Singleton

Here’s how we can translate our single remote control into code:

public class RemoteControl {
    private static RemoteControl instance;

    // Private constructor – no one else can create it
    private RemoteControl() {
        System.out.println("Remote is ready to use.");
    }

    // Public method to get the only instance
    public static RemoteControl getInstance() {
        if (instance == null) {
            instance = new RemoteControl();
        }
        return instance;
    }

    public void pressButton(String button) {
        System.out.println("Button pressed: " + button);
    }
}

How to Use It

Now let’s see how this works in action:

public class LivingRoom {
    public static void main(String[] args) {
        RemoteControl myRemote = RemoteControl.getInstance();
        myRemote.pressButton("Power");

        RemoteControl momRemote = RemoteControl.getInstance();
        momRemote.pressButton("Volume Up");

        System.out.println(myRemote == momRemote);  // true – same remote!
    }
}

Even though two people (you and your mom) try to get a remote, they both get the same one. That’s the Singleton pattern at work.

Why Use Singleton?

Keeps things consistent
Saves resources, reduced memory footprint, especially when the object is heavy to instantiate.
Global access point, making it easy to access from anywhere in your code.

When to Be Careful

Singleton is like global state — if overused, it can make code harder to test and maintain
Not great if you need multiple versions of something (e.g., two different remotes for two TVs)
Multithreading issues, if not implemented carefully.
Can be abused, used where simpler solutions would suffice (like dependency injection).

Conclusion

Singleton isn’t just a fancy design pattern — it’s a practical way to manage shared things in your app, like settings, logging, or yes… your one-and-only TV remote.

📍 Reference

Singleton in Java

💻 Project Repository

Project Repository on Github

👋 Talk to me

What Does SOLID Mean?

Matheus Bernardes Spilari — Mon, 19 May 2025 13:00:00 +0000

If you've spent any time learning about clean code or software architecture, you've probably come across the SOLID principles. These five principles, introduced by Robert C. Martin (Uncle Bob), aim to make your code more maintainable, flexible, and scalable.

In this article, we’ll break down what each letter in SOLID stands for, and walk through simple examples of each one.

🧱 What is SOLID?

SOLID is an acronym for five object-oriented design principles:

S – Single Responsibility Principle
O – Open/Closed Principle
L – Liskov Substitution Principle
I – Interface Segregation Principle
D – Dependency Inversion Principle

1. ✅ Single Responsibility Principle (SRP)

A class should have only one reason to change.

Each class should do one thing, and do it well. If a class has more than one responsibility, it's harder to maintain and more likely to break when you make changes.

❌ Bad Example:

public class Invoice {
    public void calculateTotal() {
        // logic here
    }

    public void printInvoice() {
        // printing logic
    }

    public void saveToDatabase() {
        // database logic
    }
}

This class is doing too much: calculation, printing, and database access.

✅ Good Example:

public class InvoiceCalculator {
    public void calculateTotal(Invoice invoice) { /* ... */ }
}

public class InvoicePrinter {
    public void print(Invoice invoice) { /* ... */ }
}

public class InvoiceRepository {
    public void save(Invoice invoice) { /* ... */ }
}

🤔 Does SRP mean "one method per class"?

No — that’s a common misconception.

The Single Responsibility Principle does not mean that a class should only have one method. It means the class should have one reason to change — in other words, a clearly defined responsibility.

For example, in a Spring Boot application, it's completely normal (and correct!) for a controller to have multiple methods, like this:

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

    @GetMapping
    public List<User> listUsers() { /* ... */ }

    @PostMapping
    public User createUser(@RequestBody User user) { /* ... */ }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) { /* ... */ }
}

This controller has one responsibility: handling HTTP requests for the User resource.

Each method maps to a different route, but they all belong to the same context — user handling.

🚫 When SRP is broken:

If your controller also starts doing business logic, data validation, and database operations, then it starts to accumulate responsibilities:

public class UserController {
    // HTTP handling
    // + Business logic
    // + Validation
    // + Persistence
}

In that case, you'd want to refactor and delegate:

Business rules → Service layer
Validation → Validator
Persistence → Repository

So remember: SRP is about cohesive responsibility, not method count.

2. 🛑 Open/Closed Principle (OCP)

Software entities should be open for extension, but closed for modification.

You should be able to add new functionality without changing existing code.

❌ Bad Example:

public class DiscountService {
    public double getDiscount(String customerType) {
        if (customerType.equals("Regular")) return 0.1;
        else if (customerType.equals("Premium")) return 0.2;
        else return 0;
    }
}

If you need to support a new type of customer, you'll have to modify this method.

✅ Good Example (Using Strategy Pattern):

public interface DiscountStrategy {
    double getDiscount();
}

public class RegularCustomer implements DiscountStrategy {
    public double getDiscount() { return 0.1; }
}

public class PremiumCustomer implements DiscountStrategy {
    public double getDiscount() { return 0.2; }
}

public class DiscountService {
    public double calculateDiscount(DiscountStrategy strategy) {
        return strategy.getDiscount();
    }
}

You can now extend with new customer types without changing existing code.

Want to see a full example of the Strategy pattern in action? Check out this article where I break it down step by step.

3. 🧬 Liskov Substitution Principle (LSP)

Subtypes must be substitutable for their base types.

Objects of a superclass should be replaceable with objects of its subclasses without breaking the application.

❌ Bad Example:

public class Bird {
    public void fly() { /* flying logic */ }
}

public class Ostrich extends Bird {
    // can't fly, but inherits fly() anyway
}

Using Ostrich in a context that expects a flying bird will cause problems.

✅ Good Example:

public abstract class Bird { }

public interface FlyingBird {
    void fly();
}

public class Sparrow extends Bird implements FlyingBird {
    public void fly() { /* logic */ }
}

public class Ostrich extends Bird {
    // No fly() method
}

Now, we can substitute FlyingBird only where flying is expected.

4. 🪪 Interface Segregation Principle (ISP)

Clients should not be forced to depend on interfaces they do not use.

Split large interfaces into smaller, more specific ones.

❌ Bad Example:

public interface Worker {
    void work();
    void eat();
}

public class Robot implements Worker {
    public void work() { /* ok */ }
    public void eat() { /* meaningless */ }
}

A robot doesn’t eat — but it's forced to implement eat().

✅ Good Example:

public interface Workable {
    void work();
}

public interface Eatable {
    void eat();
}

public class Human implements Workable, Eatable {
    public void work() { /* ... */ }
    public void eat() { /* ... */ }
}

public class Robot implements Workable {
    public void work() { /* ... */ }
}

Each class only implements what it needs.

5. 🔄 Dependency Inversion Principle (DIP)

High-level modules should not depend on low-level modules. Both should depend on abstractions.

This encourages loosely coupled code.

❌ Bad Example:

public class MySQLDatabase {
    public void connect() { /* ... */ }
}

public class UserRepository {
    private MySQLDatabase db = new MySQLDatabase();

    public void saveUser(User user) {
        db.connect();
        // save logic
    }
}

The repository is tightly coupled to MySQL.

✅ Good Example:

public interface Database {
    void connect();
}

public class MySQLDatabase implements Database {
    public void connect() { /* ... */ }
}

public class UserRepository {
    private Database db;

    public UserRepository(Database db) {
        this.db = db;
    }

    public void saveUser(User user) {
        db.connect();
        // save logic
    }
}

Now you can inject any Database implementation — perfect for testing and flexibility.

This principle can be a bit tricky to grasp at first. If you want a deeper, more practical explanation of Dependency Inversion with Spring Boot/Java examples, I wrote a full article about it here.

Conclusion

The SOLID principles are essential for writing clean, maintainable, and scalable object-oriented code. While they may seem abstract at first, practicing them over time leads to better architecture and fewer headaches as your project grows.

📍 Reference

SOLID Principles

👋 Talk to me

Asynchronous File Upload in Java with Spring

Matheus Bernardes Spilari — Mon, 12 May 2025 13:00:00 +0000

Uploading files to cloud storage like AWS S3 is a common task in modern applications. At first, you might handle this in a simple, synchronous way: one file at a time, blocking the thread. But this approach doesn't scale well.

In this post, we'll explore how to use asynchronous uploads in Java with Spring Boot, why it's a better approach, the trade-offs you need to be aware of, and how to make it more resilient using Resilience4j with retry and exponential backoff.

🐢 The Problem with Synchronous Uploads

Let’s start with a basic implementation using a for loop:

for (MultipartFile file : files) {
    uploadToS3(file);
}

This is easy to write, but uploads are sequential and slow — especially if you're uploading many files or large ones. Every file waits for the previous one to finish.

This leads to:

Higher latency
Poor user experience
Underutilization of server resources

⚡ The Power of Asynchronous Uploads

By uploading files concurrently, we let multiple files be uploaded at the same time, without blocking the main thread. This is especially useful when:

Uploading to remote services like S3 (network-bound operations)
Handling multiple large files
Reducing total execution time

Benefits of Asynchronous Uploads

🔄 Parallel execution: Uploads happen simultaneously, drastically reducing total upload time.
🧵 Non-blocking: Frees up the main thread for other tasks.
🚀 Scalability: Ideal for handling large batches of uploads.

✅ Using `CompletableFuture` for Concurrent Uploads

Java’s CompletableFuture combined with a custom ExecutorService provides a clean and scalable way to handle concurrent tasks.

Here’s a simple implementation:

import java.util.concurrent.*;
import java.util.stream.Collectors;

@Service
public class S3UploadService {

    private final ExecutorService executor = Executors.newFixedThreadPool(5); // Adjust pool size as needed

    public void uploadMultipleFiles(List<MultipartFile> files) {
        List<CompletableFuture<Void>> futures = files.stream()
            .map(file -> CompletableFuture.runAsync(() -> uploadToS3(file), executor))
            .collect(Collectors.toList());

        // Wait for all uploads to complete
        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
    }

    private void uploadToS3(MultipartFile file) {
        // Perform actual upload logic using S3Client
        System.out.println("Uploading: " + file.getOriginalFilename());
    }
}

🛠️ Optional: Use Spring’s `@Async`

For even cleaner integration, Spring allows asynchronous methods via the @Async annotation.

@Async
public CompletableFuture<Void> uploadAsync(MultipartFile file) {
    uploadToS3(file);
    return CompletableFuture.completedFuture(null);
}

Just remember to enable async in your config:

@EnableAsync
@Configuration
public class AsyncConfig {}

🔁 Making It Robust: Retry with Backoff

To handle temporary failures (like network hiccups or AWS rate limits), you can implement retry logic with exponential backoff — increasing the delay between attempts to avoid overwhelming the service.

A better way to manage this in Spring Boot is using Resilience4j.

✳️ Add Resilience4j to your `pom.xml`

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
</dependency>

⚙️ Configure Retry with Backoff in `application.yml`

resilience4j.retry:
  instances:
    uploadRetry:
      max-attempts: 3
      wait-duration: 2s
      exponential-backoff:
        enabled: true
        multiplier: 2

🧩 Create a Service with Resilience Retry

import io.github.resilience4j.retry.annotation.Retry;
import org.springframework.stereotype.Service;

@Service
public class UploadService {

    @Retry(name = "uploadRetry")
    public void uploadToS3(MultipartFile file) {
        // Your upload logic here
        System.out.println("Uploading: " + file.getOriginalFilename());
        // Simulate error for testing
        if (Math.random() < 0.2) {
            throw new RuntimeException("Simulated failure");
        }
    }
}

🧵 Use it Asynchronously

@Autowired
private UploadService uploadService;

@PostMapping("/upload")
public ResponseEntity<?> upload(@RequestParam("files") List<MultipartFile> files) {
    ExecutorService executor = Executors.newFixedThreadPool(5);

    List<CompletableFuture<Void>> futures = files.stream()
        .map(file -> CompletableFuture.runAsync(() -> uploadService.uploadToS3(file), executor))
        .toList();

    CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
    executor.shutdown();

    return ResponseEntity.ok("Upload complete!");
}

🤔 Why Is This Better?

Feature	Synchronous (`for`)	Asynchronous (`CompletableFuture`)
Total Time	Longer	Significantly faster
Resource Utilization	Low	High (more parallelism)
User Experience	Laggy	Responsive and smooth
Code Flexibility	Limited	Easy to scale and customize

⚠️ The Risks of Concurrency

Although we're using concurrency to speed up uploads by executing tasks independently, it's important to note that concurrency isn't the same as parallelism. While concurrency deals with managing multiple tasks at once, parallelism actually runs them simultaneously. Depending on your thread pool and hardware, concurrent uploads may or may not run in parallel — but the risks are similar either way.

Too many threads: Uploading dozens of files at once can create too many concurrent threads, exhausting system resources.
Race conditions: If files depend on each other, concurrent execution might break the logic.
Error handling is harder: One failure might go unnoticed unless you're careful.
Network or API throttling: AWS S3 has rate limits. Uploading too much, too fast, may lead to SlowDown or 503 errors.

💡 Bonus Tip

If you're planning to run this setup locally with services like LocalStack, and eventually move to the cloud with Terraform, remember:

Creating AWS resources programmatically (like buckets or tables) is fine for learning. In real-world apps, you should use Infrastructure as Code (IaC) tools like Terraform to provision your cloud resources, and just connect your application to them.

🧠 Final Thoughts

Asynchronous uploads are a powerful technique for improving performance and scalability, especially when dealing with cloud services. However, with this power comes the need for proper error handling, resource management, and backoff strategies to avoid overwhelming your system or external APIs.

Using Resilience4j for retry logic makes your code cleaner, more maintainable, and production-ready.

📍 Reference

💻 Project Repository

Project Repository on Github

👋 Talk to me

Logging in Spring Boot with SL4J

Matheus Bernardes Spilari — Mon, 05 May 2025 13:00:00 +0000

Logging is a fundamental part of software development that provides insights into an application's behavior, making debugging and monitoring easier. A well-structured logging system helps developers understand how an application is running, identify issues, and optimize performance.

Why Are Logs Important?

Logs serve several critical purposes, including:

Debugging & Troubleshooting: Logs help track down issues, especially in production environments where debugging directly is not feasible.
Monitoring & Observability: Logs allow teams to monitor application health and detect anomalies.
Security Auditing: Logs keep records of critical events, such as user authentication attempts and database queries, which are essential for security audits.
Performance Optimization: By analyzing logs, developers can detect performance bottlenecks and improve application efficiency.

Logging Levels Explained

Logs are categorized into different levels, allowing developers to filter and manage the verbosity of log messages. The main logging levels are:

TRACE: The most detailed level, used for fine-grained debugging and tracking execution flow.
DEBUG: Less verbose than TRACE, but still provides detailed information useful for debugging.
INFO: General application flow messages, such as startup, shutdown, or important milestones.
WARN: Warnings about potential issues that do not disrupt application functionality.
ERROR: Critical problems that might affect the application’s behavior.

Example: Using Logs in AWS Service Configuration

Consider the following Spring Boot configuration for AWS services, where logging can enhance visibility and traceability.

package dev.MSpilari.webSocketBackend.configs;

import java.net.URI;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition;
import software.amazon.awssdk.services.dynamodb.model.BillingMode;
import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest;
import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement;
import software.amazon.awssdk.services.dynamodb.model.KeyType;
import software.amazon.awssdk.services.dynamodb.model.ListTablesResponse;
import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;

@Configuration
public class AwsServicesConfigs {

    private static final Logger logger = LoggerFactory.getLogger(AwsServicesConfigs.class);

    @Value("${spring.cloud.aws.credentials.access-key}")
    private String accessKey;

    @Value("${spring.cloud.aws.credentials.secret-key}")
    private String secretKey;

    @Value("${spring.cloud.aws.region.static}")
    private String region;

    @Value("${spring.cloud.aws.s3.endpoint}")
    private String cloudEndpoint;

    @Value("${spring.cloud.aws.s3.bucket-name}")
    private String bucketName;

    @Value("${spring.cloud.aws.dynamodb.table-name}")
    private String tableName;

    @Bean
    public S3Client s3Client() {

        return S3Client.builder()
                .endpointOverride(URI.create(cloudEndpoint))
                .region(Region.of(region))
                .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretKey)))
                .serviceConfiguration(S3Configuration.builder()
                        .pathStyleAccessEnabled(true) // Força compatibilidade de caminho
                        .build())
                .build();
    }

    @Bean
    public DynamoDbClient dynamoDbClient() {
        return DynamoDbClient.builder()
                .endpointOverride(URI.create(cloudEndpoint))
                .region(Region.of(region))
                .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretKey)))
                .build();
    }

    @Bean
    public DynamoDbEnhancedClient dynamoDbEnhancedClient(DynamoDbClient dynamoDbClient) {
        return DynamoDbEnhancedClient.builder()
                .dynamoDbClient(dynamoDbClient)
                .build();
    }

    @Bean
    public CommandLineRunner initializeAwsServices(S3Client s3Client, DynamoDbClient dynamoDbClient) {
        return args -> {
            createTableIfNotExists(dynamoDbClient);
            createBucketIfNotExists(s3Client);
        };
    }

    private void createBucketIfNotExists(S3Client s3Client) {
        logger.info("Trying to create a bucket on S3...");
        if (!doesBucketExist(s3Client)) {
            logger.info("Creating bucket with name: " + bucketName);
            s3Client.createBucket(CreateBucketRequest.builder().bucket(bucketName).build());
        } else {
            logger.info("Bucket " + bucketName + " already exists !");
        }
    }

    private boolean doesBucketExist(S3Client s3Client) {
        ListBucketsResponse listOfBuckets = s3Client.listBuckets();
        return listOfBuckets.buckets().stream().anyMatch(bucket -> bucket.name().equals(bucketName));
    }

    private void createTableIfNotExists(DynamoDbClient dynamoDbClient) {
        logger.info("Trying to create a table in DynamoDb...");
        if (!doesTableExist(dynamoDbClient)) {

            CreateTableRequest createTableRequest = CreateTableRequest.builder()
                    .tableName(tableName)
                    .keySchema(KeySchemaElement.builder()
                            .attributeName("album_id")
                            .keyType(KeyType.HASH)
                            .build())
                    .attributeDefinitions(AttributeDefinition.builder()
                            .attributeName("album_id")
                            .attributeType(ScalarAttributeType.S)
                            .build())
                    .billingMode(BillingMode.PAY_PER_REQUEST)
                    .build();
            logger.info("Creating a table with name: " + tableName + " in DynamoDb.");
            dynamoDbClient.createTable(createTableRequest);
        } else {
            logger.info("Table with name: " + tableName + " already exists.");
        }
    }

    private boolean doesTableExist(DynamoDbClient dynamoDbClient) {
        ListTablesResponse listOfTables = dynamoDbClient.listTables();

        return listOfTables.tableNames().stream().anyMatch(name -> name.equalsIgnoreCase(tableName));
    }
}

⚠️ Important Note on Resource Initialization

The creation of S3 buckets and DynamoDB tables within the application code, as shown in the AWS configuration example above, is done purely for educational purposes. The goal is to help developers understand how to interact with AWS services programmatically using the AWS SDK in a Spring Boot environment.

However, in a production-grade application, this approach is not recommended. A more robust and scalable solution would involve provisioning these resources using Infrastructure as Code (IaC) tools such as Terraform, AWS CloudFormation, or Pulumi. These tools allow for repeatable, version-controlled, and environment-specific infrastructure setups.

In such setups, your Spring Boot application should assume that the required resources (e.g., buckets and tables) already exist, and focus solely on connecting to and interacting with them via configuration.

This separation of concerns, where infrastructure is handled by IaC and application logic by Spring, improves maintainability, security, and clarity across teams and deployment pipelines.

Best Practices for Logging

Use appropriate logging levels: Avoid using DEBUG or TRACE logs in production environments.
Structure log messages: Make logs clear and meaningful, including relevant context.
Avoid logging sensitive data: Never log passwords, API keys, or personal user information.
Enable centralized logging: Use tools like AWS CloudWatch, ELK Stack, or Prometheus for better observability.
Monitor logs regularly: Logging is only useful if logs are actively monitored and analyzed.

Conclusion

Logging is an essential part of any application, helping developers debug, monitor, and optimize performance. Using SLF4J with structured logging practices ensures that logs remain useful and manageable. By implementing logs in AWS service configurations, like the example above, developers can improve observability and system reliability.

📍 Reference

SL4J Docs

💻 Project Repository

Project Repository on Github

👋 Talk to me

Observer Design Pattern in Java

Matheus Bernardes Spilari — Mon, 28 Apr 2025 13:00:00 +0000

The Observer design pattern is a behavioral pattern that defines a one-to-many dependency between objects. When one object (the subject) changes state, all its dependent objects (observers) are notified and updated automatically. This pattern is widely used in event-driven programming and is particularly useful in designing loosely coupled systems.

Real-World Analogy

Imagine a YouTube channel. When a user subscribes to a channel, they become an observer. When the channel uploads a new video, all subscribers get notified. The channel is the subject, and the subscribers are observers.

Implementing Observer Pattern in Java

Java provides built-in support for the Observer pattern through the java.util.Observer interface and java.util.Observable class (deprecated in Java 9). However, it is common to implement the pattern manually to gain more flexibility.

Step 1: Define the Observer Interface

interface Observer {
    void update(String message);
}

Each observer needs to implement this interface and define what happens when they receive an update.

Step 2: Create the Subject (Observable) Interface

import java.util.ArrayList;
import java.util.List;

interface Subject {
    void addObserver(Observer observer);
    void removeObserver(Observer observer);
    void notifyObservers(String message);
}

The Subject interface maintains a list of observers and provides methods to add, remove, and notify observers.

Step 3: Implement the Concrete Subject

class YouTubeChannel implements Subject {
    private List<Observer> observers = new ArrayList<>();
    private String channelName;

    public YouTubeChannel(String channelName) {
        this.channelName = channelName;
    }

    @Override
    public void addObserver(Observer observer) {
        observers.add(observer);
    }

    @Override
    public void removeObserver(Observer observer) {
        observers.remove(observer);
    }

    @Override
    public void notifyObservers(String message) {
        for (Observer observer : observers) {
            observer.update("New video from " + channelName + ": " + message);
        }
    }

    public void uploadVideo(String title) {
        System.out.println(channelName + " uploaded a new video: " + title);
        notifyObservers(title);
    }
}

Step 4: Implement the Concrete Observers

class Subscriber implements Observer {
    private String name;

    public Subscriber(String name) {
        this.name = name;
    }

    @Override
    public void update(String message) {
        System.out.println(name + " received notification: " + message);
    }
}

Step 5: Test the Implementation

public class ObserverPatternDemo {
    public static void main(String[] args) {
        YouTubeChannel channel = new YouTubeChannel("Tech Explained");

        Observer subscriber1 = new Subscriber("Alice");
        Observer subscriber2 = new Subscriber("Bob");

        channel.addObserver(subscriber1);
        channel.addObserver(subscriber2);

        channel.uploadVideo("Observer Pattern in Java");

        channel.removeObserver(subscriber1);

        channel.uploadVideo("Singleton Pattern in Java");
    }
}

Expected Output

Tech Explained uploaded a new video: Observer Pattern in Java
Alice received notification: New video from Tech Explained: Observer Pattern in Java
Bob received notification: New video from Tech Explained: Observer Pattern in Java
Tech Explained uploaded a new video: Singleton Pattern in Java
Bob received notification: New video from Tech Explained: Singleton Pattern in Java

Conclusion

The Observer pattern is a powerful tool for designing decoupled and maintainable code. It is commonly used in event-driven programming, GUI applications, and distributed systems. By following this pattern, you can build scalable and flexible systems where objects communicate without tight dependencies.