You are viewing the documentation for Blueriq 16. Documentation for other versions is available in our documentation directory.

Introduction

Actuator is a Blueriq component which enables metrics and statistics about the Runtime. It is based on Spring Boot Actuator which helps you monitor and manage your application by providing a number of endpoints. The table below summarizes the Spring Boot Actuator endpoints which are enabled in the Runtime. Besides those, there are a number of  Blueriq specific actuator endpoints. It is recommended to not expose actuator endpoints via the load balancer/firewall to the public and thereby only make them accessible from inside the network.

Actuator IDEndpointDescription
auditevents/actuator/auditeventsExposes audit events information for the current application
beans/actuator/beansDisplays a complete list of all the Spring beans present in runtime
conditions

/actuator/conditions

Shows the conditions that were evaluated on configuration and auto-configuration classes and the reasons why they did or did not match
configprops/actuator/configpropsDisplays the used runtime properties
env/actuator/envDisplays all the profiles, runtime properties, system properties and environment variables
health/actuator/healthShows runtime health information
httptrace/actuator/httptraceDisplays information about the last x HTTP requests (By default x=100)
info/actuator/infoDisplays information about the runtime. Currently displays the list of unhandled exceptions
logfile/actuator/logfile

Returns the contents of the log file (if configured through logging.file.name)

loggers

/actuator/loggers

Displays and modifies the configuration of loggers in the application
mappings/actuator/mappingsDisplays a collated list of all @RequestMapping paths
metrics/actuator/metricsDisplays various metrics about the runtime. Both standard Spring Boot metrics and Blueriq specific metrics are displayed
threaddump/actuator/threaddumpPerforms a thread dump.

Enable component

To enable Blueriq Actuators add the Spring profile named actuator in file bootstrap.properties. For example:

bootstrap.properties
 spring.profiles.active=native,actuator

Starting with Release 13, the refresh endpoint should be both enabled and exposed when the development-tools profile is active, otherwise the runtime will not start.

Context path

The default path for Blueriq Actuators is /actuator. This can be changed to a different path with the management.endpoints.web.base-path property:

application-actuator.properties
management.endpoints.web.base-path=/somethingElse

If the runtime is accessible via https://localhost:8080/Runtime, the actuators can be found at https://localhost:8080/Runtime/actuator by default, or at http://localhost:8080/Runtime/somethingElse if the property above would be set.

Exposing endpoints

All enabled endpoints are available through both JMX and HTTP. (except for the logfile endpoint, which is only available through HTTP). You should limit the access to the endpoint to not be accessible from the public network. To customize this, you can change the following properties.

PropertyBlueriq default

management.endpoints.jmx.exposure.exclude


management.endpoints.jmx.exposure.include

*

management.endpoints.web.exposure.exclude


management.endpoints.web.exposure.include

*

So for instance to disable exposing all the endpoints but the health endpoint via JMX, add the following property.

application-actuator.properties
management.endpoints.jmx.exposure.include=health

In this example all endpoints are still exposed via HTTP.

Starting with Release 13, JMX is disabled by default. You can reenable it by setting the property spring.jmx.enabled to true.

Security

By default all actuators are secured using basic authentication. In order to access actuator endpoints, the authenticated user must have the role 'ACTUATOR'. When using the development tools component, this user can be defined in the users.properties file.

user.properties
admin={noop}welcome,ACTUATOR

Enable/disable default security

When more control over the security of individual endpoints is required, a custom implementation can be written.
For this, you first need to disable the default security for the actuators. This can be done by setting the property blueriq.security.actuator.enabled in application-actuator.properties. If you don't specify this property, security will be enabled.

application-actuator.properties
# Security
blueriq.security.actuator.enabled=false

Implementing custom security for actuator endpoints

By default, all users need to have the role ACTUATOR to acces the actuator pages. In the following example, the endpoints actuator/health and actuator/info are available to all, but the CUSTOM_ROLE is required to access the other actuator endpoints. This can be done by disabling the default security for actuator, and implement your own custom SecurityConfigurer like in the example below.

CustomMetricsApiSecurityConfigurer.java
@Configuration
@ConditionalOnProperty(name = "blueriq.security.actuator.enabled", havingValue = "false", matchIfMissing = false)
public class CustomMetricsApiSecurityConfigurer {
 
	// 1. Inject any required dependencies
    @Autowired
    private WebEndpointProperties webEndpointProperties;
 
