如何在Log4j的JSON日志中全局追加特定异常的自定义字段？

Log4j完全支持在Appender/Layout层面实现这个全局需求，不用在业务代码里写MDC的put/remove逻辑。下面是两种靠谱的实现方式：

方式一：自定义JsonGeneratorDecorator（适配Log4j 2.x JsonLayout） #

如果你的结构化日志用的是Log4j自带的JsonLayout，可以通过自定义JsonGeneratorDecorator，在生成JSON内容时直接检查Throwable并注入字段：

1. 实现装饰器类 #

import com.fasterxml.jackson.core.JsonGenerator;
import org.apache.logging.log4j.core.LogEvent;
import org.apache.logging.log4j.core.layout.JsonLayout.JsonGeneratorDecorator;

public class SpecificExceptionFieldDecorator implements JsonGeneratorDecorator {
    private static final String CUSTOM_FIELD_KEY = "specificExceptionData";

    @Override
    public JsonGenerator decorate(JsonGenerator generator, LogEvent event) {
        Throwable thrown = event.getThrown();
        if (thrown instanceof SpecificException) {
            SpecificException ex = (SpecificException) thrown;
            try {
                // 直接向JSON生成器写入自定义字段
                generator.writeStringField(CUSTOM_FIELD_KEY, ex.getData());
            } catch (Exception e) {
                // 序列化失败时降级，避免影响主日志输出
            }
        }
        return generator;
    }
}

2. 在Log4j配置中启用装饰器 #

修改log4j2.xml里的JsonLayout配置，添加自定义装饰器：

<Appenders>
    <Console name="JsonConsole">
        <JsonLayout complete="true">
            <JsonGeneratorDecorator class="com.yourpackage.SpecificExceptionFieldDecorator"/>
        </JsonLayout>
    </Console>
</Appenders>

方式二：自定义包装型Appender #

如果需要更灵活的事件处理（比如修改日志上下文数据后再交给原Appender输出），可以写一个包装Appender，在传递日志事件前注入字段：

1. 实现包装Appender类 #

import org.apache.logging.log4j.core.Appender;
import org.apache.logging.log4j.core.Core;
import org.apache.logging.log4j.core.Filter;
import org.apache.logging.log4j.core.LogEvent;
import org.apache.logging.log4j.core.appender.AbstractAppender;
import org.apache.logging.log4j.core.config.Property;
import org.apache.logging.log4j.core.config.plugins.Plugin;
import org.apache.logging.log4j.core.config.plugins.PluginAttribute;
import org.apache.logging.log4j.core.config.plugins.PluginElement;
import org.apache.logging.log4j.core.config.plugins.PluginFactory;
import org.apache.logging.log4j.core.util.Booleans;

@Plugin(name = "SpecificExceptionEnhancerAppender", category = Core.CATEGORY_NAME, elementType = Appender.ELEMENT_TYPE)
public class SpecificExceptionEnhancerAppender extends AbstractAppender {
    private final Appender delegateAppender;
    private static final String CUSTOM_FIELD_KEY = "specificExceptionData";

    protected SpecificExceptionEnhancerAppender(String name, Filter filter, Appender delegate, boolean ignoreExceptions, Property[] properties) {
        super(name, filter, null, ignoreExceptions, properties);
        this.delegateAppender = delegate;
    }

    @PluginFactory
    public static SpecificExceptionEnhancerAppender createAppender(
            @PluginAttribute("name") String name,
            @PluginAttribute("ignoreExceptions") String ignoreExceptions,
            @PluginElement("Filter") Filter filter,
            @PluginElement("Appender") Appender delegate) {
        boolean ignore = Booleans.parseBoolean(ignoreExceptions, true);
        return new SpecificExceptionEnhancerAppender(name, filter, delegate, ignore, null);
    }

    @Override
    public void append(LogEvent event) {
        Throwable thrown = event.getThrown();
        if (thrown instanceof SpecificException) {
            // 向日志事件的上下文数据中添加字段，JsonLayout会自动序列化这些字段
            event.getContextData().put(CUSTOM_FIELD_KEY, ((SpecificException) thrown).getData());
        }
        // 交给原Appender输出
        delegateAppender.append(event);
    }
}

2. 在Log4j配置中使用包装Appender #

先定义原JSON输出Appender，再用自定义包装Appender包裹它：

<Appenders>
    <Console name="RawJsonConsole">
        <JsonLayout complete="true"/>
    </Console>
    <SpecificExceptionEnhancerAppender name="EnhancedJsonConsole" delegate="RawJsonConsole"/>
</Appenders>
<Loggers>
    <Root level="error">
        <AppenderRef ref="EnhancedJsonConsole"/>
    </Root>
</Loggers>

关键注意事项 #

• 两种方式都是全局生效，业务代码无需任何修改，避免了MDC方式的重复代码和遗漏remove的风险。
• Log4j 2.x的LogEvent实例在传递过程中是线程安全的，每个日志事件都是独立处理，不用担心字段污染问题。
• 如果自定义字段需要复杂序列化，可以在装饰器中调用Jackson的序列化逻辑，或者让SpecificException的getData()返回可直接序列化的类型。

内容的提问来源于stack exchange，提问作者hnnn