通过 TCP 使用 Fluency 发送日志到 Fluentd 时如何保留 LogstashEncoder 结构化参数
Fluency 官方提供的 Logback Appender 本身不支持挂载 LogstashEncoder,也不会解析 logstash-logback-encoder 专属的 StructuredArguments:
- 该 Appender 内部自行组装发往 Fluentd 的报文,仅提取日志级别、Logger 名称、线程名、原始日志内容、MDC 上下文、SLF4J Marker 这类 Logback 原生事件属性
StructuredArguments(包括kv()、entries()等方法生成的结构化参数)属于编码器层扩展,只有LogstashEncoder执行编码时,才会从日志可变参数中提取结构化键值。Fluency Appender 不会触发这段解析逻辑,因此自定义字段全部丢失,仅保留默认基础字段- 不要尝试在原生 Fluency Appender 下添加
<encoder>配置,该组件未暴露编码器注入入口,配置不会生效
按改动成本从低到高可选以下方案:
方案1:改用 MapMarker 传参(无需自定义代码)
Fluency 原生识别 Logstash 提供的 Map 型 Marker,只需打开配置中的摊平开关,就能把 Marker 内的键值直接放到日志顶层,自定义字段的传递效果和 StructuredArguments 完全一致。
- 修改原有 Fluency Appender 配置,将
flattenMapMarker设为开启:
<flattenMapMarker>true</flattenMapMarker>
- 把代码中的 StructuredArguments 替换为 Marker 写法,对比如下:
原有 StructuredArguments 写法:
import static net.logstash.logback.argument.StructuredArguments.*; log.info("LOGIN", kv("User", "XXh"), kv("Item", "Audit"), entries(Map.of( "Event", "LOGIN", "EventInfo", "Logged in successfully", "Source", "1.2.3.4" )), kv("payload", Map.of("empty", true, "present", false)) );
替换为 Marker 写法:
import static net.logstash.logback.marker.Markers.*; import org.slf4j.Marker; Marker auditMarker = append("User", "XXh") .and(append("Item", "Audit")) .and(appendEntries(Map.of( "Event", "LOGIN", "EventInfo", "Logged in successfully", "Source", "1.2.3.4" ))) .and(append("payload", Map.of("empty", true, "present", false))); log.info(auditMarker, "LOGIN");
发送到 Fluentd 后的自定义字段、嵌套对象结构和预期完全一致。
该方案默认输出的基础字段名为Fluency规范命名,如果需要完全对齐
@timestamp、level_value等Logstash标准字段,可以在Fluentd侧通过字段转换插件调整,或选择后文的桥接方案。
方案2:通过 MDC 传递结构化字段(适合审计类公共字段)
如果字段是请求/线程维度的公共上下文(比如用户ID、来源IP这类审计字段),可以直接存入 SLF4J MDC,Fluency 默认会把所有 MDC 键值原样发送到 Fluentd,无需修改 Appender 配置:
MDC.put("User", "XXh"); MDC.put("Source", "1.2.3.4"); try { log.info("LOGIN"); } finally { // *必须清理,避免线程池复用导致字段串用* MDC.clear(); }
该方案缺点是 MDC 与线程绑定,异步线程、响应式场景需要手动传递上下文,不适合单条日志的独立字段。
方案3:自定义桥接 Appender(兼容原有 StructuredArguments 代码)
如果不想修改存量业务代码,可以自行实现一个 Appender,先用 LogstashEncoder 解析日志事件(含StructuredArguments)生成标准Logstash格式JSON,再转成Map交给Fluency发送,步骤如下:
- 引入所需依赖(Maven、Gradle均可):
implementation 'ch.qos.logback:logback-classic:1.2.11' implementation 'net.logstash.logback:logstash-logback-encoder:7.4' implementation 'org.komamitsu:fluency-core:2.7.0' implementation 'org.komamitsu:fluency-fluentd:2.7.0'
- 实现自定义 Appender:
import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.AppenderBase; import com.fasterxml.jackson.databind.ObjectMapper; import net.logstash.logback.encoder.LogstashEncoder; import org.komamitsu.fluency.Fluency; import java.util.Map; public class FluencyLogstashAppender extends AppenderBase<ILoggingEvent> { private LogstashEncoder encoder; private Fluency fluency; private final ObjectMapper objectMapper = new ObjectMapper(); // 基础配置,可按需扩展Fluency的缓冲、备份、ACK等参数 private String tag; private String host; private int port; @Override public void start() { encoder = new LogstashEncoder(); encoder.start(); try { fluency = Fluency.defaultFluency(host, port); } catch (Exception e) { addError("初始化Fluency客户端失败", e); } super.start(); } @Override protected void append(ILoggingEvent event) { try { // 由LogstashEncoder解析所有结构化参数,生成标准Logstash格式字段 byte[] logJson = encoder.encode(event); Map<String, Object> logEntry = objectMapper.readValue(logJson, Map.class); fluency.emit(tag, event.getTimeStamp(), logEntry); } catch (Exception e) { addError("发送日志至Fluentd失败", e); } } @Override public void stop() { try { fluency.close(); } catch (Exception e) { addError("关闭Fluency客户端失败", e); } encoder.stop(); super.stop(); } // 省略tag、host、port的getter/setter }
如果需要保留原配置里的ACK响应、文件备份、缓冲阈值等能力,只需给自定义Appender添加对应属性的setter,在start()构建Fluency时传入配置即可。
可选方案:弃用Fluency,用编码器原生TCP Appender
如果不强依赖Fluency的本地文件备份、断网缓存能力,可以直接使用 logstash-logback-encoder 自带的TCP Appender,原生支持StructuredArguments,Fluentd侧配置TCP输入+JSON解析即可:
<appender name="FLUENTD_DIRECT" class="net.logstash.logback.appender.LogstashTcpSocketAppender"> <destination>127.0.0.1:24224</destination> <encoder class="net.logstash.logback.encoder.LogstashEncoder"/> </appender>
该方案配置最简单,输出字段完全符合Logstash规范,但极端网络场景下的日志可靠性弱于Fluency。
你贴出的标签、IP、端口三个基础值没有包裹在Fluency Appender配置节点内,请确认最终配置中包含完整的基础参数:
<appender name="FLUENCY" class="org.komamitsu.fluency.logback.FluencyLogbackAppender"> <tag>AUDIT</tag> <remoteHost>127.0.0.1</remoteHost> <port>24224</port> <!-- 其余缓冲、备份配置 --> </appender>
内容的提问来源于stack exchange,提问作者Aswath Murugan