	@Autowired
	@Qualifier("blueriqAuthenticationManager")
	private AuthenticationManager authenticationManager;
 
	// 2. Specify the authentication manager
	@Override
	public AuthenticationManager authenticationManager() throws Exception {
		return authenticationManager;
	}
 
	// 3. Configure HTTP security
	@Bean
	protected SecurityFilterChain customActuatorSecurityChain(HttpSecurity http) throws Exception {
    	 http.antMatcher(webEndpointProperties.getBasePath() + "/**")
         .authorizeRequests()
			.requestMatchers(EndpointRequest.to(HealthEndpoint.class, InfoEndpoint.class)).permitAll() 
	        .requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("CUSTOM_ROLE");
		return http.build();
	}
}

Enable/Disable individual endpoints

Each endpoint can be enabled or disabled via a property with the format management.endpoint.[endpoint-id].enabled=true/false

# Enable all endpoints
management.endpoints.enabled-by-default=true

Actuator Endpoints

For a complete overview of the standard Spring Boot Actuator web API, which described example request and responses for all actuator endpoints, have a look at the documentation.

Info

The standard info 

Example request
GET http://localhost:92/Runtime/actuator/info
Example response
{
    "exceptions": [
        {
            "cause": null,
            "stackTrace": [
                {
                    "methodName": "getInternalFlow",
                    "fileName": "FlowEngine.java",
                    "lineNumber": 269,
                    "className": "com.aquima.interactions.flow.model.FlowEngine",
                    "nativeMethod": false
                },
                {
                    "methodName": "startFlow",
                    "fileName": "FlowEngine.java",
                    "lineNumber": 130,
                    "className": "com.aquima.interactions.flow.model.FlowEngine",
                    "nativeMethod": false
                }
... 
            ],
            "flowName": "main",
            "message": "Unknown flow: main",
            "localizedMessage": "Unknown flow: main",
            "suppressed": []
        }
    ]
}

Metrics

Navigating to /Runtime/actuator/metrics displays a list of available metrics. You can drill down to view information about a particular metric by providing its name as a selector, e.g. /actuator/metrics/jvm.memory.max

Example request
GET http://localhost:92/Runtime/actuator/metrics
Example response
{
"names": [
	"jvm.buffer.memory.used",
	"jvm.memory.used",
	"jvm.gc.memory.allocated",
	"jvm.memory.committed",
	"jvm.gc.max.data.size",
	"logback.events",
	"system.cpu.count",
	"runtime.session.counter",
	"jvm.memory.max",
	"jvm.buffer.total.capacity",
	"jvm.buffer.count",
	"jvm.threads.daemon",
	"process.start.time",
	"runtime.average.compose.time",
	"runtime.request.counter",
	"jvm.gc.live.data.size",
	"process.cpu.usage",
	"jvm.gc.pause",
	"process.uptime",
	"runtime.average.event.time",
	"runtime.exceptions.counter",
	"http.server.requests",
	"system.cpu.usage",
	"jvm.threads.live",
	"jvm.threads.peak",
	"jvm.gc.memory.promoted"
]
}

Blueriq specific metrics

The following Runtime specific metrics are available.

MetricDescription
runtime.request.counterCounts the total number of request for the UI REST API ( /server/* )
runtime.exceptions.counterCounts the number of unhandled exceptions
runtime.session.counterCounts the number of portal sessions currently in the runtime
gauge.portal-session.page.compose.average-timeMeasures the average page compose time in milliseconds
gauge.response.portal-session.handle-eventMeasures the average time for handling portal session events in milliseconds

The metrics are per node. When running in a cluster the counter.portal-session metric will not be displayed

Blueriq specific endpoints

With the endpoints below you can reset some of the Blueriq specific metrics provided by the metrics endpoint.

Reset Runtime Requests

Example request
POST http://localhost:92/Runtime/actuator/runtimeResetRequestCount
Example response
runtime.request.counter was reset

Reset Portal-Session Exceptions

Example request
POST http://localhost:92/Runtime/actuator/portalSessionResetExceptions
Example response
runtime.exceptions.counter was reset

Reset Portal-Session Compose Time

Example request
POST http://localhost:92/Runtime/actuator/portalSessionResetComposeTime
Example response
gauge.portal-session.page.compose.average-time was reset

Reset Portal-Session Handle-Event Time

Example request
POST http://localhost:92/Runtime/actuator/portalSessionResetHandleEvent
Example response
gauge.response.portal-session.handle-event was reset