A package that provides a set of APIs used by spring-boot-admin to view the state of the microservice by registering with eureka server.
npm install spring-boot-admin-actuator
info | Displays application information.
health | Shows application health information.
logfile | Shows application log's.
actuator | Shows middleware api.
configprops | Shows application configuration.
mappings | Shows user defined application api.
metrics | Shows some application metrics.
env | Shows environment configuration.
logger | Allows you to change the log level at runtime.
bash
$ npm install --save spring-boot-admin-actuator
`
Usage
To use this library you must pass as parameter an object that has inside the configurations that you want to show in tab "Configuration Properties" of the SBA and especially the mandatory properties for the correct functioning of the other APIs offered by the library, such as /actuator and /logfile
Mandatory Properties:
Property | Description
--- | ---
configurationObject.logFileAddr | valued with phisical path of log to be sended to SBA
configurationObject.ipAddr | valued with ip of the service
configurationObject.port | valued with the port of the service
$3
`js
const sbaActuator = require('spring-boot-admin-actuator');
const app = express();
const mappingsDocument = require('./path/to/mappings.json')
const {LoggerLevels} = require('./utils/log-utils');
//Creation of the global variable containing the configurated log level
global.loggerLevel = LoggerLevels.INFO;
const options = {
config: configurationObject,
mappings: mappingDocument, // NOT MANDATORY activate the mappings tab
metricsIsActive: true, // NOT MANDATORY activate the metrics tab
environmentIsActive: true // NOT MANDATORY activate the environment tab
loggersIsActive: true // NOT MANDATORY enable tab loggers, to be used in combination with the global loggerLevel variable
};
app.use(sbaActuator(options));
`
Where the property mappings is not mandatory but if valued with mappings.json (of which you can find an example later) will enable the tab mappings on the SBA.
Starting from version 1.4.0 the API loggers can be initialized in 2 ways:
1 - as described in the above example by passing "loggersIsActive = true" and initializing the global "loggerLevel" variable.
2 - by passing "loggersIsActive = true" and with "loggerMap" map defined in global variables
mapping-json
`json
{
"contexts": {
"your-application-name": {
"mappings": {
"dispatcherServlets": {
"api": [
{
"handler": "package.file.Method(parameter...)",
"predicate": "{GET [/api/example/{path-variable}]}",
"details": {
"handlerMethod": {
"className": "package.filename",
"name": "name of the method",
"descriptor": "description of method"
},
"requestMappingConditions": {
"consumes": [],
"headers": [],
"methods": [
"GET"
],
"params": [],
"patterns": [
"/api/example/{path-variable}"
],
"produces": [
{
"mediaType": "application/json",
"negated": false
}
]
}
}
},
{
"handler": "package.file.Method(parameter...)",
"predicate": "{POST [/api/example]}",
"details": {
"handlerMethod": {
"className": "package.filename",
"name": "name of the method",
"descriptor": "description of method"
},
"requestMappingConditions": {
"consumes": [{
"mediaType": "application/json",
"negated": false
}],
"headers": [],
"methods": ["POST"],
"params": [],
"patterns": ["/api/example"],
"produces": [{
"mediaType": "application/json",
"negated": false
}]
}
}
}
]
}
}
}
}
}
`
Endpoints Examples
$3
`json
{
"build": {
"name": "app",
"version": "1.0.0",
"node-version": ">12.6.0"
},
}
`
> _IMPORTANT:_ To get this information the package have some sort of logic:
>When the express app is executed with `node app.js` or `npm start` the module will look for a file named package.json where the node command was launched.
$3
`json
{
"status": "UP"
}
`
$3
`json
{
"_links": {
"self": {
"href": "http://host:port/actuator",
"templated": false
},
"configprops": {
"href": "http:/host:port/actuator/configprops",
"templated": true
},
"logfile": {
"href": "http://host:port/actuator/logfile",
"templated": true
},
"health": {
"href": "http://host:port/actuator/health",
"templated": true
},
"info": {
"href": "http://host:port/actuator/info",
"templated": true
}
}
}
`
> _IMPORTANT:_
>This endpoint needs the correct properties inside the configurationObject to replace placeholder hosts and ports (ipAddr and port).
$3
The configuration keys shown in this tab are automatically hidden if the name contains the words "password", "apikey", "key", "secret" and "credential"
`json
{
"contexts": {
"application": {
"eureka": {
"prefix": "eureka",
"properties": {
"host": ["http://localhost:8761/eureka/apps/"],
"ipAddr": "127.0.0.1",
"maxRetries": 10,
"requestRetryDelay": 2000
}
},
"logFileAddr": {
"prefix": "logFileAddr",
"properties": {
"value": "C:\\Users\\user\\.pm2\\logs\\app-out.log"
}
},
"ipAddr": {
"prefix": "ipAddr",
"properties": {
"value": "127.0.0.1"
}
},
"port": {
"prefix": "port",
"properties": {
"value": 3000
}
}
}
}
}
`
> _IMPORTANT:_
>The data structure "contexts": { "application": {}} are added automatically by the SBA, the other (from "eureka") in the example are exactly the configurationObject passed as parameter.
$3
The configuration keys shown in this tab are automatically hidden if the name contains the words "password", "apikey", "key", "secret" and "credential"
!screenshot
`json
{
"activeProfiles": [
"development"
],
"propertySources": [
{
"name": "systemProperties",
"properties": {
"ALLUSERSPROFILE": {
"value": "C:\\ProgramData"
}
},
"automation": {
"value": "true"
},
"autorestart": {
"value": "true"
}
}
]
}
`
$3
!screenshot
> _IMPORTANT:_
>1. For this endpoint the library needs in the configurationObject the property logFileAddr to be valued with path of the log.
>2. Since version 1.3.0 a small fix has been introduced, if the log is empty to prevent the loading spinner from remaining on the SBA, the text "EMPTY LOG" is sent.
$3
!screenshot
> _IMPORTANT:_
>for this endpoint the library needs to add the mapping property as well as the configurationObject (which is mandatory).
$3
Starting with version 1.1 with the support of the metrics (if enabled) the library adds the display of the process life time directly on the SBA.
!screenshot
In combination with reading environment variables (if enabled) the process PID will also be shown.
$3
To use Loggers API at least one of global variable 'loggerLevel' (for 1.3.0 compatibility) or 'loggerMap' must be defined (since version 1.4.0)
#### 1.4.0
!screenshot
Since version 1.4.0 the library is distributed with the logger.js file that you can copy and use in your software, you can find it under utils/logger.js
This class integrates perfectly with the innovations introduced in the new version of the API loggers.
The WARN level has also been added to those managed.
#### logger.js
`js
const LEVELS = require('spring-boot-admin-actuator/lib/utils/logger-level').LoggerLevels;
const {performance} = require('perf_hooks');
const configuredLogLevel = "INFO" // THIS IS AN EXAMPLE, GET THIS DATA FROM YOUR CONFIGURATION
const startLevel = LEVELS[configuredLogLevel].name;
class Logger {
constructor(classe) {
this.classe = classe ? classe : undefined;
if(typeof this.classe === 'undefined') {throw new Error("Required class parameter is missing")}
this.debug = this.debug.bind(this);
this.info = this.info.bind(this);
this.warn = this.warn.bind(this);
this.error = this.error.bind(this);
this.writeToConsole = this.writeToConsole.bind(this);
this.getClass = this.getClasse.bind(this);
this.setLoggerMap(this.classe);
this.getEffectiveLevel = this.getEffectiveLevel.bind(this);
}
static getStartTime(){
return performance.now();
}
/**
*
@param {} level: level of the log
@param {} method: the method that generated the log
@param {} message: the message of the log
@param {} start: a timestamp, if present adds to the messagge the execution time in milliseconds.
*
* @returns 2023-10-21T10:51:39.946Z | INFO | message.controller.js | read | END | 45.89750003814697 ms. |
*/
writeToConsole(level, method, message, start) {
if (LEVELS[global.loggerMap[this.classe].effectiveLevel].order <= LEVELS[level].order) {
const end = start != undefined ? performance.now() - start : undefined
const dateTime = new Date().toISOString();
const formattedMessage = dateTime + " | " + level + " | " + this.classe + " | " + method + " | " + message + " | " + (end != undefined ? (end + " ms. |") : "");
consolelevel.toLowerCase();
}
}
debug(method, message, start) {
this.writeToConsole('DEBUG', method, message, start);
}
info(method, message, start) {
this.writeToConsole('INFO', method, message, start);
}
warn(method, message, start) {
this.writeToConsole('WARN', method, message, start);
}
error(method, message, start) {
this.writeToConsole('ERROR', method, message, start);
}
getClasse(){
return this.classe;
}
getEffectiveLevel(){
return global.loggerMap[classe].effectiveLevel;
}
setLoggerMap(classe){
if(typeof global.loggerMap === 'undefined'){
global.loggerMap = {
"ROOT": {
"configuredLevel": startLevel,
"effectiveLevel": startLevel
}
}
}
global.loggerMap[classe] = {
"configuredLevel": startLevel,
"effectiveLevel": startLevel
}
}
}
module.exports = Logger
`
Each time a logger is instantiated by calling the constructor method, it automatically adds the new logger to the global.loggerMap.
the logger class provided contains the log level control logic relative to the file level, it uses the updated LoggerLevels object present in the library.
Here is an example of using the logger class provided:
`js
const Logger = require('../../utils/logger');
const log = new Logger("message.controller.js");
log.debug(method, "message");
`
> _IMPORTANT:_
> To use this version of API your software must set the global loggerMap variable.
#### 1.3.0
!screenshot
With version 1.3.0 the library adds the loggers tab that allows you to change the log level at runtime
With 1.3.0 automatically the library allows you to manage only the root level of the log.
This API uses the global loggerLevel variable and should be used to allow/inhibit the methods you use to log.
Managed log levels are 4: OFF, DEBUG, INFO and ERROR.
An example of usage in combination with custom log methods:
`js
exports.debug = function(method, message, start) {
if(!isDebugEnabled()){ return; }
console.debug(new Date().toISOString()+" | DEBUG | "+ method +" | "+message+" | ");
};
exports.error = function(method, message, start) {
if(!isEnabled()){ return; }
console.error(new Date().toISOString()+" | ERROR | "+method+" | "+message+" | ");
};
function isDebugEnabled(){ return (global.loggerLevel != LoggerLevels.OFF) && (global.loggerLevel != LoggerLevels.INFO) && (global.loggerLevel != LoggerLevels.ERROR); }
function isEnabled(){ return (global.loggerLevel != LoggerLevels.OFF); }
const LoggerLevels = Object.freeze({"OFF":"OFF", "DEBUG":"DEBUG", "INFO":"INFO","ERROR":"ERROR"});
``