User Guide: SDKs > Volt MX Iris SDK > Using Log SDK
Volt MX Logger
Introduction
Volt MX Logger is introduced to persist logs based on six log levels:
- Trace
- Debug
- Info
- Warn
- Error
- Fatal
The logger feature provides three ways of providing logs to output: console, file and network. The logger feature is defined in the namespace voltmx.logger. Each log will be printed as per the below syntax:
[LoggerInstanceName][AppID AppVersion][TimestampTimeZone][LogLevel][SessionID][ThreadInformation][DeviceId][DeviceOSInfo][FileName][ClassName][MethodName][LineNo]Message
Scope
The Volt MX Logger feature is available for Volt MX Iris, Android, iOS, and Windows 10.
Properties
voltmx.logger exposes the below properties:
currentLogLevel
currentLogLevel sets the log level of the logger to any of the six mentioned levels. setting to a certain level will allow the logs of that level and above to be persisted. For instance, if the currentLogLevel is set to Error, only the error and fatal log statements are printed.
| Syntax | JavaScript: voltmx.logger.currentLogLevel |
| Possible Values | The below log levels may be set to the current log level: voltmx.logger.logLevel.ALL voltmx.logger.logLevel.NONE voltmx.logger.logLevel.TRACE voltmx.logger.logLevel.DEBUG voltmx.logger.logLevel.INFO voltmx.logger.logLevel.WARN voltmx.logger.logLevel.ERROR voltmx.logger.logLevel.FATAL |
| Default Value | voltmx.logger.logLevel.NONE |
| Read or Write | Yes (Read and Write) |
| JavaScript Example | voltmx.logger.currentLogLevel = voltmx.logger.logLevel.DEBUG; |
APIs
Multiple instances of the logger can be created using APIs. The console and the file can be activated as a part of the configuration, if required. The below APIs are introduced to create logger, activate persistors and generate the logs.
createFilePersistor()
The createFilePersistor() API is used to create the configuration for the file persistor. This configuration can be used with the loggerConfig object (For more information, refer addPersistor API).
Note: In Iris Android, if you want activate file persistor and view the logs in the file, you need to add WRITE_EXTERNAL_STORAGE under Permissions tab.
| Signature | JavaScript: createFilePersistor |
| Parameters | N/A |
| Return Type | The API return a fileConfig object. The below properties have been exposed on the file persistor. |
| JavaScript Example | var persistor1 = new voltmx.logger.createFilePersistor(); persistor1.maxFileSize = 100; persistor1.maxNumberOfLogFiles = 15; |
| Platform Availability | Available on IDE, Android, iOS, and Windows 10 |
maxFileSize
The maxFileSize API is used to define the maximum size of the files created in bytes.
| Syntax | maxFileSize |
| Type | Number |
| Possible Values | Positive Integer |
| Default Value | 10000 |
| Read or Write | Only Write |
| JavaScript Example | var persistor1 = new voltmx.logger.createFilePersistor(); persistor1.maxFileSize = 10000; |
maxNumberOfLogFiles
To define the maxNumberOfLogFiles the app can have at a maximum during any instant. The filePersistor is a rolling file appender i.e. the data of latest configured files is preserved.
| Syntax | maxNumberOfLogFiles |
| Type | Number |
| Possible Values | Non-zero, Positive Integer |
| Default Value | 10 |
| Read or Write | Only Write |
| JavaScript Example | var persistor1 = new voltmx.logger.createFilePersistor(); persistor1.maxNumberOfLogFiles = 20; |
createLoggerConfig()
CreateLoggerConfig() is used to create the configuration object for the logger. This object is used in the createNewLogger() API. The object has various properties exposed to define our configuration. To apply the configuration, you need to use setConfig() API . When you pass the object through createNewLogger() API , configuration object is immediately applied .
| Signature | Javascript: createLoggerConfig |
| Parameters | N/A |
| Return Type | The API returns a loggerConfig Object. All the properties are static and affect all the logger instances. The below properties have been exposed. |
| JavaScript Example | Example 1: var loggerConfig = new voltmx.logger.createLoggerConfig(); Example 2: var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.bytesLimit = 10000; loggerConfig.statementsLimit = 10; loggerConfig.timeFormat = "dd-MM-yyyy HH.mm.ss.SSS"; loggerConfig.timeZone = "UTC"; loggerConfig.overrideConfig = true; loggerConfig.logLevel= voltmx.logger.logLevel.INFO.value; |
| Platform Availability | IDE, Android, iOS, and Windows 10 |
bytesLimit
The console logs will be printed as soon as the logging methods are invoked. It is performance intensive to persist the logs one by one on the file. The bytesLimit can be used to accumulate the logs until the bytesLimit is reached and then flushed onto the file.
| Syntax | bytesLimit |
| Type | Number |
| Possible Values | Any positive integer |
| Default Value | 10000 |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.bytesLimit = 20000; |
statementsLimit
The console logs will be printed as soon as the logging methods are invoked. It is performance intensive to persist the logs one by one on the file. The statementsLimit can be used to accumulate the logs until the specified number of statements are reached and then flushed onto the file.
| Syntax | statementsLimit |
| Type | Number |
| Possible Values | Any non-negative integer |
| Default Value | 20 |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.statementsLimit = 30; |
timeFormat
Each log is printed in a specified format. The format includes the timestamp. This property is used to specify the syntax of the timeFormat.
| Syntax | timeFormat |
| Type | String |
| Possible Values | Any valid time format pattern |
| Default Value | "dd-mm-yyyy HH.mm.ss.SSS" |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.timeFormat = "dd-MM-yyyy HH.mm.ss.SSS"; |
timeZone
Each log is printed in a specified format. The format includes the timestamp. This property is used to specify the syntax of the timeZone.
| Syntax | timeZone |
| Type | String |
| Possible Values | UTC, LocalTime |
| Default Value | UTC |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.timeZone = "UTC"; |
overrideConfig
All the properties are exposed by loggerConfig. Changing the property and using setConfig() API will affect all the logger instances created. overrideConfig is used to specify if the configuration should override the existing configuration.
| Syntax | overrideConfig |
| Type | Bool |
| Possible Values | True or False |
| Default Value | True |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.overrideConfig = false; |
logLevel
The logLevel property works similar to currentLogLevel property. There are six log levels in the logLevel property.
| Syntax | logLevel |
| Possible Values | voltmx.logger.logLevel.ALL voltmx.logger.logLevel.NONE voltmx.logger.logLevel.TRACE voltmx.logger.logLevel.DEBUG voltmx.logger.logLevel.INFO voltmx.logger.logLevel.WARN voltmx.logger.logLevel.ERROR voltmx.logger.logLevel.FATAL |
| Default Value | voltmx.logger.logLevel.NONE |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); loggerConfig.logLevel = voltmx.logger.logLevel.INFO.value; |
addPersistor
The property can be used to add file persistor through loggerConfig object.
| Syntax | addPersistor |
| Possible Values | Object of type filePersistor |
| Default Values | N/A |
| Read or Write | Only Write |
| JavaScript Example | var loggerConfig = new voltmx.logger.createLoggerConfig(); var filePers = new voltmx.logger.createFilePersistor();filePers.maxNumberOfLogFiles = 15; loggerConfig.addPersistor(filePers); |
createNewLogger() API
| Signature | createNewLogger |
| Parameters | This API takes three parameters: LoggerName, LoggerConfigloggerName: The loggerName is a string used to identify the instance of the loggerObject. Note: This is a mandatory value. loggerConfiguration: The loggerConfiguration is the configuration object. For more information, refer createLoggerConfig(). |
| Return Type | Returns a logger object on which various functions such as trace(), debug(), info(), warn(), error() and fatal() APIs are exposed. |
| JavaScript Example | var lConfig = new voltmx.logger.createLoggerConfig(); var loggerObj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lConfig); |
| Platform Availability | IDE, Android, iOS, and Windows 10 |
activatePersistors()
Unless we activate persistors, logs will not be pushed to the corresponding persistors. This is a mandatory step and no persistor is activated by default.
| Signature | activatePersistors |
| Parameters | The API takes one parameter: persistor name. This parameter could be either a console or a file. |
| Return Type | N/A |
| JavaScript Example | voltmx.logger.activatePersistors(voltmx.logger.consolePersistor) voltmx.logger.activatePersistors(voltmx.logger.filePersistor) voltmx.logger.activatePersistors(voltmx.logger.consolePersistor | voltmx.logger.filePersistor) |
| Platform Availability | IDE, Android, iOS, and windows 10 |
Note: Console Persistor logs will not be available in Iris Windows 10 and Native Windows 10.
deactivatePersistors()
If you want to make sure the logs are not pushed to a corresponding persistor or any combination of them, use deactivatePersistors() API.
| Signature | deactivatePersistors |
| Parameters | The API takes one parameter: persistor name. This parameter could be either a console or a file or any combination of these. |
| Return Type | N/A |
| JavaScript Example | voltmx.logger.deactivatePersistors(voltmx.logger.consolePersistor) voltmx.logger.deactivatePersistors(voltmx.logger.filePersistor) voltmx.logger.deactivatePersistors(voltmx.logger.consolePersistor | voltmx.logger.filePersistor) |
| Platform Availability | IDE, Android, iOS, and windows 10 |
trace() API
The trace() API is used to trace log level messages.
| Signature | trace |
| Parameters | The API takes one parameter – a string input log that must be persisted. |
| Return Type | N/A |
| JavaScript Example | Var lconfig = new voltmx.logger.createNewLoggerConfig(); loggerobj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lconfig); loggerobj.trace("Message to be added in Trace"); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
debug() API
The debug() API is used to log the debug level messages:
| Signature | debug |
| Parameters | The API takes one parameter – a string input log that must be persisted |
| Return Type | N/A |
| JavaScript Example | Var lconfig = new voltmx.logger.createNewLoggerConfig(); loggerobj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lconfig); loggerobj.debug("Message to be added in Debug"); |
| Platform Availability | IDE ,Android , iOS and windows 10 |
info() API
The info() API is used to log the info level messages.
| Signature | info |
| Parameters | The API takes one parameter – a string input log that must be persisted. |
| Return Type | N/A |
| JavaScript Example | Var lconfig = new voltmx.logger.createNewLoggerConfig(); loggerobj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lconfig); loggerobj.info("Message to be added in Info"); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
error() API
The error() API is used to log the error messages:
| Signature | error |
| Parameters | The API takes one parameter – a string input log that must be persisted. |
| Return Type | N/A |
| JavaScript Example | Var lconfig = new voltmx.logger.createNewLoggerConfig(); loggerobj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lconfig); loggerobj.error("Message to be added in Error"); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
warn() API
The warn() API is used to log the warning messages:
| Signature | warn |
| Parameters | The API takes one parameter – a string input log that must be persisted |
| Return Type | N/A |
| JavaScript Example | Var lconfig = new voltmx.logger.createNewLoggerConfig(); loggerobj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lconfig); loggerobj.warn("Message to be added in Warn"); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
fatal() API
The fatal() API is used to log the fatal messages:
| Signature | fatal |
| Parameters | The API takes one parameter – a string input log that must be persisted |
| Return Type | N/A |
| JavaScript Example | Var lconfig = new voltmx.logger.createNewLoggerConfig(); loggerobj = new voltmx.logger.createNewLogger("AndroidLoggerDemo", lconfig); loggerobj.fatal("Message to be added in fatal"); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
flush() API
The flush() API is used to flush all the statements onto the activated persistors regardless whether the bytesLimit or statementsLimit are met.
| Signature | flush |
| Parameters | N/A |
| Return Type | N/A |
| JavaScript example | voltmx.logger.flush(); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
setconfig() API
The setconfig() API is a convenience API used to set LoggerConfig (mentioned earlier). Since loggerConfig is a singleton, If you set the loggerConfig once, it is applied across all the logger objects.
| Signature | setConfig |
| Parameters | loggerConfig |
| Return Type | N/A |
| JavaScript Example | Var logConfig = new voltmx.logger.createLoggerConfig(); voltmx.logger.setConfig(logConfig); |
| Platform Availability | IDE, Android, iOS, and windows 10 |
setPersistConfig()
The setPersistConfig() API is used to change persistorConfig or set it to fresh, when it is not set through loggerConfig. As the persistors are singletons, they will have impact on all loggerObjects when set.
| Signature | setPersistorConfig |
| Parameters | persistor |
| Return Type | N/A |
| JavaScript Example | Var filePers = new voltmx.logger.createFilePersistor(); filePers.maxNumberOfFiles = 1; voltmx.logger.setPersistorConfig(filePers); |
| Platform Availability | IDE, Android, iOS, and Windows 10 |
App Logger
The default logger Instance created can be used to write log statements. If the user wants to create additional logger instances he is free to do so. The logger name used for appLogger is voltmxLogger.
Usage
voltmx.logger.appLogger.error("Message to be logged at error log level");
voltmx.logger.appLogger.debug("Message to be logged at error log level");
voltmx.logger.appLogger.trace("Message to be logged at error log level");
Usage Guidelines/Restrictions/Examples
//Create Logger Configuration
var lConfig = new voltmx.logger.createLoggerConfig();
//Create FilePersistor
Var persistor1 = new voltmx.logger.createFilePersistor();
//Add Persistor to the loggerConfig
lConfig.addPersistor(persistor1);
//Create Logger Object
loggerObj = new voltmx.logger.createNewLogger("UserLogs", lConfig);
voltmx.logger.activatePersistors(voltmx.logger.consolePersistor);
voltmx.logger.activatePersistors(voltmx.logger.filePersistor);
voltmx.logger.currentLogLevel = voltmx.logger.logLevel.INFO;
//Print Statements
for(var i=0;i<20;i++){
var msg = "statement" + i;
loggerObj.debug("Message in debug level" + msg);
loggerObj.trace("Message in trace level" + msg);
loggerObj.fatal("Message in Fatal level" + msg);
loggerObj.info("Message in Info level" + msg);
loggerObj.warn("Message in warn level" + msg);
loggerObj.error("Message in error level" + msg);
}
Note:
Unlike the file and console persistors, the network persistor is always enabled and can be managed from Volt MX Foundry Admin Console. Do not create/activate/deactivate the network persistor from the client application code. For more details on configuring Network Persistor, refer to the Log Level by Client Filters section in the Standard Logs doc.
To manage middleware logs, refer to App Services > Logs.
* Running the logger on Android devices that run on Android Lollipop or earlier versions with less than 1GB RAM may cause memory issues. These memory issues are at the Android OS level and have been declared obsolete by Google. For more information, refer to the Issue Tracker.