Class Logger
- java.lang.Object
-
- com.worklight.common.Logger
-
public final class Logger extends java.lang.Object
Logger is an abstraction of, and pass through to, android.util.Log. Logger provides some enhanced capability such as capturing log calls, package filtering, and log level control at both global and individual package scope. It also provides a method call to send captured logs to the IBM MobileFirst Platform server. When this Logger class's capture flag is turned on via setCapture(true) method call, all messages passed through this class's log methods will be persisted to store in the following JSON object format:{ "timestamp" : "17-02-2013 13:54:27:123", // "dd-MM-yyyy hh:mm:ss:S" "level" : "ERROR", // FATAL || ERROR || WARN || INFO || LOG || DEBUG || TRACE "package" : "your_tag", // typically a class name, app name, or JavaScript object name "msg" : "the message", // a helpful log message "metadata" : {"hi": "world"}, // (optional) additional JSON metadata, appended via doLog API call "threadid" : long // (optional) id of the current thread }
Log data is accumulated persistently to a log file until the file size is greater than FILE_SIZE_LOG_THRESHOLD. At this point the log file is rolled over. Log data will only be captured oncecom.worklight.common.Logger.setContext(Context) is called. Once both files are full, the oldest log data is pushed out to make room for new log data.
Log file data is sent to the IBM MobileFirst Platform server when this class's send() method is called and the accumulated log size is greater than zero. When the log data is successfully uploaded, the persisted local log data is deleted.
All of this class's method calls, such as info(String), are pass-throughs to the equivalent method call in android.util.Logger when the LEVEL log function called is at or above the set LEVEL.
As a convenience, this Logger also sets a global java.util.logging.Handler. Developers who would rather use java.util.logging.Logger API may do so, with the understanding that java.util.logging.Logger API calls will not be captured until com.worklight.common.Logger.setContext(Context) is called. The mapping of java.util.logging.Level to com.worklight.common.LEVEL is:
JUL level Logger level SEVERE ERROR WARNING WARN INFO INFO CONFIG LOG FINE DEBUG FINER TRACE FINEST TRACE
-
-
Nested Class Summary
Nested Classes Modifier and Type Class and Description protected static class
Logger.FileLoggerInterface
static class
Logger.LEVEL
Levels supported in this Logger class.
-
Method Summary
Methods Modifier and Type Method and Description void
debug(java.lang.String message)
Log at DEBUG level.void
debug(java.lang.String message, JSONObject additionalMetadata)
Log at DEBUG level.void
debug(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at DEBUG level.void
error(java.lang.String message)
Log at ERROR level.void
error(java.lang.String message, JSONObject additionalMetadata)
Log at ERROR level.void
error(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at ERROR level.void
fatal(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at FATAL level.static boolean
getCapture()
Get the current value of the capture flag, indicating that the Logger is recording log calls persistently.static java.util.HashMap
getFilters()
Get the current list of filters.static Logger
getInstance(java.lang.String tag)
Get or create an instance of this logger.static Logger.LEVEL
getLevel()
Get the current Logger.LEVEL.static int
getMaxFileSize()
Get the current setting for the max file size threshold.void
info(java.lang.String message)
Log at INFO level.void
info(java.lang.String message, JSONObject additionalMetadata)
Log at INFO level.static boolean
isUnCaughtExceptionDetected()
Ask the Logger if an uncaught exception, which often appears to the user as a crashed app, is present in the persistent capture buffer.void
log(java.lang.String message)
Log at LOG (Android VERBOSE) level.void
log(java.lang.String message, JSONObject additionalMetadata)
Log at LOG (Android VERBOSE) level.static void
send()
Send the accumulated log data when the persistent log buffer exists and is not empty.static void
send(com.worklight.wlclient.WLRequestListener listener)
SeeLogger.send()
static void
sendIfUnCaughtExceptionDetected(Context context)
Deprecated.since version 6.2; useLogger.send()
withLogger.isUnCaughtExceptionDetected()
conditional instead.Send the log file when there is an uncaught exception detected, and was recorded to the log buffer due to capture being turned on at the time of the uncaught exception.
This is a convenience method so that callers may place a single line of code at the point in their application where they want to call it.
static void
setAutoSendLogs(boolean _autoSendLogs)
Global setting: turn Auto Log Send on and off.static void
setCapture(boolean _capture)
Global setting: turn persisting of log data passed to this class's log methods on or off.static void
setContext(Context _context)
Context object must be set in order to use the Logger API.static void
setFilters(java.util.HashMap _filters)
Filter on packages at and above designated LEVEL.static void
setLevel(Logger.LEVEL desiredLevel)
Set the level and above at which log messages should be saved/printed.static void
setMaxFileSize(int bytes)
Set the maximum size of the local log file.void
trace(java.lang.String message)
Log at TRACE level.void
trace(java.lang.String message, JSONObject additionalMetadata)
Log at TRACE level.static void
updateConfigFromServer()
Get and apply the configuration from the IBM MobileFirst Platform Server.void
warn(java.lang.String message)
Log at WARN level.void
warn(java.lang.String message, JSONObject additionalMetadata)
Log at WARN level.void
warn(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at WARN level.
-
-
-
Method Detail
-
getInstance
public static Logger getInstance(java.lang.String tag)
Get or create an instance of this logger. If an instance already exists for 'tag' parameter, that instance will be returned.- Parameters:
tag
- the package or tag that should be printed with log messages. The value is passed through to android.util.Log and persistently recorded when log capture is enabled.- Returns:
- an instance of this class
-
setContext
public static void setContext(Context _context)
Context object must be set in order to use the Logger API. This is called automatically by WL.init. setContext should only be called once. Any subsequent calls will be a no-op. If the configuration needs to be changed, use the getters and setters provided.- Parameters:
_context
- Android Context object
-
setLevel
public static void setLevel(Logger.LEVEL desiredLevel)
Set the level and above at which log messages should be saved/printed. For example, passing LEVEL.INFO will log INFO, WARN, ERROR, and FATAL. A null parameter value is ignored and has no effect.- Parameters:
desiredLevel
- @see LEVEL
-
getLevel
public static Logger.LEVEL getLevel()
Get the current Logger.LEVEL.- Returns:
- Logger.LEVEL
-
setCapture
public static void setCapture(boolean _capture)
Global setting: turn persisting of log data passed to this class's log methods on or off.- Parameters:
_capture
- flag to indicate if log data should be saved persistently
-
setAutoSendLogs
public static void setAutoSendLogs(boolean _autoSendLogs)
Global setting: turn Auto Log Send on and off.- Parameters:
_autoSendLogs
- flag to indicate if log data should be sent automatically after each successful resource request, if no logging has occurred within 60 seconds.
-
getCapture
public static boolean getCapture()
Get the current value of the capture flag, indicating that the Logger is recording log calls persistently. Default behavior is to retrieve on successful WLClient.connect and WLClient.invokeProcedure.- Returns:
- current value of capture flag
-
setFilters
public static void setFilters(java.util.HashMap _filters)
Filter on packages at and above designated LEVEL. This is a white list. Any package not listed in the filters will not be logged. Pass null or an empty HashMap parameter to remove filters and resume logging at the default LEVEL.- Parameters:
_filters
- set of filters and associated level (and above) to allow for logging
-
getFilters
public static java.util.HashMap getFilters()
Get the current list of filters.- Returns:
- map of white list package filters and the designated LEVEL
-
setMaxFileSize
public static void setMaxFileSize(int bytes)
Set the maximum size of the local log file. Once the maximum file size is reached, no more data will be appended. Consider that this file is sent to a server.- Parameters:
bytes
- maximum size of the file in bytes, minimum 10000
-
getMaxFileSize
public static int getMaxFileSize()
Get the current setting for the max file size threshold.- Returns:
- current max file size threshold
-
send
public static void send()
Send the accumulated log data when the persistent log buffer exists and is not empty. The data accumulates in the log buffer from the use ofLogger
with capture (seeLogger.setCapture(boolean)
) turned on.
-
send
public static void send(com.worklight.wlclient.WLRequestListener listener)
SeeLogger.send()
- Parameters:
listener
- WLRequestListener which specifies an onSuccess callback and an onFailure callback (seeWLRequestListener
)
-
updateConfigFromServer
public static void updateConfigFromServer()
Get and apply the configuration from the IBM MobileFirst Platform Server. The configuration comes from the use of the "Config Profiles" tab in the IBM MobileFirst Platform administrative console.
-
sendIfUnCaughtExceptionDetected
@Deprecated public static void sendIfUnCaughtExceptionDetected(Context context)
Deprecated. since version 6.2; useLogger.send()
withLogger.isUnCaughtExceptionDetected()
conditional instead.Send the log file when there is an uncaught exception detected, and was recorded to the log buffer due to capture being turned on at the time of the uncaught exception.
This is a convenience method so that callers may place a single line of code at the point in their application where they want to call it.
- Parameters:
context
- the Android Context in which this method should be run; typically an Activity instance.
-
isUnCaughtExceptionDetected
public static boolean isUnCaughtExceptionDetected()
Ask the Logger if an uncaught exception, which often appears to the user as a crashed app, is present in the persistent capture buffer. This method should not be called beforeLogger.setContext(Context)
. If it is called too early, an error message is issued and false is returned.- Returns:
- boolean if an uncaught exception log entry is currently in the persistent log buffer
-
fatal
public void fatal(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at FATAL level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log outputt
- a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
-
error
public void error(java.lang.String message)
Log at ERROR level.- Parameters:
message
- the message to log
-
error
public void error(java.lang.String message, JSONObject additionalMetadata)
Log at ERROR level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log output
-
error
public void error(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at ERROR level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log outputt
- a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
-
warn
public void warn(java.lang.String message)
Log at WARN level.- Parameters:
message
-
-
warn
public void warn(java.lang.String message, JSONObject additionalMetadata)
Log at WARN level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log output
-
warn
public void warn(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at WARN level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log outputt
- a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
-
info
public void info(java.lang.String message)
Log at INFO level.- Parameters:
message
- the message to log
-
info
public void info(java.lang.String message, JSONObject additionalMetadata)
Log at INFO level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log output
-
log
public void log(java.lang.String message)
Log at LOG (Android VERBOSE) level.- Parameters:
message
- the message to log
-
log
public void log(java.lang.String message, JSONObject additionalMetadata)
Log at LOG (Android VERBOSE) level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log output
-
debug
public void debug(java.lang.String message)
Log at DEBUG level.- Parameters:
message
- the message to log
-
debug
public void debug(java.lang.String message, JSONObject additionalMetadata)
Log at DEBUG level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log output
-
debug
public void debug(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
Log at DEBUG level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log outputt
- a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
-
trace
public void trace(java.lang.String message)
Log at TRACE level.- Parameters:
message
- the message to log
-
trace
public void trace(java.lang.String message, JSONObject additionalMetadata)
Log at TRACE level.- Parameters:
message
- the message to logadditionalMetadata
- to append to log output
-
-