What is MDC and how to use it in Mule

MDC stands for Mapped Diagnostic Context. It’s a feature included in Log4j that allows us to enrich our logs by adding contextual information, making it easier to trace and understand the flow of execution across different parts of an application or, in a mule deployment, an Application Network.

MDC acts as a thread-local storage of key-value pairs, where each key represents some contextual information (e.g., user ID, correlation ID) relevant to the current thread of execution.
These values are then automatically included in every log statement made by that thread, allowing for a more detailed and relevant logging output.
This is important for Mule applications, where flows might be executed in parallel or across different threads.

How to use it

Let’s see a simple example, without extra configurations, to see what information is available in MDC by default in a mule application.
For that, let’s create a mule project for a simple app: one HTTP listener + One logger

Open the log4j2.xml file located under src/main/resources folder of your mule project and make the following changes:

• Add a new Appender (Console) within the Appender section with the following values

<Console name="Console" target="SYSTEM_OUT">
    <PatternLayout pattern="[gon-mdc: %MDC] %c: %m%n"/>
</Console>

• Notice that we’ve included the PatternLayout with a simple conversion pattern - [gon-mdc: %MDC] %c: %m%n
• [gon-mdc: %MDC] - This will display all the properties in the MDC in brackets
• %c - will display the thread name
• %m - will display the message of the log
• %n - will add a new line of text

(If you want to know more about how the PatternLayout works have a look at the post: Breaking down the Log4j PatternLayout)

• In the Loggers section add the AppenderRef within the AsyncRoot element:

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

• Our final log4j2.xml should look like this

• Save the file and run the project
• Once the app is deployed send a request to our hello endpoint and check the console. We should see a new log entry like this:

[gon-mdc: {correlationId=9c7c4750-711f-11ef-b36c-38f9d3cde3d6, processorPath=mdc-tests-flow/processors/0}] org.mule.runtime.core.internal.processor.LoggerMessageProcessor: Hello Gon!

So, as we can see, by default the MDC provides us with 

• correlationId
• processorPath

Adding properties to the MDC

Let’s see how we can enrich the logs and add our custom properties to the MDC. For that:

• Add the Tracing module from the Mule Palette

• Drag and drop the Set logging variable processor to the flow, just before the Logger:

• In the configuration of the Tracing processor we will add the following key-value pair: user_id: 22

Save the project and Run it. Once the app is deployed, send a request to our hello endpoint to generate a new log entry. Check the console, we should see a new log like this:

[gon-mdc: {correlationId=35763220-7122-11ef-b7c6-38f9d3cde3d6, user_id=22, processorPath=mdc-tests-flow/processors/1}] org.mule.runtime.core.internal.processor.LoggerMessageProcessor: Hello Gon!

MDC properties with the JSONLayout

The previous example was using the PatternLayout, which is the default Layout in mule apps. But if you are sending your logs to a logging aggregation system like Splunk, ELK or Datadog, you would probably be using the JSONLayout to get the logs in JSON format.
In the JSONLayout we need to add the attribute properties=“true” to include the information in the MDC. Let’s see it:

• Get back to the log4j2.xml file
• Remove the PatternLayout element
• Add the JSONLayout element with these values:

<JSONLayout compact="false" eventEol="true" properties="true" />

• Your log4j2.xml should now look like this:

• Save the file and run the project.
• When the app is deployed send a new request to our hello endpoint and check the console, we should see a new log entry like this:

{
 "instant" : {
    "epochSecond" : 1726158237,
    "nanoOfSecond" : 374000000
 },
 "thread" : "[MuleRuntime].uber.04: [mdc-tests].mdc-tests-flow.CPU_LITE @b880cea",
 "level" : "INFO",
 "loggerName" : "org.mule.runtime.core.internal.processor.LoggerMessageProcessor",
 "message" : "Hello Gon!",
 "endOfBatch" : true,
 "loggerFqcn" : "org.apache.logging.slf4j.Log4jLogger",
 "contextMap" : {
    "correlationId" : "69198950-7123-11ef-a128-38f9d3cde3d6",
    "processorPath" : "mdc-tests-flow/processors/1",
    "user_id" : "22"
 },
 "threadId" : 51,
 "threadPriority" : 5
}

Notice that now, with a JSON format, all the MDC properties are included under the contextMap field, which will make it easy for the logging aggregation system to parse those values and create search queries filtering by any of the custom properties we’ve just added. In our example we could query all the transactions related to the user_id=22.