External Logging

You can persist your
Layer7 Live API Creator
log messages by creating a logger for externalizing your API logs. Having your API logs in a central repository can help you identify API errors and error frequency, as well as help you narrow down the rules or SQL execution that are causing the API errors.
Layer7 Live API Creator
uses the Apache Log4j 2 framework for API-level logging.
For more information about the Log4j 2 framework, see the Apache Log4j 2 documentation.
In this article:
3
Configure External Logging
Use the following process to configure external logging:
  1. Create the logging configuration file.
    If you are using the single-user version of
    Layer7 Live API Creator
    (the demonstration package) that is based on Jetty, you can skip this step. The demonstration package includes the the
    %JETTY_HOME%/caliveapicreator/resources/laclogging.xml
    logging configuration file.
Create the Logging Configuration File
Create the logging configuration file, and then modify it to include logger entries for each log type:
Log Type
Logger Name
Description
Application
lacapplogger
Logger for the API logs that are available in API Creator.
For more information about these logs, see View Logging Information.
System
lacsyslogger
Logger for internal system-specific log messages.
Listeners
laclistenerlogger
Outputs logs that listener execution generate.
For more information about listener logs, see Creating Listeners.
Timers
lactimerlogger
Outputs logs that timer execution generate.
For more information about timer logs, see Creating Timers.
Data source providers
lacdsplogger
Logger for events that are related to the data source providers that you have created. These events include Create, Read, Update, and Delete (CRUD) operations that have been performed against the endpoints that are connected using the data source provider.
For more information about data source providers, see Manage Data Source Providers.
Audit
lacauditlogger
Logger for auditing.
For more information about auditing, see View an Audit Trail of your Changes.
Usage data (telemetry)
lactelemetrylogger
Logger to capture the activities for sending usage data. If you are connected a proxy server that sends your usage data, and
Layer7 Live API Creator
cannot reach the proxy server,
Layer7 Live API Creator
logs an error in this logger and to the API Server console.
For more information about how to configure to send usage data, see Activate and Configure to Send Usage Data.
You can externalize these logs by specifying the logger to use the Log4j 2 appenders or you can create your own appender and point the logger to it.
The following XML snippet shows an example logger entry of a Log4j 2 configuration file that includes a logger entry for
Layer7 Live API Creator
logging:
<Logger name="lacapplogger" level="debug" additivity="false">
<AppenderRef ref="file" />
</Logger>
Layer7 Live API Creator
reads the appender that you created, the
lacapplogger
logger, and dynamically links the appenders of this logger to
Layer7 Live API Creator
.
The following table shows the Log4j 2 logger's log levels and how these levels map to logging log levels in
Layer7 Live API Creator
(from highest to lowest):
Log4j Log Level
Log Level in
Layer7 Live API Creator
ERROR
error
WARN
warning
INFO
info
DEBUG
debug
FINER
finer
TRACE
finest
For example, if you configure the Log4j 2 logger to use the
DEBUG
level,
Layer7 Live API Creator
logs the logs that are in the
debug
log level and lower to the logger.
For more information:
Example:
The following sample shows a logging configuration file that specifies the logger to use the log4j 2 appenders to push API log entries to a file in the server:
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="error" strict="true" name="Externalconfig">
<Properties>
<Property name="filename">/pathToLogfile/log_test_customer.log</Property>
</Properties>
<Filter type="ThresholdFilter" level="trace" />
<Appenders>
<Appender type="File" name="file" fileName="${filename}" createOnDemand="true">
<Layout type="PatternLayout">
<Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
</Layout>
</Appender>
</Appenders>
<Loggers>
<Logger name="lacapplogger" level="debug" additivity="false">
<AppenderRef ref="file" />
</Logger>
<Root level="error">
<AppenderRef ref="consoleout" />
</Root>
</Loggers>
</Configuration>
You can control the size of your log files by configuring a
RollingFileAppender
in your logging configuration file.
For more information, see the Apache Log4j 2 documentation.
Set the Absolute Path of the Logging Configuration File
Add the
LAC_LOGGING_CONFIG_FILE
option when you start API Server, specifying the absolute path of the configuration file, based on the Java container on which you are running
Layer7 Live API Creator
:
Create a logger for the demonstration package, Apache Tomcat, Oracle WebLogic, or JBoss/WildFly Java Containers
-DLAC_LOGGING_CONFIG_FILE=/<path_to_your_logging_configuration_file>/<configuration_file_name>
A logger is created.
For Tomcat running on a Windows platform, add the
LAC_LOGGING_CONFIG_FILE
Java option to your Tomcat properties, and then restart Tomcat.
For more information about how to set the absolute path of the logging configuration file using system properties in JBoss/WildFly, see the JBoss documentation.
Create a Logger for an IBM WebSphere Java container
Add your own application logger for
Layer7 Live API Creator
deployed on WebSphere application server.
Based on your WebSphere application server setup, you might need to perform extra configuration to create a logger for WebSphere. We recommend that you contact your WebSphere administrator before creating a logger for WebSphere.
In the WebSphere administrative console, navigate to the Java virtual machine (JVM) Custom Properties page and ensure that WebSphere initializes external Log4j 2 configuration by enabling the following system property:
-DLAC_LOGGING_CONFIG_FILE=/<path_to_your_logging_configuration_file>/<logging_configuration_file_name
For more information about how to add system properties to the JVM, see the IBM documentation.
A logger for WebSphere is created.
For more information about this and other options that you can add when you start API Server, see API Server Startup Options.
View your Logs in a Central Repository
The format of the external logs are based on the appender to which your logger is pointing.
The following code snippet shows the format of a log message:
{CONTEXTUAL INFORMATION} LOG MESSAGE
The contextual information displays the context of the log event with a comma-separated list of properties and their values. The context contains the following properties:
Property
Description
Applicable Loggers
hostname
The hostname of the server that runs
Layer7 Live API Creator
and that generated the log event.
lacapplogger, lactimerlogger, laclistenerlogger
keyname
The key of the request the caused the log event.
lacapplogger
full-url
The full URL of the request the caused the log event.
lacapplogger
teamspace
The teamspace URL name of the API.
lacapplogger, lactimerlogger, laclistenerlogger
api
The URL name of the API.
lacapplogger, lactimerlogger, laclistenerlogger
listener/connection
The name of the listener or connection that generated the log event.
laclistenerlogger
parameters
The parameter of the listener or connection that generated the log event.
The parameters are comma separated key-value pairs enclosed in braces ({}).
laclistenerlogger
status
The status of the timer that generated the log event.
lactimerlogger
timer
The name of the timer that generated the log event.
lactimerlogger
The external log messages that
Layer7 Live API Creator
generates contain the following properties:
Property
Description
date
The timestamp for the log message.
millis
The event time in milliseconds (since 1970) for the log message.
sequence
The unique sequence number for the log message.
logger
The type of logger in
Layer7 Live API Creator
. For example,
admini
and
resrcs
.
level
The log level for the log message.
Values:
(From highest to lowest) error, warning, info, debug, finer, and finest
You can control the level of logging for the authentication tokens that you have created within your API.
For more information about how to control logging levels, see The apikeys Endpoint.
class
The class for the log message, using the following syntax:
host:<host name> - keyname:<key name> - http://localhost:8080/APIServer/rest/abl/admin/v2/admin:roles/?sysfilter=equal(project_ident:2013)&pagesize=10000" scope="external"><full URL>
method
The HTTP method (GET, PUT, POST, DELETE) for the log message.
thread
The thread identifier within the Java VM.
message
The log message. For example:
Resource Read demo:employee SQL: `dblocal_demo`.`employee` select 0 `EL__BATCHNUMBER`
,`employee_id`
,`login`
,`name` from `dblocal_demo`.`employee` `el__this` order by `login` limit 21
For timers, the external log messages that
Layer7 Live API Creator
generates contain the following properties. These properties are located in the
Additional Information
section:
Property
Description
scheduled_execution
The scheduled start timestamp for this timer.
execution_start
The actual execution start timestamp for this timer.
execution_end
The actual execution end timestamp for this timer.
status
The status of the execution.
The following code snippet shows an example of an external log message that contains properties for timers:
Additional Information:
{
"scheduled_execution": "2018-07-11T04:08:00+00:00",
"execution_start": "2018-07-11T04:08:00.312+00:00",
"execution_end": "2018-07-11T04:08:00.314+00:00",
"status": "OK"
}
Search a Log File
The following image shows an example of searching a log file using a REST resource or table endpoint:
example log.png
Improve Performance by Enabling Asynchronous Logging
If you have deployed
Layer7 Live API Creator
to a high-end machine, or to a cluster of high-end machines, that is equipped to handle a lot of traffic, you can improve the performance of
Layer7 Live API Creator
by enabling asynchronous logging. With asynchronous logging,
Layer7 Live API Creator
executes the input/output (I/O) operations in a separate thread.
Prerequisite:
You have reviewed the drawbacks of Log4j 2 asynchronous loggers. For more information, see the Apache Log4j 2 documentation.
Before starting API Server, add the following system property to the Java command line for your server:
-DLog4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector
Prevent Log Injection by Enabling Log Encoding
You can prevent log injection by enabling log encoding when you start API Server. Log injection is a mechanism whereby unvalidated user input to log files can allow an attacker to forge log entries or inject malicious content into the logs. By default, log encoding is disabled.
For more information about log injection, see the OWSAP org site.
Add the following option when you start API Server:
-DLAC_LOG_ENCODING_REQUIRED=true
For more information about this option and other options that you can add when you start API Server, see API Server Startup Options.