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

本文探讨了在使用logstash logback进行结构化日志记录时，如何高效地处理包含多个字段的对象id。针对手动添加冗余结构化参数的问题，教程介绍了如何利用`structuredarguments.fields()`方法，通过反射自动将对象字段作为结构化参数添加到日志中，同时通过重写`tostring()`方法自定义日志消息中的显示内容，从而显著简化代码并提升可读性。

结构化日志的优势与挑战

在现代应用开发中，结构化日志记录已成为不可或缺的一部分，尤其是在结合ELK（Elasticsearch, Logstash, Kibana）等日志分析栈时。Logstash Logback Encoder 提供了一种便捷的方式，将日志消息转换为JSON格式，使得日志更容易被机器解析和查询。

然而，当一个业务对象包含多个标识字段（例如，一个SomeObjectId对象包含date、objectId和objectLocation），并且需要在日志中以结构化参数的形式记录这些字段时，传统的方法可能会导致代码冗余和可读性下降。

考虑以下场景，一个SomeObjectId类定义如下：

import java.time.LocalDate;

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

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

为了将SomeObjectId的所有字段作为结构化参数记录到日志中，通常会采用StructuredArguments.v()方法逐一添加：

import static net.logstash.logback.argument.StructuredArguments.v;

// 假设 someObjectId 是 SomeObjectId 的实例
log.info("Some object with ID {} {} {} is processed on {}.",
  v("date", someObjectId.getDate()),
  v("objectId", someObjectId.getObjectId()),
  v("location", someObjectId.getObjectLocation()),
  "someOtherArgument" // 其他非结构化参数
);

这段代码会生成如下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"
}

尽管实现了结构化日志的目标，但当对象字段增多时，log.info方法中的参数列表会变得非常冗长，影响代码的整洁性和维护性。

简化多字段对象结构化日志记录

为了解决上述问题，Logstash Logback Encoder 提供了一个强大的工具：StructuredArguments.fields(Object object)（或其简写形式StructuredArguments.f(Object object)）。这个方法允许我们将一个完整的对象作为参数传入，它会通过反射机制自动提取对象的字段（或通过getter方法），并将它们作为独立的结构化参数添加到日志中。

同时，为了控制这些字段在日志消息占位符（{}）中的显示方式，我们需要在对象类中重写toString()方法。

1. 修改对象类以支持显示和结构化提取

首先，我们需要修改SomeObjectId类，为其添加一个toString()方法，用于定义该对象在日志消息中的字符串表示。

喵记多

喵记多 - 自带助理的 AI 笔记

27

查看详情

import java.time.LocalDate;

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

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

  @Override
  public String toString() {
    // 定义对象在日志消息中的显示格式
    return date + " " + objectId + " " + objectLocation;
  }

  // 为了让StructuredArguments.fields()能访问，建议提供getter方法
  public LocalDate getDate() { return date; }
  public int getObjectId() { return objectId; }
  public String getObjectLocation() { return objectLocation; }
}

注意事项：

• StructuredArguments.fields()默认会通过反射查找对象的公共字段或公共的getter方法（例如getDate()），并将其作为结构化参数。因此，建议为需要记录的字段提供公共的getter方法。
• toString()方法仅影响对象在日志消息中的占位符{}处显示的内容，不影响其作为结构化参数被提取到JSON中的键值对。

2. 使用 StructuredArguments.fields() 简化日志调用

现在，我们可以使用StructuredArguments.fields()来简化日志调用：

import static net.logstash.logback.argument.StructuredArguments.fields; // 导入 fields 方法

// 假设 someObjectId 是 SomeObjectId 的实例
log.info("Some object with ID {} is processed on {}.",
  fields(someObjectId), // 将整个对象作为结构化参数传入
  "someOtherArgument"   // 其他非结构化参数
);

3. 生成的JSON日志输出

使用上述简化后的日志代码，将生成与之前相同效果的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", // 这里的内容由 SomeObjectId 的 toString() 方法决定
  "thread_name": "main",
  "level": "INFO",
  "date": "2022-11-30",       // 这些是结构化参数，由 fields() 方法通过反射提取
  "objectId": "123",
  "location": "NL"
}

总结与最佳实践

通过利用StructuredArguments.fields()方法，我们可以显著提高Logstash Logback结构化日志代码的简洁性和可维护性，尤其适用于那些包含多个字段的复杂业务对象。

关键点回顾：

• StructuredArguments.fields(object)： 自动将对象的公共字段或通过getter方法获取的值作为独立的结构化参数添加到JSON日志中。
• 重写toString()： 定义对象在日志消息占位符{}处的显示内容，使其更具可读性。

最佳实践：

1. 选择合适的字段： 并非所有对象字段都适合作为结构化参数。只将对日志分析有意义的字段通过getter暴露或作为公共字段。
2. 敏感信息处理： 避免将敏感信息（如密码、个人身份信息）直接通过fields()方法记录。如果需要记录，应进行脱敏处理。
3. 性能考量： fields()方法内部使用反射，虽然通常性能开销可接受，但在极度高并发的场景下，仍需注意其潜在影响。对于性能敏感的场景，可以考虑手动指定少量关键字段，或者实现自定义的StructuredArgument。
4. 清晰的toString()： toString()方法应提供一个简洁、有意义的字符串表示，方便开发人员快速理解日志内容。

通过遵循这些指导原则，您可以更有效地利用Logstash Logback进行结构化日志记录，从而提升日志的可观测性和故障排查效率。

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