---
schema_version: "1"
id: 7d54dcd1e6bbe3585fbb7a3b526dd4080ba71cd0469667f762826f59ada36825
title: Configuring Logging
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/latest/logging-in-mule.md
canonical_url: https://docs.mulesoft.com/mule-runtime/latest/logging-in-mule
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 923723478065caffdb1e569713a03391534f4880a2ff23ba56a2900a49a4ec0c
description: MuleSoft Documentation Site
release: "4.13"
latest: true
---
---
product: Mule Runtime
version: 4.13
is-latest-version: true
keywords: mule, studio, logger, logs, log, notifications, errors, debug
---

# Configuring Logging

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

MuleSoft provides application logs and a runtime log to help you monitor and troubleshoot your Mule
applications and the Mule instance.

## App Logs

Every app that you build in Studio comes with its own `log4j2.xml` configuration file, which defines
how the app log is written. The app log contains information about any errors raised in the app
(unless you have app logic to handle those errors). It also contains anything you explicitly log in
the app.

Mule automatically logs multiple messages and specific elements in your app flows to help you debug
and keep track of events. You can also include the [Logger component](https://docs.mulesoft.com/mule-runtime/latest/logger-component-reference)
anywhere in a flow and set it up to output any message you want.

You can view an app log as follows:

- If you’re running an app from Anypoint Studio, the output from the app log is visible in Anypoint
  Studio’s console window.

- If you’re using Mule from the command line to run an app, the app log is visible in your OS
  console.

By default, Mule stores application log files in the following location:
`MULE_HOME/logs/<app-name>.log`. You can customize the log file path in the `log4j2.xml` file of the
Mule app.

If you deploy your app to CloudHub or CloudHub 2.0, see
[View Log Data](https://docs.mulesoft.com/cloudhub/viewing-log-data). If you deploy your app to Runtime Fabric, see
[Integrating with Your Logging System Using Log4j](https://docs.mulesoft.com/runtime-fabric/latest/use-log4j-appender).

## Runtime Log

The runtime log (`mule_ee.log`) contains information about the apps and lifecycle events. For
example, the log records an entry when a Mule service or app starts, deploys, stops, or undeploys.

The runtime log configuration is located in the `log4j2.xml` file, in the `/conf` directory. You can
customize this file when running Mule on-premises.

### View the Runtime Log in Anypoint Studio

Click **Anypoint Studio > About Anypoint Studio > Installation Details > Configuration > View Error
Log**:

![An Anypoint Studio error log viewer interface](/mulesoft/current/en-us/mule-runtime/latest/_images/logging-in-mule-view-error-log.png)

## How Logging Works in Mule

Mule uses `slf4j`, which is a logging facade that discovers and uses a logging strategy from the
classpath, such as Apache Log4j 2 or the JDK Logger. By default, Mule includes Log4j 2, which is
configured with a file called `log4j2.xml`.

In the `log4j2.xml` file, you define:

- What kinds of messages to log (the log level)

- How to log the messages (asynchronously or synchronously)

- Where to log the messages, such as to the console or disk, or to an endpoint or database (the
  appenders)

## Synchronous Versus Asynchronous Logging

By default, Mule logs messages asynchronously. When logging synchronously, the execution of the
thread that is processing your message is interrupted to wait for the log message to be fully
handled before it can continue:

![A synchronous logging in a threaded environment](/mulesoft/current/en-us/mule-runtime/latest/_images/logger-synch.png)

When logging asynchronously, the logging operation occurs in a separate thread, so the message can
process before the logging completes:

![An asynchronous logging in a threaded environment](/mulesoft/current/en-us/mule-runtime/latest/_images/logger-asynch-alternativo.png)

In most situations, MuleSoft recommends that you use **asynchronous logging** because it
substantially improves the throughput and lowers the latency of message processing.

When asynchronous logging is used, some actions might not be logged if there is a system crash. This
situation occurs because log writing is performed on a separate thread that runs independently of
other actions. See [Exception Handling with Asynchronous Logging](#exception_handling) for
information on mitigating this issue.

If you use app logs as audit trails, configure your app to always use **synchronous** logging. This
prevents the loss of any log messages.

> [!NOTE] Mule 4 introduced thread-local functionality to optimize the memory usage of log4j. To
> enhance the use of this feature, you can set the system property
> `AsyncLoggerConfig.RingBufferSize` (see [Configuring Properties](https://docs.mulesoft.com/mule-runtime/latest/configuring-properties)). `20000`
> is the suggested value, but you need to tune it to meet your needs.

### Performance Tests

The chart below shows the performance difference between synchronous and asynchronous logging, and
how much latency increased as more concurrent messages were added. In this test, an app logged about
one million messages, using an increasingly higher amount of threads on each run. Each transaction
resulted in 1000 messages.

![A line chart comparing latency versus concurrency](/mulesoft/current/en-us/mule-runtime/latest/_images/logging-latency-vs-concurrency.png)

As indicated by the chart, the results of logging asynchronously are significantly closer to the
results of not logging at all.

## Configuring Custom Logging Settings

By default, logging in Mule is done asynchronously and at a level greater than or equal to INFO. The
default log level discards log messages at the DEBUG or TRACE level.

To change this behavior, edit the `log4j2.xml` file, for example, to use synchronous logging, change
the log level, or define custom logger categories. For the runtime, this file is
`$MULE_HOME/conf/log4j2.xml`. If you don’t edit this file, Mule uses the default configuration.

In Anypoint Studio, `log4j2.xml` appears in the `src/main/resources` path of each Mule project.

The default configuration defines all loggers, including the root logger, as asynchronous. You can
override this configuration at the domain or app level. To use a custom configuration file at the
app level, add a `logConfigFile` entry to the `mule-artifact.json` file. The path is relative to the
root of the app. For example:

```json
{
  "minMuleVersion": "4.0.0",
  "logConfigFile": "custom-log4j2.xml"
}
```

### Change the Log Level

To change the log level, modify the `level` value of the logger for the package you want to
configure. For example, to change the runtime log level, modify these loggers in the `log4j2.xml`
file:

```xml
  <AsyncLogger name="org.mule" level="INFO"/>
  <AsyncLogger name="com.mulesoft" level="INFO"/>
```

Accepted values, from most to least verbose, are: `TRACE`, `DEBUG`, `INFO`, `WARN`, and `ERROR`.

To change the log level only for specific connectors, see
[Enable Verbose Logging](https://docs.mulesoft.com/mule-runtime/latest/enable-verbose-logging).

### Use Synchronous Logging

To log synchronously, use the `Logger` and `Root` elements instead of `AsyncLogger` and `AsyncRoot`
in your `log4j2.xml` file.

This example makes all logging synchronous:

```xml
<Configuration>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%-5p %d [%t] %c: %m%n"/>
        </Console>
    </Appenders>

    <Loggers>
        <Logger name="org.mule" level="INFO"/>
        <Logger name="com.mulesoft" level="INFO"/>

        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>
```

### Default Configuration

The following is the default configuration for the `log4j2.xml` file:

```xml
<Configuration>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%-5p %d [%t] %c: %m%n"/>
        </Console>
    </Appenders>

    <Loggers>

        <!-- CXF is used heavily by Mule for web services -->
        <AsyncLogger name="org.apache.cxf" level="WARN"/>

        <!-- Apache Commons tend to make a lot of noise which can clutter the log-->
        <AsyncLogger name="org.apache" level="WARN"/>

        <!-- Reduce startup noise -->
        <AsyncLogger name="org.springframework.beans.factory" level="WARN"/>

        <!-- Mule classes -->
        <AsyncLogger name="org.mule" level="INFO"/>
        <AsyncLogger name="com.mulesoft" level="INFO"/>

        <AsyncRoot level="INFO">
            <AppenderRef ref="Console"/>
        </AsyncRoot>
    </Loggers>

</Configuration>
```

## Configuring Logs for the Runtime Manager Agent

> [!NOTE] This configuration is only valid when using the Runtime Manager agent 1.5.2 and later.

To log the Runtime Manager Agent state in a location other than the default `mule_agent.log` file,
configure the `$MULE_HOME/conf/log4j2.xml` file to include a new Log4j 2 Appender called
`mule-agent-appender`. If included, the Runtime Manager Agent plugin uses this appender to log its
state.

The `log4j2.xml` file should include something like the following snippet to enable this
functionality:

```xml
<Configuration>
    <Appenders>

      (...)

        <RollingFile name="mule-agent-appender" fileName="${env:MULE_HOME}/logs/custom_mule_agent.log" filePattern="${env:MULE_HOME}/logs/custom_mule_agent.log-%d{MM-dd-yyyy}.log.gz">
            <PatternLayout>
                <Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
            </PatternLayout>
            <Policies>
                <TimeBasedTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="250 MB"/>
            </Policies>
        </RollingFile>
    </Appenders>

    <Loggers>

        (...)

        <AsyncLogger name="com.mulesoft.agent" additivity="TRUE" level="ALL">
          <AppenderRef ref="mule-agent-appender" />
        </AsyncLogger>

        <AsyncRoot level="INFO">
          <AppenderRef ref="Console"/>
        </AsyncRoot>
    </Loggers>
</Configuration>
```

The above example makes the Runtime Manager agent log its state to a rolling log file in
`$MULE_HOME/logs/custom_mule_agent.log`. The file rolls over daily, or sooner if it reaches 250 MB.

For other Log4j 2 appender configurations, see the
[Apache Log4j 2 Appenders documentation](https://logging.apache.org/log4j/2.x/manual/appenders.html).

## Exception Handling with Asynchronous Logging

If you’re using asynchronous logging and experience a system crash that might have caused incomplete
logs, the LMAX `ExceptionHandler` handler can help. By default, Mule registers this handler to log
events to the disk, console, and `logs/mule_ee.log`. To provide your own exception handler, set the
system property `AsyncLoggerConfig.ExceptionHandler` to the canonical name of a class that
implements the interface.

The default exception handler,
`org.mule.runtime.module.launcher.api.log4j2.AsyncLoggerExceptionHandler`, logs the failure through
the Log4j 2 `StatusLogger`. Use it as a reference for your own implementation:

```java
import com.lmax.disruptor.ExceptionHandler;

import org.apache.logging.log4j.status.StatusLogger;

public class AsyncLoggerExceptionHandler implements ExceptionHandler {

  private static final StatusLogger LOGGER = StatusLogger.getLogger();

  @Override
  public void handleEventException(Throwable ex, long sequence, Object event) {
    LOGGER.error("Failed to asynchronously log message: " + event, ex);
  }

  @Override
  public void handleOnStartException(Throwable ex) {
    LOGGER.error("Failed to start asynchronous logger", ex);
  }

  @Override
  public void handleOnShutdownException(Throwable ex) {
    LOGGER.error("Failed to stop asynchronous logger", ex);
  }
}
```

There is a performance-reliability trade-off between asynchronous and synchronous logging. If the
risk of losing log messages is a serious issue, then configure your loggers to be synchronous. You
can have a mix of both synchronous and asynchronous logging.

## Configuration Reloading

Log4j 2 can check the `log4j2.xml` file for changes at a set interval and apply them without a
restart. To enable this behavior, add the `monitorInterval` attribute to the `log4j2.xml`
configuration file:

1.  In the Mule installation folder, open `conf/log4j2.xml`.

2.  Add the `monitorInterval` attribute, in seconds, to the `<Configuration>` element. For example:

    ```xml
    <?xml version="1.0" encoding="UTF-8"?>
    <Configuration monitorInterval="15">
        <Appenders>
           <Console name="Console" target="SYSTEM_OUT">
               <PatternLayout pattern="%-5p %d [%t] %c: %m%n"/>
           </Console>
        </Appenders>
    ...
    ```

    In this example, Log4j 2 checks for changes every 15 seconds.

3.  Save the file, and restart Mule so that it loads the `monitorInterval` setting.

    After this restart, Log4j 2 applies later changes to `log4j2.xml` automatically within the
    configured interval.

For more information, see the
[Apache Log4j 2 Configuration documentation](https://logging.apache.org/log4j/2.x/manual/configuration.html).

## Debugging Projects that Use the HTTP Connector

To debug projects that use the HTTP connector, you might want to make the logging more verbose than
usual and track all of the behavior of the HTTP connector’s `http-listener` and `http-request`
operations in your project. See
[HTTP Connector Troubleshooting Guide](https://docs.mulesoft.com/http-connector/1.10/http-troubleshooting) for
information.

## Request and Response Logging for SOAP

Mule sends and receives SOAP messages over HTTP, so to log the full SOAP requests and responses of
your app, enable debug logging for the HTTP message logger:

1.  In Anypoint Studio, open the `log4j2.xml` file in `src/main/resources` and add the
    `HttpMessageLogger` logger inside the `<Loggers>` element:

    ```xml
    <!-- HTTP is used by Mule for dispatching to web services -->
    <AsyncLogger name="org.mule.service.http.impl.service.HttpMessageLogger" level="DEBUG" />
    ```

2.  Save your project.

## Troubleshooting Logging

I don’t see any logging output

Make sure the `log4j2.xml` file is at the root of your classpath. In an Anypoint Studio project,
place it in `src/main/resources`.

I reconfigured Log4j 2, but nothing happened

This issue happens because there is another `log4j2.xml` file on your classpath that is getting
picked up before your modified one. To find out which configuration file Log4j 2 is using, add the
following switch when starting Mule (or add it to the container startup script if you are embedding
Mule):

\-M-Dlog4j.debug=true

This switch writes the Log4j 2 startup information, including the location of the configuration file
being used, to `stdout`. You must remove that configuration file before your modified configuration
can work.