如果你在用 Elastic 的日志采集(Filebeat、Elastic Agent),文档里的字段是 ECS 命名(
span.id、log.level)。9.1 加了个 ingest 处理器,能把这些字段改成 OpenTelemetry 的写法(span_id、severity_text)。目的是让 ES 能直接"按 OTel 方式"存日志。
说明
实测环境:本地起的 Elasticsearch 9.4.2 单节点实例(官方 tar 包直接跑,堆内存 512MB,安全与机器学习关闭),curl 连本地 9200 端口。本文「实测」小节的命令和输出都出自这个实例。
来源和边界先交代:本文的依据出自 v9.4.2 标签下的官方文件(9.1.0.yml、9.2.0.yml、NormalizeForStreamProcessor.java),文中引用的原文均来自这些文件。示例取自官方示例;哪些是文档写明、哪些是我的推断,正文里逐处标注。
图 1:官方文件 9.1.0.yml(v9.4.2 标签)。来源:GitHub elastic/elasticsearch v9.4.2 9.1.0.yml
官方条目
9.1 的 changelog 标为 feature(9.1.0.yml 第 740–743 行 @ v9.4.2),area: Ingest Node:
Adding `NormalizeForStreamProcessor`
9.2 还有一条扩展(9.2.0.yml 第 1091 行 @ v9.4.2):
Add support for flexible access pattern to `NormalizeForStreamProcessor`
两条都只有一行 summary。下面的内容全部来自源码——而源码写得意外地清楚。
图 2:官方文件 NormalizeForStreamProcessor.java(v9.4.2 标签)。来源:GitHub elastic/elasticsearch v9.4.2 NormalizeForStreamProcessor.java
两套命名规范
ECS(Elastic Common Schema):Elastic 自己定义的一套字段命名规范。日志里的常见字段:
messagelog.leveltrace.idspan.id
OpenTelemetry(OTel):CNCF 下的可观测性标准,也是一套命名:
body.textseverity_texttrace_idspan_id
两者表达的是同一件事,写法不同。 ECS 用点分层级,OTel 用下划线。
图 3:官方文件 9.2.0.yml(v9.4.2 标签)。来源:GitHub elastic/elasticsearch v9.4.2 9.2.0.yml
处理器做了什么
源码里的映射表写得非常直白(NormalizeForStreamProcessor.java 第 50–56 行,源码 @ v9.4.2):
/**
* Mapping of ECS field names to their corresponding OpenTelemetry-compatible counterparts.
*/
static final Map<String, String> RENAME_KEYS = Map.ofEntries(
entry("span.id", "span_id"),
entry("message", "body.text"),
entry("log.level", "severity_text"),
entry("trace.id", "trace_id")
);
四条重命名:
| ECS | OTel |
|---|---|
span.id | span_id |
message | body.text |
log.level | severity_text |
trace.id | trace_id |
类型名在源码第 47 行:
public static final String TYPE = "normalize_for_stream";
所以 pipeline 里的处理器类型写 normalize_for_stream。
不只是改名
源码里还有一段说明"哪些字段留在顶层"(第 62–80 行):
private static final Set<String> KEEP_KEYS;
...
Set<String> keepKeys = new HashSet<>(Set.of("@timestamp", "attributes", "resource"));
注释解释得很清楚:
A closed-set of keys that should be kept at the top level of the processed document after applying the namespacing. In essence, these are the fields that should not be moved to the "attributes" or "resource.attributes" namespaces.
大意:有一批字段留在顶层,其余的会被移到 attributes 或 resource.attributes 命名空间下。
这就是 "normalize for stream" 里 "stream" 的含义——OTel 的日志流有固定的顶层结构(body、attributes、resource、scope 等),其余自定义字段都归到 attributes / resource.attributes 下。源码里能看到这几个键名常量(第 81–86 行):
private static final String ATTRIBUTES_KEY = "attributes";
private static final String RESOURCE_KEY = "resource";
private static final String SCOPE_KEY = "scope";
private static final String BODY_KEY = "body";
private static final String TEXT_KEY = "text";
private static final String STRUCTURED_KEY = "structured";
这几个常量就是 OTel 日志模型的顶层字段。它们挨个列出来,比任何说明都直观。
所以这个处理器做两件事:
- 重命名那四个已知字段;
- 把其余字段归拢到
attributes/resource.attributes命名空间。
OTel 文档直接跳过
类注释里有一句(第 41 行附近):
If a document is identified as OpenTelemetry-compatible, no transformation is performed.
如果文档已经被识别为 OTel 兼容,就不做任何转换。
这点设计得对:幂等。同一个文档处理两次不会产生奇怪的结果,也不会把已经是 OTel 写法的字段再改一遍。
对使用者的意义:可以无条件把它放进 pipeline,不用担心数据来源是不是已经 OTel 化了。混合来源(一部分 ECS、一部分 OTel)的情况下尤其省事——不用在 pipeline 里做分支判断。
9.2 那条"flexible access pattern"是什么
9.2 的扩展从名字看是访问模式更灵活。源码里能找到一点痕迹(第 339 行):
// Dotted fields are treated the same as normalized fields in flexible mode
"flexible mode"(灵活模式)下,点号字段和已规范化字段同样处理。
推测(这是理解,官方没解释):早期版本对字段名带点(log.level)和嵌套形式({"log": {"level": ...}})的处理可能不一致,9.2 统一了。
(说明:"flexible mode" 具体怎么开启、有哪些参数,未查证。源码里只看到这一处注释。)
为什么要做这个转换
我的判断是这是最值得说的一层:它决定了这次迁移的成本主要落在迁移之外。
日志数据的存储方式在变。Elastic 的传统方式是用 ECS + 自己的数据结构;OTel 是行业通用标准。如果 ES 能按 OTel 的结构存日志,那么:
- 和其它 OTel 生态的工具互通更容易;
- 同一份数据不用为不同系统维护不同的字段映射;
- 采集端如果是 OTel Collector,数据可以直接进。
这个处理器是过渡期的工具:让已经用 ECS 采集的数据,也能转换成 OTel 结构存下来。
它的存在本身就说明一件事:ES 在向 OTel 靠拢。本篇是"为标准互通补工具"这个方向上的一个具体例子——和给 AI 助手准备存储位置那类改动一样,都属于生态适配。
日志字段为什么会有两套
上面说"两套命名",这里补一点背景,因为不理解由来会觉得这是无谓的折腾。
ECS 是 Elastic 自己定义的,出现得早,围绕 Elastic Stack 设计。它的好处是和 Kibana 深度适配——Discover 里看到的字段、内置的可视化、告警模板,都按 ECS 来的。
OTel 是行业中立的,由 CNCF 托管,目标是让可观测性数据在不同厂商之间流通。它的日志模型有固定的顶层结构:body(正文)、attributes(属性)、resource(来源)、trace_id/span_id(链路关联)。
两套并存的原因是历史性的:ECS 出现时 OTel 还没成气候;等 OTel 成为事实标准,Elastic 已经有大量用户按 ECS 存数据了。
所以现在的局面是"都要支持":
- 老用户继续用 ECS,不能断;
- 新场景(尤其是从 OTel Collector 进来的数据)要按 OTel 存。
normalize_for_stream 就是为这个过渡服务的——让"按 ECS 采集"的数据也能"按 OTel 存"。
(说明:这段背景是理解,官方没在这条条目里解释动机。)
什么时候需要它
按理解:
需要的场景:
- 你希望日志按 OTel 结构存储(比如要用 ES 的 OTel 原生支持);
- 数据来源是传统的 Elastic Agent / Filebeat(产出 ECS);
- 想统一混合来源的字段结构。
不需要的场景:
- 现有 ECS 结构工作得好好的,没有切换 OTel 的需求;
- 下游(Kibana、告警、报表)依赖 ECS 字段名——改了会全部失效。
第二条是硬约束:字段名一改,所有引用这些字段的地方都要跟着改。Kibana 的 Discover、可视化、告警规则、自定义查询——凡是写了 log.level 的地方。
所以我的建议是:先确认真的需要 OTel 结构,再上这个处理器。它是一次数据结构迁移,不是一个"改了更好"的优化——迁移的成本主要在迁移之外。
迁移类改动要衡量连带成本
这条改动技术上很简单——四条重命名加一次归拢。但它属于迁移类改动,成本不在它本身,在连带影响面。
按这个角度评估过它:
| 维度 | 判断 |
|---|---|
| 处理器本身复杂度 | 低 |
| 配置成本 | 低(加到 pipeline 里) |
| 下游影响面 | 可能很大 |
| 是否可逆 | 是(去掉处理器、重建) |
关键在第三行。 字段改名的影响会扩散到所有消费方,而这些地方往往分散在不同系统里,容易漏。
实操建议:如果决定做这个迁移,先列一份字段清单,把下游所有引用点找出来。这步做完,才知道成本有多大。不要先改数据再改下游——中间会出现一段"数据已经变了、查询还没改"的空窗期。
在 9.4.2 上跑一遍
同一份 ECS 风格的日志,一条直接入库、一条过一遍 normalize_for_stream:
图 4:本地 9.4.2 单节点实例上的实测输出。上:不过处理器;下:过了处理器
curl -s -X PUT "http://localhost:9200/_ingest/pipeline/nfs-p" \
-H 'Content-Type: application/json' -d '{"processors":[{"normalize_for_stream":{}}]}'
curl -s "http://localhost:9200/nfs/_search?filter_path=hits.hits._source"
curl -s -X POST "http://localhost:9200/_ingest/pipeline/nfs-p/_simulate" \
-H 'Content-Type: application/json' \
-d '{"docs":[{"_source":{"@timestamp":"2026-01-01T00:00:00Z","host.name":"h1","message":"up"}}]}' \
| jq -c '.docs[0].doc._source'
不过处理器时 _source 原封不动:{"@timestamp":"2026-01-01T00:00:00Z","host.name":"h1","message":"up"}。
过了之后变成 {"attributes":{},"@timestamp":"...","body":{"text":"up"},"resource":{"attributes":{"host.name":"h1"}}}——三处变化:message 进了 body.text,host.name 进了 resource.attributes,还多了一个空的 attributes 壳。
前两处是"搬到 OTel 该在的位置",第三处是凭空多出来的空对象。这一条最容易在下游出问题:按字段数做校验、或者遍历 attributes 的代码,会碰到空壳。
结论是:这个处理器是迁移工具,不是优化工具——它不改变数据量,只改变字段摆在哪。接入前先确认下游是按 OTel 结构读的;还按 ECS 读的话,加了它只会让所有查询取不到东西。
写在最后
一个很具体的处理器:把 ECS 的四个字段改成 OTel 写法,其余归到 attributes 下。
一,类型名是 normalize_for_stream,映射的四条字段在源码里写得很清楚(message→body.text 等)。
二,它做两件事:重命名 + 把其余字段归拢到 attributes / resource.attributes。
三,对已经是 OTel 格式的文档不做处理,可以安全地放进 pipeline。
四,字段改名的影响面比处理器本身大得多,决定前先列下游引用清单——所有的可视化、告警规则、自定义查询都要跟着改。
另外诚实标注三处:"flexible mode" 的开启方式和参数未查证(只看到一处注释);完整的命名空间归拢规则未逐个跟踪(只确认了顶层保留集合的构造逻辑);这个处理器的完整配置参数未核对。
参考
- changelog 9.1.0:Adding
NormalizeForStreamProcessor(第 740–743 行)@ v9.4.2 - changelog 9.2.0:flexible access pattern(第 1091 行)@ v9.4.2
NormalizeForStreamProcessor.java:类型名(第 47 行)、ECS→OTel 映射表(第 50–56 行)、顶层保留字段(第 62–80 行)@ v9.4.2NormalizeForStreamPlugin.java:插件注册 @ v9.4.2
本文对照 Elasticsearch
v9.4.2标签的 changelog 与源码核对,引文与代码逐字取自原文。图 4 实测了默认模式下的改写结果(message→body.text、host.name→resource.attributes.host.name,并多出空的attributes)。"flexible mode" 的开启方式与参数未查证,仅见第 339 行注释;完整的命名空间归拢规则未逐个跟踪,仅确认顶层保留集合(KEEP_KEYS)的构造逻辑;处理器的完整配置参数未核对;ECS 与 OTel 的背景说明为通用认知。
