What kind of logging required to your WSO2 API-Manager based solution

source : https://www.magna5global.com/developing-an-effective-it-monitoring-strategy/in-the-system-control-room-technical-operator-stands-and-monitors-various-activities-showing-on-multiple-displays-with-graphics-administrator-monitors-work-of-artificial-intelligence-big-data-minin/

Logging is a crucial factor when designing a solution since that is the way to identifying errors, security threats, and usage patterns of deployment. In the WSO2 servers, there are few main logging types as below.

• Carbon Logs : This is used for administrative and server-side activities[1]. The respective log file can be identified as the ‘wso2carbon.log’ located in the ‘<APIM_HOME>/repository/logs’ directory.
• Debug Logs for specific classes or packages : This can be used for debugging and troubleshooting purposes of the server. In the WSO2-APIM there are special debug logs that popular as ‘Gateway wire logs’[1]. This is also identified as a debug logs for a special classes implemented in the synapse engine, named as ‘org.apache.synapse.transport.http.wire’ and ‘org.apache.synapse.transport.http.headers’. By default, these logs are also printed in the log file of ‘wso2carbon.log’.
• HTTP Access Logs : This will help to identify and monitor the application’s usage such as the persons who access it, how many hits it received, what the errors are, etc by logging the HTTP requests and responses[2]. The respective log files can be identified as ‘http_access_<DATE>.log’ from the location of ‘<APIM_HOME>repository/logs/’ directory.
• Audit Logs : The audit logs can be used to track aset of actions performed on the server. From the APIM perspective, this can be used to track the user actions for the Publisher-portal and the Dev-portal[3]. The respective log file can be identified as ‘audit .log’ from the location of ‘<APIM_HOME>repository/logs/’ directory.
• Correlation Logs : The ‘Observability feature’[4] is the popular name for correlation logs. For the debugging purposes, it will generate a random ‘correlation ID’ for each transaction and that will help to track the entire call. Also using the correlation logs we can mainly track the Method Calls, External Calls (HTTP/HTTPS), and Database Calls (JDBC and LDAP) in a more detailed manner. The respective log files can be identified as ‘correlation.log’ from the location of ‘<APIM_HOME>repository/logs/’ directory.

Depending on the requirement and the deployment we need to select the type of log.

On-promise deployments

Also if the deployment consists of on-promise infrastructure, most of us would like to have separate log files for specific classes or packages(eg: wire logs to a separate log file) as that will help us to troubleshoot and maintain the system. In that case please find the guidance to use a separate log file(synapse-wire.log’) for the wso2 wire logs.

Perform the below actions for the ‘log4j2.properties’ file in ‘<APIM-3.1.0_HOME>/repository/conf’ directory.

• Add a new ‘appender’ name of ‘WIRE_LOGFILE’ to the ‘appenders’ section as below.

appenders=CARBON_CONSOLE, .... , BOTDATA_APPENDER, WIRE_LOGFILE

• Add the ‘WIRE_LOGFILE’ appender configurations as below.

# Appender config to WIRE_LOGFILE
appender.WIRE_LOGFILE.type = RollingFile
appender.WIRE_LOGFILE.name = WIRE_LOGFILE
appender.WIRE_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/synapse-wire.log
appender.WIRE_LOGFILE.filePattern = ${sys:carbon.home}/repository/logs/synapse-wire-%d{MM-dd-yyyy}.log
appender.WIRE_LOGFILE.layout.type = PatternLayout
appender.WIRE_LOGFILE.layout.pattern = [%d] %5p {%c} - %m%ex%n
appender.WIRE_LOGFILE.policies.type = Policies
appender.WIRE_LOGFILE.policies.time.type = TimeBasedTriggeringPolicy
appender.WIRE_LOGFILE.policies.time.interval = 1
appender.WIRE_LOGFILE.policies.time.modulate = true
appender.WIRE_LOGFILE.policies.size.type = SizeBasedTriggeringPolicy
appender.WIRE_LOGFILE.policies.size.size=10MB
appender.WIRE_LOGFILE.strategy.type = DefaultRolloverStrategy
appender.WIRE_LOGFILE.strategy.max = 20
appender.WIRE_LOGFILE.filter.threshold.type = ThresholdFilter
appender.WIRE_LOGFILE.filter.threshold.level = DEBUG

• Add and update the below segment related to the logger named ‘synapse-wire’.

logger.synapse-wire.name = org.apache.synapse.transport.http.wire
logger.synapse-wire.level = DEBUG
logger.synapse-wire.appenderRef.WIRE_LOGFILE.ref = WIRE_LOGFILE
logger.synapse-wire.additivity = false

• Update the ‘loggers’ section by adding the logger name of ‘synapse-wire’ as below.

loggers = AUDIT_LOG, trace-messages, …. correlation, synapse-wire

By following the same steps, you will be able to add any kind of log file for the required classes or packages by changing the logger class name accordingly (ex: ‘org.apache.synapse.transport.http.wire’).

Containerized deployments

When we having a containerized deployment, in order to analyze or troubleshoot the server, we need to log in to the container and extract the relevant logs from the file system of the container. To overcome that, we have few options as below.

1. Mount the log files of the container to some other location.

This way is ideal when you are having a mechanism to analyze and monitor the system using the files. Also, this will keep the log files for future purposes like auditing the server and more.

2. Redirect the default-logs to the console.

If we are having a mechanism to analyze and monitor the system using console logs, this way will be ideal. You can refer to the below sample to redirect the same above wire logs to the console instead of the ‘synapse-wire.log’ file.

• No need to follow the first and second steps on the previous section, since we do not need to add new ‘appender’ configurations.
• Here we will be used the default appender configurations related to the ‘CARBON_CONSOLE’.
• Add and update the below segment related to the logger named ‘synapse-wire’.

logger.synapse-wire.name = org.apache.synapse.transport.http.wire
logger.synapse-wire.level = DEBUG
logger.synapse-wire.appenderRef.WIRE_LOGFILE.ref = CARBON_CONSOLE
logger.synapse-wire.additivity = false

• Update the ‘loggers’ section by adding the logger name of ‘synapse-wire’ as below.

loggers = AUDIT_LOG, trace-messages, …. correlation, synapse-wire

If we need to change some other logs, we just need to change the default ‘appenderRef’ value to the ‘CARBON_CONSOLE’ as above.

Hope this post helps to get a more clear understanding of the logging and how to configure logs as per the deployment/requirement.

References

[1] — https://apim.docs.wso2.com/en/latest/administer/logging-and-monitoring/logging/setting-up-logging/

[2] — https://apim.docs.wso2.com/en/latest/administer/logging-and-monitoring/logging/monitoring-http-access-logs/

[3] — https://apim.docs.wso2.com/en/latest/administer/logging-and-monitoring/logging/monitoring-audit-logs/

[4] — https://apim.docs.wso2.com/en/latest/administer/logging-and-monitoring/monitoring/working-with-observability/