Kotlin-logging项目中JSON日志输出字段问题的解决方案

背景介绍

在Kotlin-logging这个流行的日志库使用过程中，开发者发现了一个关于JSON日志输出的重要问题。当从传统的StructuredArguments方式迁移到新的API时，额外字段在JSON输出中无法正常显示。这个问题影响了需要结构化日志输出的应用场景。

问题分析

在7.0.0版本之前，开发者可以使用如下方式添加额外字段：

log.error("Cake", StructuredArguments.keyValue("caketype", "chocolate"))

这种方式在JSON配置下能正确输出包含额外字段的日志。但随着API更新，这种方法被标记为废弃，推荐使用新的atError等流畅API：

log.atError {
   message = "Cake"
   payload = buildMap { put("caketype", "chocolate") }
}

然而，新方法在JSON输出中却无法保留额外字段，这显然不符合预期行为。经过深入分析，发现问题根源在于：

1. 旧方法通过argumentArray传递额外参数
2. 新方法使用keyValuePairs机制
3. Logback的JSON编码器默认只处理argumentArray中的结构化参数

技术实现细节

在底层实现上，Slf4j 2.x引入了全新的流畅API，改变了参数传递机制。Kotlin-logging 7.0.0基于这个新API重构，但参数处理方式发生了变化：

• 传统方式：参数通过Object[]数组传递
• 流畅API：参数通过键值对形式传递
• Logback编码器：默认配置只识别数组形式的参数

解决方案

经过社区讨论和代码验证，最终在7.0.3版本中引入了新的arguments属性，允许开发者明确指定要作为日志事件参数的额外字段：

log.atError {
   message = "Cake"
   arguments = listOf(StructuredArguments.keyValue("caketype", "chocolate"))
}

这种实现方式既保持了API的流畅性，又确保了与现有JSON配置的兼容性。底层实现上，它调用了Slf4j流畅API的addArgument方法，将参数放入正确的位置供编码器处理。

最佳实践建议

对于需要结构化日志输出的项目，建议：

1. 升级到7.0.3或更高版本
2. 使用新的arguments属性传递需要出现在JSON中的字段
3. 保留payload用于非结构化日志的额外信息
4. 检查Logback配置确保包含arguments提供器

总结

Kotlin-logging通过这次改进，既保持了现代化API的设计，又解决了与现有日志基础设施的兼容性问题。这体现了开源项目在平衡创新和稳定性方面的考量，也为开发者提供了更灵活的日志记录方式。