Log4j2配置异常：生产环境自定义%mask数据掩码功能失效

问题描述 #

我们通过自定义Log4j2模式转换器%mask实现日志敏感数据掩码，本地开发环境完全正常，但部署到生产服务器后掩码功能失效。移除%mask配置后部署成功，但无法实现掩码效果。

已完成的排查：

• 按Log4j2官方文档要求为转换器添加@ConverterKeys({"mask"})注解
• 确认转换器实现逻辑与当前Log4j2版本兼容
• 排查过依赖冲突，确保生产环境类路径包含所有必要依赖

相关代码 #

自定义转换器Java类 #

@Plugin(name = "MaskedPatternConverter", category = "Converter")
@ConverterKeys({"mask","masked"})
public class MaskedPatternConverter extends LogEventPatternConverter {
    public void format(LogEvent event, StringBuilder outputmsg) {
        String message = event.getMessage().getFormattedMessage();
        // Implement your masking logic here
        String maskedMessage = maskSensitiveData(message);
        
        if (message.toLowerCase().contains("email") ||
            message.toLowerCase().contains("adharcard") ||
            message.toLowerCase().contains("creditcard")) {
            String mask = maskEmailandAdhar(message);
            outputmsg.append(mask);
        } else {
            outputmsg.append(maskedMessage);
        }
    }
}

log4j2.xml配置片段 #

<Appenders>
    <Routing name="AppzillonServerLogFile">
        <Routes pattern="$${ctx:AppId}/$${ctx:UserId}/">
            <Route>
                <RollingFile name="MainLogFile" fileName="${loghome}/${ctx:AppId}/${ctx:UserId}/MainLogFile.log"
                             filePattern="${loghome}/${ctx:AppId}/${ctx:UserId}/%d{dd-MM-yyyy}-MainLogFile-%i.log.zip">
                    <PatternLayout>
                        <Pattern>%d %p %-40c{1.} [$${ctx:reqRef}] [$${ctx:UserId}] %mask{email}{pass}{aadhaar}%n
                        </Pattern>
                    </PatternLayout>
                </RollingFile>
            </Route>
        </Routes>
    </Routing>
</Appenders>

可能的原因及解决方法 #

1. SPI配置文件缺失 #

Log4j2通过SPI机制加载自定义插件，生产环境常出现打包时遗漏配置文件的情况：

• 检查生产环境类路径下是否存在META-INF/services/org.apache.logging.log4j.core.pattern.LogEventPatternConverter文件，文件内容必须包含自定义转换器的全类名（如com.yourpackage.MaskedPatternConverter）
• 确认Maven/Gradle打包脚本将该文件包含进最终Jar/War包，可通过解压包文件直接验证

2. 类加载器隔离冲突 #

部分应用服务器（Tomcat、WebLogic等）的类加载隔离机制会阻碍自定义插件加载：

• 调整应用类加载优先级，比如Tomcat中在context.xml添加<Loader delegate="false"/>，让Web应用优先加载自身类
• 排查容器自带的Log4j2依赖，若版本与应用不一致，需排除容器依赖或确保应用依赖优先加载

3. 转换器参数处理逻辑缺失 #

配置中%mask传递了{email}{pass}{aadhaar}参数，但当前代码未处理这些参数：

• 补充参数接收逻辑，重写带参数的构造方法和newInstance方法，根据传入参数动态掩码（示例代码如下）
• 注意代码中关键词拼写：配置用的是aadhaar，代码中是adharcard，拼写不一致会导致掩码逻辑未触发

修改后的转换器示例：

private final List<String> maskTargets;

private MaskedPatternConverter(List<String> options) {
    super("Mask", "mask");
    this.maskTargets = options;
}

public static MaskedPatternConverter newInstance(List<String> options) {
    return new MaskedPatternConverter(options);
}

@Override
public void format(LogEvent event, StringBuilder outputmsg) {
    String message = event.getMessage().getFormattedMessage();
    String maskedMessage = message;
    // 根据传入参数针对性掩码
    for (String target : maskTargets) {
        switch(target.toLowerCase()) {
            case "email":
                maskedMessage = maskEmail(maskedMessage);
                break;
            case "pass":
                maskedMessage = maskPassword(maskedMessage);
                break;
            case "aadhaar":
                maskedMessage = maskAadhaar(maskedMessage);
                break;
        }
    }
    outputmsg.append(maskedMessage);
}

4. 生产环境日志过滤规则问题 #

• 检查生产环境日志级别配置，确保需要掩码的日志级别（如DEBUG/INFO）未被过滤
• 排查是否存在ThresholdFilter等过滤器拦截日志事件，导致自定义转换器未被调用

5. 插件加载日志验证 #

添加JVM启动参数-Dlog4j2.debug=true，查看生产环境启动日志中是否有自定义转换器的加载记录，确认插件是否被成功识别加载

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