Skip to content

spring-boot-java17-mysql

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

spring-boot-java17-mysql

README.md

Spring Boot with OpenTelemetry

Spring Boot 3.5.9 application with OpenTelemetry auto-instrumentation for traces, metrics, and logs.

📚 Full Documentation

What's Instrumented

  • HTTP requests and responses
  • Database queries (JDBC/JPA) and connection pool
  • JVM metrics (memory, threads, GC)
  • Distributed trace propagation (W3C)
  • Custom business metrics via Micrometer

Prerequisites

  • Docker Desktop or Docker Engine with Compose
  • Base14 Scout credentials (setup guide)
  • Java 17+ (only for local development without Docker)

Quick Start

# Clone and navigate
git clone https://github.com/base-14/examples.git
cd examples/java/spring-boot-java17-mysql

# Set Base14 Scout credentials as environment variables
export SCOUT_ENDPOINT=https://your-tenant.base14.io/v1/traces
export SCOUT_CLIENT_ID=your_client_id
export SCOUT_CLIENT_SECRET=your_client_secret
export SCOUT_TOKEN_URL=https://your-tenant.base14.io/oauth/token

# Start application (MySQL + Spring Boot + OTel Collector)
docker-compose up --build -d

# Verify it's running
curl http://localhost:8080/actuator/health
curl http://localhost:8080/users/testMessage

The app runs on port 8080, MySQL on 3306, OTel Collector on 4317/4318.

Configuration

Required Environment Variables

The OpenTelemetry Collector requires Base14 Scout credentials to export telemetry data. Set these before running docker-compose up:

Variable Required Description
SCOUT_ENDPOINT Yes Base14 Scout OTLP endpoint
SCOUT_CLIENT_ID Yes OAuth2 client ID from Base14 Scout
SCOUT_CLIENT_SECRET Yes OAuth2 client secret from Base14 Scout
SCOUT_TOKEN_URL Yes OAuth2 token endpoint

Example:

export SCOUT_ENDPOINT=https://your-tenant.base14.io/v1/traces
export SCOUT_CLIENT_ID=your_client_id
export SCOUT_CLIENT_SECRET=your_client_secret
export SCOUT_TOKEN_URL=https://your-tenant.base14.io/oauth/token

See the Base14 Collector Setup Guide for obtaining credentials.

Application Environment Variables (compose.yaml)

Variable Default
SPRING_APPLICATION_NAME java-spring-boot-otel
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT http://otel-collector:4318

Resource Attributes

Automatically included in telemetry:

service.name=java-spring-boot-otel
service.namespace=base14
service.version=0.0.1-SNAPSHOT
deployment.environment=dev

API Endpoints

Application Endpoints

Method Endpoint Description
GET /users/ List all users
POST /users/saveUser Create user
PUT /users/{id} Update user
DELETE /users/{id} Delete user
GET /users/testMessage Test endpoint 
# Create user
curl -X POST http://localhost:8080/users/saveUser \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","address":"123 Main St"}'

# List users
curl http://localhost:8080/users/

Actuator Endpoints

Endpoint Purpose
/actuator/health Health status
/actuator/metrics Metrics list
/actuator/prometheus Prometheus format

Development

Run Locally (without Docker)

Requires MySQL and OTel Collector running locally on standard ports.

./gradlew bootRun      # Run application
./gradlew test         # Run tests
./gradlew build        # Build JAR

Update application.properties to use localhost:3306 for MySQL.

Docker Commands

docker-compose up --build        # Build and start
docker-compose down              # Stop all
docker-compose down -v           # Stop and remove volumes
docker logs spring-app -f        # View logs
docker-compose restart spring-service  # Restart app only

Faster Development Loop

Run only MySQL in Docker, app locally for quick iteration:

docker-compose up db -d    # Start MySQL only
./gradlew bootRun          # Run app locally

Telemetry Data

Traces

  • HTTP requests (method, URL, status)
  • Database queries (SQL statements)
  • Exceptions and stack traces

Metrics

  • HTTP: Request count, duration, errors
  • JVM: Memory, GC, threads
  • Database: Connection pool, query duration
  • Process: CPU, file descriptors

Logs

All logs include trace_id and span_id for correlation.

Troubleshooting

Collector connection failed

docker ps | grep otel-collector  # Check collector is running
docker logs otel-collector       # View collector logs

Use host.docker.internal not localhost when running app in Docker.

No telemetry data

docker logs spring-app | grep -i otel  # Check app logs

Verify collector config exports to the correct backend.

Database connection failed

docker-compose ps           # Check MySQL health
docker logs mysql-db        # View MySQL logs

Wait for MySQL healthcheck to complete before starting the app.

Enable debug logging

In compose.yaml:

environment:
  OTEL_LOG_LEVEL: DEBUG

Or application.properties:

logging.level.io.opentelemetry=DEBUG

Technology Stack

Component Version
Spring Boot 3.5.9
OpenTelemetry Instrumentation 2.23.0
OpenTelemetry SDK 1.55.0
MySQL 9.1
Gradle 9.2.1
Java 17 (target) / 17-25 (supported)

Resources