Java API with OpenTelemetry SDK

Table of Contents

• Introduction
• Architecture
  • Components
  • Data Flow
• Project Structure
• Prerequisites
• Installation
• Usage
  • Running the API
  • API Endpoints
• Components in Detail
  • Spring Boot API
  • OpenTelemetry SDK
  • H2 Database
  • Swagger Documentation
• Configurations
  • Application Properties
• Troubleshooting
• Contribution
• License

Introduction

Java API with OpenTelemetry SDK is a complete REST API built with Spring Boot that demonstrates a production-ready implementation of the OpenTelemetry SDK for observability. This project provides a robust foundation for developing microservices with built-in telemetry capabilities, allowing seamless integration with modern observability platforms.

The API includes full CRUD operations for user management, follows a layered architecture pattern (Controller-Service-Repository), and uses JPA/Hibernate for persistence with an in-memory H2 database. The OpenTelemetry integration provides automatic instrumentation for metrics, traces, and logs.

Architecture

Components

The application consists of the following main components:

• Spring Boot API: REST API with CRUD operations
• OpenTelemetry SDK: For collecting and exporting telemetry data
• H2 Database: In-memory database for persistence
• Swagger UI: API documentation and testing interface

Data Flow

┌─────────────┐      ┌─────────────────┐      ┌──────────────────┐
│ HTTP Client │──────▶ Spring Boot API │──────▶ Business Services │
└─────────────┘      └────────┬────────┘      └─────────┬────────┘
                             │                          │
                             │                          │
                    ┌────────▼────────┐      ┌──────────▼────────┐
                    │  OpenTelemetry  │      │   H2 Database     │
                    │      SDK        │      │                   │
                    └────────┬────────┘      └───────────────────┘
                             │
                             │
                    ┌────────▼────────┐
                    │ Telemetry Data  │
                    │ (OTLP Format)   │
                    └────────┬────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │ Observability Backend │
                  │ (Collector, Jaeger,   │
                  │  Prometheus, etc.)    │
                  └──────────────────────┘

Project Structure

java-api-with-otlp-sdk/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           ├── controller/        # REST API controllers
│   │   │           │   └── HealthController.java
│   │   │           ├── service/           # Business logic services
│   │   │           ├── repository/        # Data access layer
│   │   │           ├── model/             # Domain entities
│   │   │           ├── config/            # Application configs
│   │   │           └── Application.java   # Main application class
│   │   └── resources/
│   │       ├── application.properties     # App configuration
│   └── test/                              # Unit and integration tests
├── pom.xml                                # Maven dependencies
├── Dockerfile                             # Container definition
└── README.md                              # Project documentation

Prerequisites

To run this project, you need:

• JDK 17 or higher
• Maven 3.6 or higher
• OpenTelemetry Collector (optional, for exporting telemetry data)
• Docker (optional, for containerization)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/java-api-with-otlp-sdk.git
   cd java-api-with-otlp-sdk

2. Build the project with Maven:

   mvn clean package

3. (Optional) Build Docker container:

   docker build -t java-api-with-otlp:latest .

Usage

Running the API

Run the application locally:

mvn spring-boot:run

Or using the JAR file:

java -jar target/java-api-with-otlp-sdk-1.0.0.jar

With Docker:

docker run -p 8080:8080 java-api-with-otlp:latest

API Endpoints

Once the application is running, you can access:

• API Base URL: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui.html
• Health Check: http://localhost:8080/health

Main endpoints include:

• GET /users - List all users
• GET /users/{id} - Get user by ID
• POST /users - Create new user
• PUT /users/{id} - Update existing user
• DELETE /users/{id} - Delete user

Components in Detail

Spring Boot API

The API is built using Spring Boot 3.1.0 with the following features:

• RESTful endpoints with proper HTTP status codes
• Controller-Service-Repository architecture
• Custom exception handling with appropriate error responses
• Request validation
• Pagination and sorting capabilities

OpenTelemetry SDK

The application uses OpenTelemetry Java SDK for:

• Automatic Instrumentation: Traces HTTP requests, database queries, and internal method calls
• Manual Instrumentation: Custom spans for business logic
• Metrics Collection: JVM metrics, API endpoint metrics, and custom business metrics
• Context Propagation: Maintains trace context across asynchronous boundaries
• Attribute Enrichment: Adds metadata to spans for better analysis

H2 Database

An in-memory H2 database is used for data persistence:

• Auto-configured by Spring Boot
• Console available at http://localhost:8080/h2-console
• Default credentials: username="sa", password="" (empty)
• JDBC URL: jdbc:h2:mem:testdb

Swagger Documentation

The API is documented using SpringDoc OpenAPI:

• Interactive API documentation
• Try-out functionality for all endpoints
• Model schema definitions
• Authentication documentation

Configurations

Application Properties

Key application properties (application.properties):

# Server configuration
server.port=8080

# H2 Database
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.h2.console.enabled=true

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

Troubleshooting

Common Issues and Solutions

1. Application fails to start:

   • Verify Java version (java -version)
   • Check the application logs for specific error messages
   • Ensure required ports are available (8080 for API)

2. Database connection issues:

   • Check H2 console for database state
   • Verify entity mappings and relationships
   • Review JPA configuration properties

Contribution

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

Please ensure your code follows the existing code style and includes appropriate tests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Developed with ❤️ to demonstrate Spring Boot and OpenTelemetry integration.