Skip to content

Configuring Logs


All WSO2 products are shipped with log4j2 logging capabilities, which generate server side logs. The file, which governs how logging is performed by the server can be found in the MI_HOME/conf directory.

Java logging and Log4j2 integration

In addition to the logs from libraries that use Log4j2, all logs from libraries that use the Java logging framework are also visible in the same log files. That is, when Java logging is enabled in Carbon, only the Log4j2 appenders will write to the log files. If the Java Logging Handlers have logs, these logs will be delegated to the log events of the corresponding Log4j2 appenders. A Pub/Sub registry pattern implementation has been used in the latter mentioned scenario to plug the handlers and appenders. The following default log4j2 appenders in the file are used for thisimplementation:

  • org.wso2.carbon.logging.appenders.CarbonConsoleAppender
  • org.wso2.carbon.logging.appenders.CarbonDailyRollingFileAppender

There are three main components when configuring log4j2: Loggers, Appenders, and Layouts.

Log4j2 Loggers

A Logger is an object used to log messages for a specific system or application component. Shown below is how a logger is configured in the file.

logger.<LOGGER_NAME>.level = INFO
logger.<LOGGER_NAME>.additivity = false
logger.<LOGGER_NAME>.appenderRef.<APPENDER_NAME>.ref = <APPENDER_NAME>

The logger attributes are described below.

name The name of the component (class) for which the logger is defined. That is, this logger is responsible for generating logs for the activities of the specified component.
level Allows to configure level (threshold). After you specify the level for a certain logger, a log request for that logger will only be enabled if its level is equal or higher to the logger’s level. If a given logger is not assigned a level, then it inherits one from its closest ancestor with an assigned level. Refer to the hierarchy of levels given above. See descriptions of the available log levels.
additivity Allows to inherit all the appenders of the parent Logger if set as 'True'.
appenderRef.APPENDER_NAME.ref This element is used to attach appenders to the logger.

The loggers are then listed in the file using the logger name as shown below.


Log4j2 Appenders

Log4j2 allows logging requests to print to multiple destinations. These output destinations are called 'Appenders'. All the defined appenders should be listed as shown below in the file.


If the output destination is in another environment (such as a cloud storage), you need to use custom log appenders.


Once the appenders are defined, a logger can refer the appender by using the appenderRef.APPENDER_NAME.ref element. You can also attach several appenders to one logger. For example, see how the root logger is linked to three appenders. Also, see how other loggers in the file are configured to use appenders.

Configuring Log4j2 Logs

The list below shows some of the main loggers (excluding the root logger) that are configured by default in the Micro Integrator. Open the file to see the complete list.

loggers = SERVICE_LOGGER, API_LOGGER, AUDIT_LOG, correlation, trace-messages, org.apache.synapse.transport.http.headers, org.apache.synapse.transport.http.wire, httpclient.wire.header, httpclient.wire.content,

The above logger configurations are explained below.

Root Logs

Given below is the root logger that is configured by default for the Micro Integrator. All loggers that do not have specific appenders defined will refer the appenders from the root logger.

This logger generates INFO-level logs and prints them to three destinations as per the appenders linked to the logger. The appenderRef.<APPENDER_NAME>.ref attribute is used for referring the appenders.

rootLogger.level = INFO
rootLogger.appenderRef.CARBON_CONSOLE.ref = CARBON_CONSOLE
rootLogger.appenderRef.CARBON_LOGFILE.ref = CARBON_LOGFILE
rootLogger.appenderRef.ERROR_LOGFILE.ref = ERROR_LOGFILE

