You need to enable JavaScript to run this app. 通过 TCP 使用 Fluency 发送日志到 Fluentd 时如何保留 LogstashEncoder 结构化参数
优惠活动
大模型
产品
解决方案
定价
更多

通过 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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.22 07:06:00