优化Logstash Logback结构化日志：简化多字段对象参数记录

本文旨在解决logstash logback中记录包含多个字段的对象（如id）时，代码冗余的问题。通过详细阐述传统`v()`方法的不足，并引入`structuredarguments.fields()`（或`f()`）这一高效解决方案，指导开发者如何利用该方法自动将对象字段作为结构化参数输出，同时结合`tostring()`方法优化日志消息的显示，从而显著提升日志代码的简洁性和可维护性。

在现代分布式系统中，结构化日志是可观测性的基石。Logstash Logback Encoder 提供强大的能力，允许开发者将自定义数据作为结构化字段嵌入到JSON格式的日志中，便于后续的检索和分析。然而，当需要记录一个包含多个标识字段的对象（例如，一个由日期、ID和位置组成的对象ID）时，传统的日志方式可能会导致代码冗余和可读性下降。

传统结构化日志记录的挑战

考虑一个常见的场景，我们有一个SomeObjectId对象，它包含date、objectId和objectLocation三个字段，用于唯一标识某个业务对象。

class SomeObject {
  SomeObjectId id;
  // ... 其他字段
}

class SomeObjectId {
  LocalDate date;
  int objectId;
  String objectLocation;
}

如果采用Logstash Logback提供的v()（StructuredArguments.v()）方法逐一记录这些字段，代码会显得比较冗长：

import static net.logstash.logback.argument.StructuredArgument.v;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MyService {
    private static final Logger log = LoggerFactory.getLogger(MyService.class);

    public void processObject(SomeObjectId objectId) {
        log.info("Some object with ID {} {} {} is processed on {}.",
          v("date", objectId.getDate()),
          v("objectId", objectId.getObjectId()),
          v("location", objectId.getObjectLocation()),
          "someOtherArgument" // 其他非结构化参数
        );
    }
}

上述代码将生成以下JSON日志输出，其中date、objectId和location作为独立的结构化字段出现：

{
  "@timestamp": "2022-11-30T12:34:56.000+00:00",
  "@version": "1",
  "message": "Some object with ID 2022-11-30 123 NL is processed on someOtherArgument",
  "thread_name": "main",
  "level": "INFO",
  "date": "2022-11-30",
  "objectId": "123",
  "location": "NL"
}

尽管这种方式实现了结构化日志的目标，但每次记录SomeObjectId时都需要显式列出所有字段，这不仅增加了代码量，也降低了可维护性，特别是在对象字段增减时。

解决方案：利用 StructuredArguments.fields() 简化记录

Logstash Logback Encoder 提供了一个更简洁的解决方案：StructuredArguments.fields(object)（或其缩写形式StructuredArguments.f(object)）。这个方法能够自动解析给定对象的字段，并将它们作为独立的结构化参数添加到日志消息中。为了控制对象在日志消息占位符中的文本表示，我们还需要重写对象的toString()方法。

1. 重写对象的 toString() 方法

首先，修改SomeObjectId类，重写其toString()方法，使其返回一个包含所有ID字段的简洁字符串表示。这将用于填充日志消息中的占位符{}。

即构数智人

即构数智人是由即构科技推出的AI虚拟数字人视频创作平台，支持数字人形象定制、短视频创作、数字人直播等。

36

查看详情

import java.time.LocalDate;

class SomeObjectId {
  LocalDate date;
  int objectId;
  String objectLocation;

  // 构造函数、Getter/Setter等省略

  @Override
  public String toString() {
    return date + " " + objectId + " " + objectLocation;
  }
}

2. 使用 StructuredArguments.fields() 记录日志

接下来，在日志记录时，直接将SomeObjectId对象传递给StructuredArguments.fields()方法。

import net.logstash.logback.argument.StructuredArguments;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MyService {
    private static final Logger log = LoggerFactory.getLogger(MyService.class);

    public void processObject(SomeObjectId someObjectId) {
        log.info("Some object with ID {} is processed on {}.",
          StructuredArguments.fields(someObjectId), // 使用 fields() 方法
          "someOtherArgument" // 其他非结构化参数
        );
    }
}

生成的JSON日志输出

经过上述优化，Logstash Logback将生成与之前完全相同的结构化JSON日志，但日志代码显著简化：

{
  "@timestamp": "2022-11-30T12:34:56.000+00:00",
  "@version": "1",
  "message": "Some object with ID 2022-11-30 123 NL is processed on someOtherArgument",
  "thread_name": "main",
  "level": "INFO",
  "date": "2022-11-30",
  "objectId": "123",
  "location": "NL"
}

可以看到，date、objectId和location依然作为独立的JSON字段存在，而日志消息中的{}占位符则被SomeObjectId的toString()方法返回的字符串填充。

注意事项与最佳实践

• toString() 的重要性： StructuredArguments.fields() 方法负责将对象的字段提取为JSON日志的键值对。而对象在日志消息字符串中的显示，完全依赖于其toString()方法的实现。因此，务必为频繁作为参数传递的对象提供一个有意义的toString()实现。
• 字段提取机制： StructuredArguments.fields() 通常通过反射来获取对象的公共字段或通过getter方法获取属性值。为了确保所有相关字段都能被正确提取，建议对象遵循JavaBean规范，为需要记录的字段提供公共的getter方法。
• 性能考量： 尽管反射操作会有轻微的性能开销，但在大多数日志场景中，这种开销通常可以忽略不计。对于极端高性能要求的日志，应进行基准测试。
• 缩写形式 f()： 为了进一步简化代码，可以使用StructuredArguments.f(someObjectId)替代StructuredArguments.fields(someObjectId)。
• 适用场景： StructuredArguments.fields() 特别适用于那些作为聚合ID或DTO（数据传输对象）频繁出现在日志中的对象。它避免了重复编写大量v("fieldName", object.getFieldName())的代码，提高了日志代码的内聚性和可读性。

总结

通过巧妙地结合StructuredArguments.fields()方法和对象的toString()方法，我们可以极大地简化Logstash Logback中记录多字段对象的代码。这种方法不仅减少了冗余，提升了代码的可维护性，同时保持了日志输出的结构化特性，为后续的日志分析提供了便利。在设计日志策略时，应优先考虑使用这种高效且简洁的方式来处理复杂的结构化参数。

以上就是优化Logstash Logback结构化日志：简化多字段对象参数记录的详细内容，更多请关注php中文网其它相关文章！