Listed below are the default log destinations (appenders) used by the root logger:

  • CARBON_CONSOLE: This is the consoleAppender that prints logs to the server's console. These logs are printed to the wso2carbon.log file and the wso2error.log file through the two appenders given below.

    # CARBON_CONSOLE is set to be a ConsoleAppender using a PatternLayout.
    appender.CARBON_CONSOLE.type = Console = CARBON_CONSOLE
    appender.CARBON_CONSOLE.layout.type = PatternLayout
    appender.CARBON_CONSOLE.layout.pattern = [%d] %5p {%c{1}} - %m%ex%n
    appender.CARBON_CONSOLE.filter.threshold.type = ThresholdFilter
    appender.CARBON_CONSOLE.filter.threshold.level = DEBUG
  • CARBON_LOGFILE: This is a RollingFile appender that generates management logs of the server. Logs are printed to the <MI_HOME>/repository/logs/wso2carbon.log.

    # CARBON_LOGFILE is set to be a DailyRollingFileAppender using a PatternLayout.
    appender.CARBON_LOGFILE.type = RollingFile = CARBON_LOGFILE
    appender.CARBON_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/wso2carbon.log
    appender.CARBON_LOGFILE.filePattern = ${sys:carbon.home}/repository/logs/wso2carbon-%d{MM-dd-yyyy}.log
    appender.CARBON_LOGFILE.layout.type = PatternLayout
    appender.CARBON_LOGFILE.layout.pattern = [%d] %5p {%c} - %m%ex%n
    appender.CARBON_LOGFILE.policies.type = Policies
    appender.CARBON_LOGFILE.policies.time.type = TimeBasedTriggeringPolicy
    appender.CARBON_LOGFILE.policies.time.interval = 1
    appender.CARBON_LOGFILE.policies.time.modulate = true
    appender.CARBON_LOGFILE.policies.size.type = SizeBasedTriggeringPolicy
    appender.CARBON_LOGFILE.strategy.type = DefaultRolloverStrategy
    appender.CARBON_LOGFILE.strategy.max = 20
    appender.CARBON_LOGFILE.filter.threshold.type = ThresholdFilter
    appender.CARBON_LOGFILE.filter.threshold.level = DEBUG
  • ERROR_LOGFILE: This is a RollingFile appender that print the error logs to the <MI_HOME>/repository/logs/wso2error.log file.

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

Service Logs

This logger generates logs for services deployed in the Micro Integrator. It refers the SERVICE_LOGFILE appender and prints logs to the MI_HOME/repository/logs/wso2-mi-service.log file.


If you want to have separate log files for individual services, you need to add loggers for each service and then specify appenders for the loggers. Note that the service name has to be suffixed to SERVICE_LOGGER as follows: = SERVICE_LOGGER.TestProxy

See the instructions on monitoring per-service logs. SERVICE_LOGGER
logger.SERVICE_LOGGER.level = INFO
logger.SERVICE_LOGGER.additivity = false
# Appender config to SERVICE_LOGFILE
appender.SERVICE_LOGFILE.type = RollingFile = SERVICE_LOGFILE
appender.SERVICE_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/wso2-mi-service.log
appender.SERVICE_LOGFILE.filePattern = ${sys:carbon.home}/repository/logs/wso2-mi-service-%d{MM-dd-yyyy}.log
appender.SERVICE_LOGFILE.layout.type = PatternLayout
appender.SERVICE_LOGFILE.layout.pattern = [%d] %5p {%c} - %m%ex%n
appender.SERVICE_LOGFILE.policies.type = Policies
appender.SERVICE_LOGFILE.policies.size.type = SizeBasedTriggeringPolicy
appender.SERVICE_LOGFILE.strategy.type = DefaultRolloverStrategy
appender.SERVICE_LOGFILE.strategy.max = 20

API Logs

This logger generates logs for APIs deployed in the Micro Integrator. It refers the API_LOGFILE appender and prints logs to the MI_HOME/repository/logs/wso2-mi-api.log file.


If you want to have separate log files for individual APIs, you need to add loggers for each API and then specify appenders for the loggers. Note that the service name has to be suffixed to SERVICE_LOGGER as follows:

See the instructions on monitoring per-API logs. API_LOGGER
logger.API_LOGGER.level = INFO
logger.API_LOGGER.additivity = false
# Appender config to API_APPENDER
appender.API_LOGFILE.type = RollingFile = API_LOGFILE
appender.API_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/wso2-mi-api.log
appender.API_LOGFILE.filePattern = ${sys:carbon.home}/repository/logs/wso2-mi-api-%d{MM-dd-yyyy}.log
appender.API_LOGFILE.layout.type = PatternLayout
appender.API_LOGFILE.layout.pattern = [%d] %5p {%c} - %m%ex%n
appender.API_LOGFILE.policies.type = Policies
appender.API_LOGFILE.policies.size.type = SizeBasedTriggeringPolicy
appender.API_LOGFILE.strategy.type = DefaultRolloverStrategy
appender.API_LOGFILE.strategy.max = 20

Audit Logs

