External Logging

You can persist your  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 to help you narrow down the rules or SQL execution that are causing the API errors.
lac52
You can persist your 
CA 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 to help you narrow down the rules or SQL execution that are causing the API errors.
 
CA 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. If you are using the single-user version of 
    CA 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.
Cluster synchronization
lacclustersynclogger
To externalize your Hazelcast logs, include this logger name in the logging configuration file.
For more information about how to configure 
CA Live API Creator
 to run as a cluster, see Configure to Run as a Cluster.
Data source providers
lacdsplogger
Logger for events that are related to the data source providers that you have created.
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 
CA Live API Creator
 cannot reach the proxy server, 
CA 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 
CA Live API Creator
 logging:
<Logger name="lacapplogger" level="debug" additivity="false">
<AppenderRef ref="file" />
</Logger>
CA Live API Creator
 reads the appender that you created, the 
lacapplogger
 logger, and dynamically links the appenders of this logger to 
CA Live API Creator
.
The following table shows the Log4j 2 logger's log levels and how these levels map to logging log levels in 
CA Live API Creator
 (from highest to lowest):
Log4j Log Level
Log Level in 
CA 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, 
CA 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>
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 
CA 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 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 
CA 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 
CA 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 
CA 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 
CA 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 the logging level, see The apikeys Endpoint.
class
The class for the log message, using the following syntax:
host:<host name> - keyname:<key name> - <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 
CA 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 
CA 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 
CA Live API Creator
 by enabling asynchronous logging. With asynchronous logging, 
CA 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.