tenzir-ecs

Elastic Common Schema

Elastic Common Schema（ECS）定义了日志、指标、安全遥测和可观测性数据的通用字段，使来自不同来源的事件能够以一致的方式进行查询和关联。

此技能基于本仓库中最新支持的 ECS 版本生成：v9.5.0 / 9.5.0。 请将 YAML 文件作为权威参考，用于确认准确的字段名、字段集、类型、级别、允许值、规范化提示、复用元数据和 OpenTelemetry 关系。 Markdown 文档仅用于了解概念、映射示例和实现约定。 如果 YAML 数据中未提供某个字段、字段集、允许值或关系，请说明此处未记录。

数据文件

• 使用 fields.yaml 查找 ECS 点分字段，然后加载其引用的 fields/<field>.yaml 文件。
• 使用 fieldsets.yaml 选择字段集，然后加载其引用的 fieldsets/<fieldset>.yaml 文件。
• 使用 categorization.yaml 查询 event.kind、event.category、event.type、event.outcome、允许值以及预期的 category/type 组合。
• 使用 otel.yaml 查看以 ECS 键为索引的 OpenTelemetry 关系速查表。
• 使用 source.md 查看版本来源、源文件、复制的文档、引用的上游文档和计数。

补充文档

• 有关一般建模问题，请从 实现模式、设计原则 和 约定 开始。
• 分配 event.* 分类值时，请使用 categorization.yaml 和 使用分类字段。
• 有关 source/destination 与 client/server 的选择，请参阅 映射网络事件。
• ECS 没有合适字段时，请参阅 自定义字段。
• 有关 OTel 对齐问题，请结合使用 ECS 与 OpenTelemetry 和 otel.yaml。
• 有关映射场景，请参阅以下专题使用文档：cloud、service、threat 和 user。

映射规则

• 优先填充必需字段：@timestamp 和 ecs.version。
• 字段语义匹配时，优先使用有文档说明的 ECS 字段，而不是自定义字段。
• ECS 没有匹配字段时，请在自定义字段中保留来源特有的细节；适当情况下，可使用 labels 存储少量关键字元数据。
• 分类时，仅使用 categorization.yaml 中的允许值；没有合适的允许值时，将分类字段留空。
• 将 event.category 和 event.type 视为数组；仅当事件合理地属于多个类别或类型时，才使用多个值。
• 使用 fieldsets.yaml 中的字段集复用元数据，区分 user.target、process.parent、cloud.origin 和 service.target 等特定角色的位置。
• 对于网络事件，使用 source/destination 表示数据包或流量方向；已知端点角色时，也应填充 client/server。
• 文档或字段语义要求跨字段搜索时，请将透视值复制到 related.* 中。

问题路由

• 字段 X 表示什么？ 从 fields.yaml 开始，然后加载所选字段的 YAML 文件。
• 字段集 X 下有哪些字段？ 从 fieldsets.yaml 开始，然后加载所选字段集的 YAML 文件。
• 我应该使用哪个 event.category 或 event.type？ 从 categorization.yaml 开始，然后阅读 使用分类字段 中的示例。
• 我应该如何映射网络事件？ 阅读 映射网络事件，然后检查相关字段集。
• 我该如何建模用户、云资源、服务或威胁指标？ 阅读 docs/usage/ 下对应的用法文档，然后检查相关字段集的 YAML 文件。
• ECS 与 OpenTelemetry 有什么关系？ 使用 otel.yaml 查看精简的字段对照表，并阅读 ECS 与 OpenTelemetry 了解概念性指导。
• 如果 ECS 中没有匹配的字段，该怎么办？ 阅读 自定义字段。
• 此技能基于哪个上游原始来源？ 使用 source.md。