企业官网建设流程全解析

Logstash 中的 ECS 兼容模式（ecs_compatibility）完整配置指南

【免费下载链接】logstashLogstash - transport and process your logs, events, or other data项目地址: https://gitcode.com/gh_mirrors/lo/logstash

导读

Elastic Common Schema（ECS）是一套开放的事件字段规范，帮助用户将日志、指标等事件数据归一化，从而在 Elasticsearch 中更高效地分析、可视化与关联数据。本文聚焦 Logstash 的 ECS 兼容模式机制：从单个插件实例、单个管道到整个进程三个层级，详解ecs_compatibility的配置方法、默认值与优先级，并结合仓库源码剖析其参数校验、默认值来源与生效链路，帮助你精准掌控 Logstash 8 中 ECS 与 legacy 行为的切换，平滑完成既有管道的升级。

ECS 是什么，为什么 Logstash 需要它

ECS（Elastic 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的合法取值有三类：

从源码看，这个取值并非自由字符串，而是经过严格校验的。在 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）依次解析：

1. 若插件配置中显式设置了@ecs_compatibility，直接采用插件实例值；
2. 否则从当前插件的execution_context.pipeline.settings读取pipeline.ecs_compatibility（即管道级或进程级值）；
3. 若管道上下文缺失，回退到全局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 disabled

• Central Management：x-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