Logstash 中的 ECS 兼容模式ecs_compatibility完整配置指南【免费下载链接】logstashLogstash - transport and process your logs, events, or other data项目地址: https://gitcode.com/gh_mirrors/lo/logstash导读Elastic Common SchemaECS是一套开放的事件字段规范帮助用户将日志、指标等事件数据归一化从而在 Elasticsearch 中更高效地分析、可视化与关联数据。本文聚焦 Logstash 的 ECS 兼容模式机制从单个插件实例、单个管道到整个进程三个层级详解ecs_compatibility的配置方法、默认值与优先级并结合仓库源码剖析其参数校验、默认值来源与生效链路帮助你精准掌控 Logstash 8 中 ECS 与 legacy 行为的切换平滑完成既有管道的升级。ECS 是什么为什么 Logstash 需要它ECSElastic Common Schema是一个由 Elastic 社区共同支持的开源规范它定义了一套通用字段用于存储日志、指标等事件数据。借助 ECS用户可以规范化事件数据从而更好地分析、可视化和关联事件中表示的数据——不同来源如 Filebeat、Logstash、各种采集器产生的同类事件将共享一致的字段命名与语义。Logstash 插件在 ECS 规范出现之前就已存在多年许多插件的默认字段命名与 ECS 并不一致。为此很多插件实现了 ECS 兼容模式ECS compatibility mode在该模式下插件以符合 ECS 的方式产生和处理事件。任何支持该模式的插件都会提供一个ecs_compatibility选项用于配置该插件实例工作在哪种模式下使用某个具体版本的 ECS或保持其 legacy非 ECS行为。需要强调的是ECS 兼容模式并不阻止你显式配置一个与 ECS 冲突的插件它只确保「隐式配置」即插件未显式指定时的默认字段行为不与 ECS 冲突。理解 ecs_compatibility 的取值根据 config/logstash.yml 中的注释说明pipeline.ecs_compatibility的合法取值有三类取值含义disabled关闭 ECS 兼容模式插件保持 legacy非 ECS行为v1使用 ECS 1.x 兼容模式v8使用 ECS 8 兼容模式默认值从源码看这个取值并非自由字符串而是经过严格校验的。在 logstash-core/lib/logstash/plugins/ecs_compatibility_support.rb 的ArgumentValidator中字面量disabled被原样接受形如v1、v8的「v 前缀 整数」模式正则\Av[1-9][0-9]?\Z被转换为 Symbol 接受其余任何值都会报错Expected a v-prefixed integer major-version number (e.g.,v1) or the literaldisabled。而在 logstash-core/lib/logstash/environment.rb 中进程级设置pipeline.ecs_compatibility被注册为CoercibleStringSetting默认值为v8合法值集合为%w(disabled v1 v8)——这正对应了「Logstash 8 中所有插件默认运行在 ECS v8 模式」的设计。三级配置从插件实例到整个进程ecs_compatibility遵循「具体优先」的覆盖规则插件实例级 管道级 进程级。未在低层显式指定时自动向上层取值。这使你可以精确控制某一处行为而不影响其他实例。1. 单个插件实例使用插件的 ecs_compatibility 选项在管道配置中为某个插件实例显式设置ecs_compatibility即可覆盖该实例的默认值且不影响任何其他插件实例。例如让某个特定的 GeoIP Filter 实例关闭 ECS 兼容模式filter { geoip { source [host][ip] ecs_compatibility disabled } }反过来如果你运行在 Logstash 7 中却希望某个 UDP input 及其 CEF codec 提前启用 ECS 模式可以分别指定 ECS 大版本input { udp { port 1234 ecs_compatibility v8 codec cef { ecs_compatibility v8 } } }注意示例中 input 与 codec 是两个独立插件实例各自都需要设置ecs_compatibility——这也是理解该机制的关键ECS 兼容性作用于插件实例粒度。2. 管道级pipeline.ecs_compatibility 设置若想让一条管道中所有插件使用统一的默认值可以在管道定义中设置pipeline.ecs_compatibility位于config/pipelines.yml或 Central Management 中。该值会被该管道中所有未显式指定的插件实例继承。例如将一条升级前定义的管道「锁定」为 pre-Logstash 8 行为同时让另一条新管道启用 ECS v8- pipeline.id: my-legacy-pipeline path.config: /etc/path/to/legacy-pipeline.config pipeline.ecs_compatibility: disabled - pipeline.id: my-ecs-pipeline path.config: /etc/path/to/ecs-pipeline.config pipeline.ecs_compatibility: v8从源码层面看logstash-core/lib/logstash/settings.rb 将pipeline.ecs_compatibility列入管道设置白名单使其既能作为进程级设置也能作为pipelines.yml中的管道级覆盖设置生效。3. 进程级为所有管道设置全局默认值在config/logstash.yml中设置pipeline.ecs_compatibility即为整个 Logstash 进程的所有管道提供默认值pipeline.ecs_compatibility: disabled该方式适合「整体保持 legacy 行为」的场景。不过需要注意进程级设置会作用于所有管道包括以后新建的管道如果你只想隔离少数旧管道优先使用第 2 种管道级配置。底层实现ecs_compatibility 如何被解析生效理解了三个层级后我们再看仓库源码中的完整生效链路这能帮助你更准确地预判行为。第一步插件注册配置项。所有插件基类 logstash-core/lib/logstash/plugin.rb 引入ECSCompatibilitySupport模块该模块在 ecs_compatibility_support.rb 中为插件声明了config(:ecs_compatibility, :validate :ecs_compatibility_argument)——这正是为什么「支持 ECS 的插件都拥有ecs_compatibility选项」。第二步取值优先级解析。模块中的ecs_compatibility方法ecs_compatibility_support.rb依次解析若插件配置中显式设置了ecs_compatibility直接采用插件实例值否则从当前插件的execution_context.pipeline.settings读取pipeline.ecs_compatibility即管道级或进程级值若管道上下文缺失回退到全局LogStash::SETTINGS中的进程级默认值。这一实现与文档描述的三级覆盖规则完全一致插件显式配置 管道设置 全局设置。第三步启动日志确认。管道初始化时logstash-core/lib/logstash/java_pipeline.rb 会记录一条 INFO 日志Pipeline my-ecs-pipeline is configured with pipeline.ecs_compatibility: v8 setting. All plugins in this pipeline will default to ecs_compatibility v8 unless explicitly configured otherwise.日志文案定义于 logstash-core/locales/en.yml。排查问题时直接查看 Logstash 启动日志中的该条信息即可确认每条管道实际生效的 ECS 模式。命令行与 Central Management 中的配置途径除了配置文件ecs_compatibility还有另外两条配置途径命令行参数logstash-core/lib/logstash/runner.rb 注册了--pipeline.ecs_compatibility STRING启动选项默认值取自进程级设置的默认值。可在启动时覆盖全局默认例如bin/logstash --pipeline.ecs_compatibility disabledCentral Managementx-pack/lib/config_management/elasticsearch_source.rb 在从 Elasticsearch 拉取托管管道配置时会将pipeline.ecs_compatibility一并下发到管道设置中其行为与pipelines.yml中的管道级配置一致对应测试见 x-pack/spec/config_management/elasticsearch_source_spec.rb。迁移建议与注意事项升级 Logstash 8 的默认行为Logstash 8 中所有插件默认运行在 ECS v8 模式。如果你的管道在 Logstash 7 时代定义且大量依赖 legacy 字段名升级后字段结构可能变化影响下游索引映射与 Kibana 可视化。分层退出策略为个别插件设ecs_compatibility disabled影响面最小→ 为某条管道在pipelines.yml设pipeline.ecs_compatibility: disabled锁定该管道→ 最后才考虑在config/logstash.yml全局关闭影响所有管道包括未来的新管道。注意 legacy 与 ECS 的字段差异以 GeoIP filter 为例关闭 ECS 时事件中的地理位置字段使用[geoip][...]结构开启 ECS 后则落在[geoip]之外按 ECS 规范组织如[client][geo]等切换模式会直接影响下游字段引用务必在切换后核对下游 filter 与 output 的字段路径。验证生效状态修改配置后重启 Logstash观察启动日志中的effective_ecs_compatibility信息确认每条管道实际生效的模式符合预期。显式配置优先记住 ECS 兼容模式只约束「隐式默认行为」——插件实例上的显式字段配置如source [host][ip]始终优先模式切换不会自动改写你显式写出的字段路径。总结Logstash 的 ECS 兼容模式通过ecs_compatibility一个配置项将 ECS 字段规范以「可选、可分粒度」的方式引入既有管道插件实例级实现精准微调管道级实现批量锁定进程级实现全局兜底且三者严格遵循「插件 管道 进程」的优先级。理解disabled/v1/v8三个取值、三级配置的覆盖关系以及启动日志中的生效确认信息即可在升级 Logstash 8 时从容掌控 ECS 与 legacy 行为避免事件字段结构突变带来的下游影响。【免费下载链接】logstashLogstash - transport and process your logs, events, or other data项目地址: https://gitcode.com/gh_mirrors/lo/logstash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考