This is a RollingFile appender that writes logs to the MI_HOME/repository/logs/audit.log file. By default, the AUDIT_LOG logger is configured to write logs using this appender. = AUDIT_LOG
logger.AUDIT_LOG.level = INFO
logger.AUDIT_LOG.additivity = false
# Appender config to AUDIT_LOGFILE
appender.AUDIT_LOGFILE.type = RollingFile = AUDIT_LOGFILE
appender.AUDIT_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/audit.log
appender.AUDIT_LOGFILE.filePattern = ${sys:carbon.home}/repository/logs/audit-%d{MM-dd-yyyy}.log
appender.AUDIT_LOGFILE.layout.type = PatternLayout
appender.AUDIT_LOGFILE.layout.pattern = [%d] %5p {%c} - %m%ex%n
appender.AUDIT_LOGFILE.policies.type = Policies
appender.AUDIT_LOGFILE.policies.time.type = TimeBasedTriggeringPolicy
appender.AUDIT_LOGFILE.policies.time.interval = 1
appender.AUDIT_LOGFILE.policies.time.modulate = true
appender.AUDIT_LOGFILE.policies.size.type = SizeBasedTriggeringPolicy
appender.AUDIT_LOGFILE.strategy.type = DefaultRolloverStrategy
appender.AUDIT_LOGFILE.strategy.max = 20
appender.AUDIT_LOGFILE.filter.threshold.type = ThresholdFilter
appender.AUDIT_LOGFILE.filter.threshold.level = INFO

Correlations Logs

This loggger generates correlation logs for monitoring individual HTTP requests from the point that a message is received by the Micro Integrator until the corresponding response message is sent back to the original message sender. It refers the CORRELATION appender and prints logs to the MI_HOME/repository/logs/correlation.log file.


The maximum file size of the correlation log is set to 10MB in the following appender. That is, when the size of the file exceeds 10MB, a new log file is created. If required, you can change this file size. = correlation
logger.correlation.level = INFO
logger.correlation.appenderRef.CORRELATION.ref = CORRELATION
logger.correlation.additivity = false
# Appender config to put correlation Log.
appender.CORRELATION.type = RollingFile = CORRELATION
appender.CORRELATION.fileName =${sys:carbon.home}/repository/logs/correlation.log
appender.CORRELATION.filePattern =${sys:carbon.home}/repository/logs/correlation-%d{MM-dd-yyyy}.log
appender.CORRELATION.layout.type = PatternLayout
appender.CORRELATION.layout.pattern = %d{yyyy-MM-dd HH:mm:ss,SSS}|%X{Correlation-ID}|%t|%m%n
appender.CORRELATION.policies.type = Policies
appender.CORRELATION.policies.time.type = TimeBasedTriggeringPolicy
appender.CORRELATION.policies.time.interval = 1
appender.CORRELATION.policies.time.modulate = true
appender.CORRELATION.policies.size.type = SizeBasedTriggeringPolicy
appender.CORRELATION.strategy.type = DefaultRolloverStrategy
appender.CORRELATION.strategy.max = 20
appender.CORRELATION.filter.threshold.type = ThresholdFilter
appender.CORRELATION.filter.threshold.level = INFO

Additional configurations:

If required, you can change the default HTTP header (which is 'activity_id') that is used to carry the correlation ID by adding the following property to the deployment.toml file (stored in the MI_HOME/conf/ directory). Replace <correlation_id> with a value of your choice.


Once you have configured this logger, see the instructions on monitoring correlation logs.

Message Tracing Logs

This is a RollingFile appender that writes logs to the MI_HOME/repository/logs/wso2carbon-trace-messages.log file. By default, the trace.messages logger is configured to write logs using this appender. = trace.messages
logger.trace-messages.level = TRACE
logger.trace-messages.appenderRef.CARBON_TRACE_LOGFILE.ref = CARBON_TRACE_LOGFILE
# Appender config to CARBON_TRACE_LOGFILE
appender.CARBON_TRACE_LOGFILE.fileName = ${sys:carbon.home}/repository/logs/wso2carbon-trace-messages.log
appender.CARBON_TRACE_LOGFILE.filePattern = ${sys:carbon.home}/repository/logs/wso2carbon-trace-messages-%d{MM-dd-yyyy}.log
appender.CARBON_TRACE_LOGFILE.layout.type = PatternLayout
appender.CARBON_TRACE_LOGFILE.layout.pattern = [%d] %5p {%c} - %m%ex%n
appender.CARBON_TRACE_LOGFILE.policies.type = Policies
appender.CARBON_TRACE_LOGFILE.policies.time.type = TimeBasedTriggeringPolicy
appender.CARBON_TRACE_LOGFILE.policies.time.interval = 1
appender.CARBON_TRACE_LOGFILE.policies.time.modulate = true
appender.CARBON_TRACE_LOGFILE.policies.size.type = SizeBasedTriggeringPolicy
appender.CARBON_TRACE_LOGFILE.strategy.type = DefaultRolloverStrategy
appender.CARBON_TRACE_LOGFILE.strategy.max = 20

