Enable Spring Boot Actuator

Overview

This guide explains how to enable Spring Boot Actuator in the CMS application of a Bloomreach Content implementation project. Spring Boot Actuator provides monitoring and management endpoints over HTTP and JMX, supporting operational visibility in production environments.

When to Use

Enable Spring Boot Actuator to expose health checks, metrics, and management endpoints for the CMS application. This is recommended for production deployments where monitoring and operational insight are required.

Implementation Steps

1. Add Maven Dependencies

Edit cms-dependencies/pom.xml and add the required dependencies. Select the appropriate versions based on your Bloomreach Content version.

For brXM 16.x and 17.x:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
  <version>${spring-boot.version}</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <!-- (check more recent version) -->
  <version>1.12.3</version> 
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-jmx</artifactId>
  <!-- (check more recent version) -->
  <version>1.12.3</version>
</dependency>

For brXM 15.x:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
  <version>${spring-boot.version}</version>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-logging</artifactId>
    </exclusion>
    <exclusion>
      <groupId>org.yaml</groupId>
      <artifactId>snakeyaml</artifactId>
    </exclusion>
  </exclusions>
</dependency>

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <!-- For brXM versions lower than 15.3.0, use version 1.5.5 -->
  <!-- (check more recent version) -->
  <version>1.9.7</version> 
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-jmx</artifactId>
  <!-- For brXM versions lower than 15.3.0, use version 1.5.5 -->
  <!-- (check more recent version) -->
  <version>1.9.7</version>
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
    </exclusion>
  </exclusions>
</dependency>

For all versions:
If your project does not already include Spring Security dependencies, add the following:

<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-web</artifactId>
  <version>${spring-security.version}</version>
</dependency>

<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-config</artifactId>
  <version>${spring-security.version}</version>
</dependency>

Info: Exclude the spring-boot-starter-logging, slf4j-api, and snakeyaml-1.x dependencies as shown above.

These dependencies enable Spring Boot Actuator and integrate the Micrometer metrics framework.

2. Create Spring Boot Configuration

In your CMS module, create src/main/java/org/bloomreach/xm/cms/ActuatorConfiguration.java. Use the version-appropriate file below.

For brXM 16.x and 17.x:

package org.bloomreach.xm.cms;

import javax.naming.NamingException;
import javax.sql.DataSource;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.boot.actuate.jdbc.DataSourceHealthIndicator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.jndi.JndiObjectFactoryBean;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer;

@Configuration
@PropertySource(value = "classpath:actuator.properties")
// From 15.3.0 onwards, add this security annotation
@EnableWebSecurity
public class ActuatorConfiguration {

    @Value("${app.datasource.name}")
    String datasourceName;

    @Bean(destroyMethod = "")
    DataSource jndiDataSource() throws IllegalArgumentException, NamingException {
        final JndiObjectFactoryBean bean = new JndiObjectFactoryBean();
        bean.setJndiName("java:comp/env/jdbc/" + datasourceName);
        bean.afterPropertiesSet();
        return (DataSource) bean.getObject();
    }

    @Bean
    HealthIndicator dbHealthIndicator(final DataSource dataSource) {
        return new DataSourceHealthIndicator(dataSource, "SELECT 1");
    }

    // With Spring Boot 2.7 and later, security is stricter by default.
    // From 15.3.0 onwards, add this method.
    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        // Allow all requests. Adjust as needed for your environment.
        return (web) -> web.ignoring().requestMatchers("/**");
    }
}

For brXM 15.x:

package org.bloomreach.xm.cms;

import javax.naming.NamingException;
import javax.sql.DataSource;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.boot.actuate.jdbc.DataSourceHealthIndicator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.jndi.JndiObjectFactoryBean;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer;

@Configuration
@PropertySource(value = "classpath:actuator.properties")
// From 15.3.0 onwards, add this security annotation
@EnableWebSecurity
public class ActuatorConfiguration {

    @Value("${app.datasource.name}")
    String datasourceName;

    @Bean(destroyMethod = "")
    DataSource jndiDataSource() throws IllegalArgumentException, NamingException {
        final JndiObjectFactoryBean bean = new JndiObjectFactoryBean();
        bean.setJndiName("java:comp/env/jdbc/" + datasourceName);
        bean.afterPropertiesSet();
        return (DataSource) bean.getObject();
    }

    @Bean
    HealthIndicator dbHealthIndicator(final DataSource dataSource) {
        return new DataSourceHealthIndicator(dataSource, "SELECT 1");
    }

    // With Spring Boot 2.7 and later, security is stricter by default.
    // From 15.3.0 onwards, add this method.
    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        // Allow all requests. Adjust as needed for your environment.
        return (web) -> web.ignoring().antMatchers("/**");
    }
}

Info: The annotation @PropertySource(value = "classpath:actuator.properties") references the properties file for additional configuration.

Spring Boot automatically detects Java-based configuration classes in the org.bloomreach.xm.cms package.

3. Create Properties File

Create src/main/resources/actuator.properties with the following content:

management.endpoint.health.probes.enabled=true
management.endpoint.health.show-details=always
management.endpoints.web.exposure.include=*

app.datasource.name=actuatorDS

This configuration enables health probes and exposes all actuator endpoints. For details on available properties, refer to the Spring Boot Actuator documentation.

4. Configure the Datasource

Warning: The app.datasource.name property must reference a JNDI datasource defined in your CMS setup, typically as a <Resource> element in context.xml.

Warning: On Bloomreach Cloud, use the repository datasource named repositoryDS.

For local development with Cargo, you can use an H2 database. Add the following resource definition:

<Resource name="jdbc/actuatorDS" auth="Container" type="javax.sql.DataSource"
     maxTotal="100" maxIdle="10" initialSize="10" maxWaitMillis="10000"
     testWhileIdle="true" testOnBorrow="false" validationQuery="SELECT 1"
     timeBetweenEvictionRunsMillis="10000"
     minEvictableIdleTimeMillis="60000"
     username="sa" password=""
     driverClassName="org.h2.Driver"
     url="jdbc:h2:${repo.path}/brxm/actuator"/>

5. Rebuild and Start the Project

Rebuild and start your project using the Cargo profile. For instructions, see Rebuilding and Restarting a Project.

Verification

After starting the project, access http://localhost:8080/cms/actuator in your browser. You should see the Spring Boot Actuator endpoint page.

Troubleshooting

  • If the /actuator endpoint is not available, verify that:

    • All required dependencies are present and correctly versioned.

    • The ActuatorConfiguration class is in the correct package and compiled.

    • The actuator.properties file exists and is on the classpath.

    • The JNDI datasource is defined and accessible.

  • Review application logs for errors related to Spring Boot or datasource configuration.

Share Feedback
Page: /build/spring-services/spring-boot-integration
Section: Build
Category *
Enable Spring Boot Actuator | Bloomreach Content Documentation