Using the SAP Logging API¶
The SDK uses Simple Logging Facade for Java (SLF4J) for its logging API and logback-android
for the logging
implementation. For more information about SLF4J, refer to the SLF4J documentation.
For more information about logback-android
, refer to the documentation on the
logback-android
site.
Notes
- If you don't need to upload logs, you don't have to use the SDK logging API. Make sure you don't
call either of the
Logging.initialize()
methods orLogService
. It will be up to you to configure the logging implementation. - If you want to use another SLF4J logging implementation instead of
logback
, such as Log4j orjava.util.logging
, you can do that too. In that case you will not be able to use the SDK logging API. Make sure you don't call either of theLogging.initialize()
methods orLogService
, and make sure you don't add the `logback``dependencies to your Gradle build. - You can use a logger other than
SLF4J
too, but you will not get any logging from the SDK if you do that. - If you want to implement your own log upload, see the documentation for Client Log Upload Service.
Prerequisites¶
To enable logging in your mobile app, you require SLF4J and logback-android
. To install logback-android
, go to
logback-android
and follow the Quick Start instructions.
Adding Dependency to Your Project¶
To include SLF4J and logback
in your project, add the following dependency to your Gradle build:
dependencies {
implementation 'org.slf4j:slf4j-api:1.7.25'
implementation 'com.github.tony19:logback-android:2.0.0'
}
Using LogService
Facade¶
LogService
helps initialize logging and provides feature of auto upload enabled by default. When log file reaches
threshold size of 100 KB by default, which is configurable by Logging.ConfigurationBuilder
, it will trigger the
automatic log upload process.
public LogService setAutoUpload(@NonNull boolean autoUpload) {...}
The client code may look like:
LogService logService = new LogService();
logService.setAutoUpload(true);
SDKInitializer.INSTANCE.start(application, new MobileService[]{logService}, null);
val logService = LogService().apply {
this.setAutoUpload(true)
}
SDKInitializer.start(this, logService)
When using LogService
with onboarding flows2
,
logging configurations will be set by log policy on mobile services. Client code can also call this method to override
parameters on mobile services.
public LogService setLogPolicy(@NonNull LogPolicy logPolicy) {...}
Getting Named Logger¶
In classes where you want to add logging, get a named logger from the LoggerFactory
and then log at the level you need
to. For example:
org.slf4j.Logger log = LoggerFactory.getLogger("com.my.package");
log.info("info");
log.warn("warn");
log.debug("debug");
log.error("error");
log.trace("trace");
log.info("info {}", "info");
log.warn("warn {}", "warn");
log.debug("debug {}", "debug");
log.error("error {}", "error");
log.trace("trace {}", "trace");
val log = LoggerFactory.getLogger("com.my.package")
log.info("info")
log.warn("warn")
log.debug("debug")
log.error("error")
log.trace("trace")
log.info("info {}", "info")
log.warn("warn {}", "warn")
log.debug("debug {}", "debug")
log.error("error {}", "error")
log.trace("trace {}", "trace")
The mobile service does not support trace logging. Any messages logged as "trace" will be converted to "path" when uploaded.
Initializing Logging¶
The best place to initialize logging is in a custom Application's onCreate
method. To set up logging, call one of the following initialize methods:
Logging.initialize(context);
Logging.initialize(context)
or
Logging.initialize(
context,
new Logging.ConfigurationBuilder().initialLevel(Level.DEBUG).logToConsole(true).build()
);
Logging.initialize(
context,
Logging.ConfigurationBuilder().initialLevel(Level.DEBUG).logToConsole(true).build()
)
But if LogService
is included in the SDKInitializer.start
method, there is no need to call the initialize
method again in the client code.
The simple form of initialize
sets the log level to ERROR
. It uses four rolling log files with maximum file size of
1000 KB for each log file. This method provides no console output and no expiration. It is the recommended setting for
production code.
You can also set one or more configuration option using a Logging.ConfigurationBuilder
to build a parameter list. Any
configuration option not set will use the default. See the Logging
API
documentation for more details.
Logs are written to a rolling log. Logs are written to a maximum size. When the limit is reached, the oldest log entries
(the oldest log file) are deleted to make room for new log entries. The maximum size is logFileCount
x logFileSize
.
Setting Logging Levels¶
Logging level controls which log messages are written to the log. For example, when the log level is set to ERROR
,
DEBUG
messages are not written to the log. See the logback
documentation for more information.
Logging.initialize() sets the initial level for the whole application. You can also do this using the following code:
Logging.getRootLogger().setLevel(Level.ERROR);
Logging.getRootLogger().level = Level.ERROR
Customizing Console Logging¶
You can customize what is written to the console and how it is written out. To see the current format, call:
String pattern = Logging.getConsoleLoggerPattern();
val pattern = Logging.getConsoleLoggerPattern()
To set the format, call:
Logging.setConsoleLoggerPattern(pattern);
Logging.setConsoleLoggerPattern(pattern)
For more information on patterns, go to the logback
website.