Java / Spring Boot Integration Guide

Overview

This guide explains how to integrate the AmpliServ Backend SDK with your Spring Boot application. The integration enables JSON logging, correlation ID propagation, and automatic log collection.

Prerequisites

• Java 11 or higher
• Spring Boot 2.x or 3.x
• Maven or Gradle
• AmpliServ SDK binary

Step 1: Add Dependencies

Maven (pom.xml)

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- JSON Logging - Required for AmpliServ SDK -->
    <dependency>
        <groupId>net.logstash.logback</groupId>
        <artifactId>logstash-logback-encoder</artifactId>
        <version>7.4</version>
    </dependency>
    
    <!-- For Correlation ID (Optional but Recommended) -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
    </dependency>
</dependencies>

Gradle (build.gradle)

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'net.logstash.logback:logstash-logback-encoder:7.4'
}

Step 2: Configure JSON Logging

Create src/main/resources/logback-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- JSON appender for AmpliServ SDK -->
    <appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>./app.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>app.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <includeMdc>true</includeMdc>
            <includeCallerData>true</includeCallerData>
        </encoder>
    </appender>

    <!-- Console appender for debugging -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="JSON_FILE"/>
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

Step 3: Configure application.yml

spring:
  application:
    name: your-springboot-app

server:
  port: 8080

logging:
  file:
    name: ./app.log
  level:
    root: INFO
    com.yourcompany: DEBUG

Step 4: Add Correlation ID Filter (Optional)

Create src/main/java/com/yourcompany/filter/CorrelationIdFilter.java:

package com.yourcompany.filter;

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.util.UUID;

@Component
@Order(1)
public class CorrelationIdFilter implements Filter {
    
    private static final String CORRELATION_ID_HEADER = "X-Correlation-ID";
    private static final String CORRELATION_ID_MDC = "correlation_id";
    
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        
        String correlationId = httpRequest.getHeader(CORRELATION_ID_HEADER);
        if (correlationId == null || correlationId.isEmpty()) {
            correlationId = UUID.randomUUID().toString();
        }
        
        MDC.put(CORRELATION_ID_MDC, correlationId);
        
        if (response instanceof HttpServletResponse httpResponse) {
            httpResponse.setHeader(CORRELATION_ID_HEADER, correlationId);
        }
        
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

Step 5: Add Global Exception Handler

Create src/main/java/com/yourcompany/exception/GlobalExceptionHandler.java:

package com.yourcompany.exception;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handleAllExceptions(Exception ex) {
        // Full stack trace will be captured here
        logger.error("Exception occurred: {}", ex.getMessage(), ex);
        
        Map<String, Object> response = new HashMap<>();
        response.put("timestamp", LocalDateTime.now());
        response.put("message", ex.getMessage());
        response.put("status", HttpStatus.INTERNAL_SERVER_ERROR.value());
        
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
    }
}

Step 6: Add Test Endpoint (Optional)

Create src/main/java/com/yourcompany/controller/TestController.java:

package com.yourcompany.controller;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/test")
public class TestController {
    
    private static final Logger logger = LoggerFactory.getLogger(TestController.class);
    
    @GetMapping("/error")
    public ResponseEntity<Map<String, Object>> testError() {
        logger.info("Test error endpoint called");
        
        try {
            simulateDeepError();
        } catch (Exception e) {
            logger.error("Test error occurred: {}", e.getMessage(), e);
            return ResponseEntity.status(500).body(Map.of("message", "Error triggered"));
        }
        
        return ResponseEntity.ok(Map.of("message", "No error"));
    }
    
    private void simulateDeepError() {
        throw new RuntimeException("This is a test error with deep stack trace!");
    }
}

Step 7: Configure AmpliServ SDK

Create run-agent.bat (Windows) or run-agent.sh (Linux/Mac):

#!/bin/bash
export AMPLISERV_API_KEY="your-api-key-here"
export AMPLISERV_COLLECTOR_MODE="file"
export AMPLISERV_ENDPOINT="http://dev-backend.ampliserv.com/api/ingestion/v1/ingest"
export AMPLISERV_SERVICE_NAME="ingestion-service"
export AMPLISERV_ENV="development"
export AMPLISERV_LOG_PATH="./app.log"
export AMPLISERV_BATCH_SIZE="50"
export AMPLISERV_FLUSH_INTERVAL_SEC="5"
export AMPLISERV_INCIDENT_ENABLED="true"

./ampliserv-agent

Step 8: Run the Integration

Terminal 1: Start Spring Boot Application

mvn spring-boot:run
# OR
java -jar target/your-app.jar

Terminal 2: Start AmpliServ SDK

chmod +x run-agent.sh
./run-agent.sh

Terminal 3: Test the Integration

# Test normal endpoint
curl http://localhost:8080/api/test/info

# Test error endpoint (generates stack trace)
curl http://localhost:8080/api/test/error

Sample JSON Log Output

{
  "@timestamp": "2026-03-23T10:30:45.123+05:30",
  "message": "Test error occurred: This is a test error with deep stack trace!",
  "logger_name": "com.yourcompany.controller.TestController",
  "level": "ERROR",
  "correlation_id": "a1270278-7ef9-4e59-803e-e9862c257d73",
  "stack_trace": "java.lang.RuntimeException: This is a test error...\n\tat com.yourcompany.controller.TestController.simulateDeepError(TestController.java:45)\n\t..."
}

Verification Checklist

• Spring Boot starts without errors
• app.log file is created with JSON content
• AmpliServ SDK shows "Starting AmpliServ Agent"
• SDK displays "Mode: file"
• Test endpoint logs appear in SDK terminal
• Stack traces are visible in logs

Common Issues

Issue	Solution
Log file not created	Check write permissions in application directory
JSON parsing errors	Ensure logback-spring.xml uses LogstashEncoder
SDK can't read file	Run SDK with same user as Spring Boot
Correlation ID missing	Verify CorrelationIdFilter is registered

Next Steps

• Configure production deployment
• Set up alerting on incidents
• Create custom dashboards