Wire Logs and Header Logs

These logs are disabled by default by setting the log level to OFF. You can enable these logs by changing the log level of the loggers to DEBUG.


It is not recommended to use these logs in production environments. Developers can enable them for testing and troubleshooting purposes. Note that appenders are not specified for these loggers, and therefore, the logs will be printed as specified for the root logger.

  • The following loggers configure wire logs for the Passthrough HTTP transport:


    The Passthrough HTTP transport is the main transport that handles HTTP/HTTPS messages in the Micro Integrator.

    # Following are to log HTTP headers and messages
  • The following loggers configure wire logs for the Callout mediator/MessageProcessor.

See the instructions on using wire logs to debug your integration solution during development.

Configuring HTTP Access Logs

Access logs related to service/API invocations are enabled by default in the Micro Integrator. Access logs for the PassThrough transport will record the request and the response on two separate log lines.

By default, access logs are printed to the http_acces_.log file (stored in the MI_HOME/repository/logs folder). If required, you can use the log4j2 configurations to print the access logs to other destinations. Simply apply the following logger with an appender.

  • Logger Name: PassThroughAccess
  • Logger Class: org.apache.synapse.transport.http.access

Customizing the Access Log Format

You can customize the format of this access log by changing the following property values in the MI_HOME/conf/ configuration file. If this file does not exist in the product by default, you can create a new file.

  1. Open the file and add the following properties.

    access_log_directory Add this property ONLY if you want to change the default location of the log file. By default, the product is configured to store access logs in the MI_HOME/repository/logs directory.

    The prefix added to the log file's name. The default value is as follows:


    The suffix added to the log file's name. The default value is as follows:


    The date format used in access logs. The default value is as follows:


    The attribute defines the format for the log pattern, which consists of the information fields from the requests and responses that should be logged. The pattern format is created using the following attributes:

    • A standard value to represent a particular string. For example, "%h" represents the remote host name in the request. Note that all the string replacement values supported by Tomcat are NOT supported for the PassThrough transport's access logs. The list of supported values are given below .

    • %{xxx}i is used to represent the header in the incoming request (xxx=header value).
    • %{xxx}o is used to represents the header in the outgoing request (xxx=header value).

    While you can use the above attributes to define a custom pattern, the standard patterns shown below can be used.

    By default, a modified version of the Apache combined log format is enabled in the ESB as shown below. Note that the "X-Forwarded-For" header is appended to the beginning of the usually combined log format. This correctly identifies the original node that sent the request (in situations where requests go through a proxy such as a load balancer). The "X-Forwarded-For" header must be present in the incoming request for this to be logged.

    access_log_pattern=%{X-Forwarded-For}i %h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"

  2. Restart the server.

  3. Invoke a proxy service or REST API that is deployed in the Micro Integrator. The access log file for the service/API will be created in the MI_HOME/repository/logs directory. The default name of the log file is http_access_.log .


    Note that there will be a delay in printing the logs to the log file.

Supported Log Pattern Formats

Attribute Description

Remote IP address


Local IP address


Bytes sent, excluding HTTP headers, or '-' if zero


Bytes sent, excluding HTTP headers


Cookie value


Accept header


Accept Encoding


Transfer Encoding


Remote host name (or IP address if enableLookups for the connector is false)


Remote logical username from identd (always returns '-')


Accept Language


Keep Alive


Request method (GET, POST, etc.)


Content Encoding


Request Element


HTTP status code of the response


Accept Chatset


Date and time, in Common Log Format


Time taken to process the request in seconds.


Remote user that was authenticated (if any), else '-'


