Configuring JSON Message Layout

Enabling the JSON layout

You can enable JSON layout for log messages by specifying a corresponding class attribute for a message section:

<appender name="LOKI" class="com.github.loki4j.logback.Loki4jAppender">
    <format>
        ...
        <message class="com.github.loki4j.logback.JsonLayout" />
    </format>
    ...
</appender>

That's it! After running your application, you should see your log messages are sent to Loki as JSON objects:

{"timestamp_ms":1707947657247,"logger_name":"io.my.App","level":"INFO","thread_name":"main","message":"42"}

Fine-tuning the standard providers

Loki4j comes with a predefined set of standard JSON providers. Each of them can write zero, one, or more fields to the resulting JSON object. All standard provides are enabled by default, but you can disable them using the enabled setting:

<message class="com.github.loki4j.logback.JsonLayout">
    <timestamp>
        <enabled>false</enabled>
    </timestamp>
</message>

This will remove a timestamp from the log record:

{"logger_name":"io.my.App","level":"INFO","thread_name":"main","message":"42"}

Most of the providers have a fieldName setting that allows you to customize the JSON field name they will write to:

<message class="com.github.loki4j.logback.JsonLayout">
    <loggerName>
        <fieldName>class</fieldName>
    </loggerName>
</message>

Applying this configuration will give you:

{"timestamp_ms":1707947657247,"class":"io.my.App","level":"INFO","thread_name":"main","message":"42"}

Some providers have their own specific properties. For example, you can configure the MDC provider to include only specified keys in the log record:

<message class="com.github.loki4j.logback.JsonLayout">
    <mdc>
        <include>myKey1</include>
        <include>myKey2</include>
    </mdc>
</message>

Please check the reference for a complete list of standard providers and their settings.

Custom JSON providers

If standard providers don't cover all your needs, consider creating your own provider. All providers must implement the com.github.loki4j.logback.json.JsonProvider interface. The easiest way to build a one-field provider is to derive it from the AbstractFieldJsonProvider from the same package. Here is the example implementation:

public class ConstantProvider extends AbstractFieldJsonProvider {

    public ConstantProvider() {
        setFieldName("constant_name");
    }

    @Override
    protected void writeExactlyOneField(JsonEventWriter writer, ILoggingEvent event) {
        writer.writeStringField(getFieldName(), "constant_value");
    }
}

Then, you need to register this new provider in the configuration:

<message class="com.github.loki4j.logback.JsonLayout">
    <customProvider class="io.my.ConstantProvider" />
</message>

After applying this configuration, you will see the following:

{"timestamp_ms":1707947657247,"logger_name":"io.my.App","level":"INFO","thread_name":"main","message":"42","constant_name":"constant_value"}

You can add as many custom providers as you want:

<message class="com.github.loki4j.logback.JsonLayout">
    <customProvider class="io.my.ConstantProvider1" />
    <customProvider class="io.my.ConstantProvider2" />
    <customProvider class="io.my.ConstantProvider3" />
</message>