Requested URL path


Local server name


Vary Header


Connection Header


Server Header

Updating the Log4j2 Log Level

You can dynamically update the log level for a specific logger by using the Micro Integrator dashboard or CLI. If you change the wire log configuration directly from the file (without using the dashboard or CLI), the Micro Integrator needs to be restarted for the changes to become effective.

Log Levels

The following table explains the log4j2 log levels you can use. Refer Log4j2 documentation for more information.

Level Description
OFF The highest possible log level. This is intended for disabling logging.
FATAL Indicates server errors that cause premature termination. These logs are expected to be immediately visible on the command line that you used for starting the server.
ERROR Indicates other runtime errors or unexpected conditions. These logs are expected to be immediately visible on the command line that you used for starting the server.
WARN Indicates the use of deprecated APIs, poor use of API, possible errors, and other runtime situations that are undesirable or unexpected but not necessarily wrong. These logs are expected to be immediately visible on the command line that you used for starting the server.
INFO Indicates important runtime events, such as server startup/shutdown. These logs are expected to be immediately visible on the command line that you used for starting the server . It is recommended to keep these logs to a minimum.
DEBUG Provides detailed information on the flow through the system. This information is expected to be written to logs only. Generally, most lines logged by your application should be written as DEBUG logs.
TRACE Provides additional details on the behavior of events and services. This information is expected to be written to logs only.

Using the dashboard

  1. Sign in to the Micro Integrator dashboard.
  2. Click Log Configs on the left-hand navigator to open the Logging Management window.

    change log level from dashboard

  3. Use the Search option to find the required logger, and change the log level as shown above.

Using the CLI

  1. Download and set up the Micro Integrator CLI.
  2. Use the mi log-level option in the CLI with the required commands as shown in the following examples:

    # Update the log level of an existing logger
    mi log-level update org-apache-coyote DEBUG

Updating the Threshold Level

The threshold value filters log entries based on the log level. This value is set for the log appender in the file. For example, a threshold set to 'WARN' allows the log entry to pass into the appender. If its level is 'WARN', 'ERROR' or 'FATAL', other entries will be discarded. This is the minimum log level at which you can log a message.

Shown below is how the log level is set to DEBUG for the CARBON_LOGFILE appender:

appender.CARBON_LOGFILE.filter.threshold.level = DEBUG

Updating the Log4j2 Log Pattern

The log pattern defines the output format of the log file. This is the layout pattern that describes the log message format.

Identifying forged messages: The conversion character 'u' can be used in the pattern layout to log a UUID. For example, the log pattern can be  [%u] [%d] %5p {%c} - %m%ex%n, where [%u] is the UUID.

Hide Current Parameters in the Printed Log

By default, when an error occurs while invoking a dataservice, the Micro Integrator logs a set of parameters in the error message.

For example:

Source Data Service:-
Name: RDBMSSample
Location: /RDBMSSample.dbs
Description: N/A
Default Namespace:
Current Request Name: _addEmployee
Current Params: {firstName=Will, lastName=Smith, salary=1200, [email protected]}

You can hide the 'Current Params' in the printed logs by passing the following system property:

-Ddss.disable.current.params=true \

Using Custom Log Appenders

Custom log appenders for Log4j2 can be used to store application logs in various environments/systems such as cloud storages.

However, since WSO2 Micro Integrator works in an OSGi environment, such Log4j2 extensions cannot be used as they are. Therefore, you need to modify those extensions to be compatible with WSO2 Micro Integrator. Follow the steps given below to modify an existing Log4j2 extension:

  1. In the custom log appender, open the pom.xml file of the module that contains the Log4j2Appender class.

  2. Under the build section, add maven-compiler-plugin and maven-bundle-plugin as follows.

  3. Rebuild the related module and copy the built JAR file from the target directory to <MI_HOME>/dropins directory.

  4. Configure the custom appender in the file as follows.

    appender.log4j2Custom.type = Log4j2Appender = log4j2Custom
    appender.log4j2Custom.layout.type = PatternLayout
    appender.log4j2Custom.layout.pattern = [%d] %5p {%c} - %m%ex%n
  5. The custom appender should be added to the list of registered appenders in the file as shown below.

    appenders = log4j2Custom, ....
  6. Restart the server.

What's Next?

Once you have configured the logs, you can start using the logs.