血缘元数据采集开放标准：OpenLineage Integrations Compatibility Tests Structure

OpenLineage 是一个用于元数据和血缘采集的开放标准，专为在作业运行时动态采集数据而设计。它通过统一的命名策略定义了由作业（Job）、运行实例（Run）和数据集（Dataset） 组成的通用模型，并通过可扩展的Facets机制对这些实体进行元数据增强。
该项目是 LF AI & Data 基金会的毕业级项目，处于活跃开发阶段，欢迎社区贡献。

兼容性测试

Compatibility Tests

兼容性测试是一套全面的测试套件，旨在提升可见性并标准化对OpenLineage与不同组件兼容性的验证。

它由一个GitHub仓库组成，其中包含GitHub Actions工作流，持续检查OpenLineage不同版本与各类producer或consumer版本之间的兼容性。结果经过解释并可视化为兼容性表格，展示在OpenLineage兼容性文档中。

检查通过对producer和consumer进行语法和语义验证来执行：

• 对于producer：我们定义测试场景生成OpenLineage事件，验证其是否符合预期结构（语法）以及事件字段中的值（语义）
• 对于consumer：我们发送有效的OpenLineage事件，验证它们能否被正确摄取（语法）并引发consumer状态中的预期变更（语义）

动机

OpenLineage社区缺乏一种正式方式来确定组件是否符合标准。
社区成员不得不在供应商网站或文档中查找支持信息，常常发现不一致或过时的内容。

目标

OpenLineage社区中有三类主要群体：为OpenLineage贡献的人、为兼容OpenLineage的组件贡献的人，以及将OpenLineage与这些软件一起使用的人。我们希望测试套件能提供这些群体可能需要的关于OpenLineage的信息。

对于组件贡献者：

• 持续测试其组件与多个OpenLineage版本的兼容性，包括：
  • 集成 - 组件与OpenLineage集成运行时是否存在问题（producer）
  • 语法 - 发出的事件是否符合OpenLineage标准（producer）或能否无错误地消费（consumer）
  • 语义 - 发出的事件是否正确反映逻辑（producer）或是否以正确方式映射到consumer实体（consumer）
• 提供自行验证事件的方式

对于OpenLineage贡献者：

• 持续测试新的或更新的facet是否向后兼容
• 对组件集成新版本中的问题提供早期预警

对于OpenLineage用户：

• 生成关于各种组件对OpenLineage支持程度的最新且易于获取的信息
• 提供不同组件生成的OpenLineage事件示例

假设

在创建测试套件时，我们在以下几个关键方面关注其对社区的实用性：

1. 简单表示：测试结果应以清晰易懂的格式呈现
2. 轻松贡献：贡献应尽可能简单
   • 每个组件及其测试场景应具有一致的结构和输出
   • 每个组件应独立于其他组件
   • 验证机制应通用且可复用
3. 本地执行：验证机制应在工作流之外可运行 - 工作流应执行单独定义的模块，这些模块可在本地运行
4. 全面测试：测试应验证语法和语义合规性
5. 文档化：测试套件应有良好文档
   • producer场景应包含操作、数据集和facet的描述
   • consumer场景应描述消费事件后的预期状态变更
   • 每个consumer应提供OpenLineage事件实体与其自身数据模型之间的映射

:maxdepth: 1
:hidden:structure.md
test_workflows.md
reusable_actions_and_common_scripts.md

结构

Structure

生产者

包含与特定生产者相关的文件和目录。每个生产者应包含：

• runner 目录，包含运行测试所需的文件
• scenarios 目录，包含场景目录
• maintainers.json 文件，列出在组件失败时通知的人员
• versions.json 文件，列出支持的 OpenLineage 和组件版本

生产者目录结构

producer
└── example_producer├── maintainers.json├── versions.json├── runner│   └── ...└── scenarios├── ...└── example_scenario├── config.json├── events│   ├── ...│   └── expected_event_structure_1.json├── maintainers.json├── scenario.md└── test└── scenario_test_script

Runner

包含运行生产者测试所需的任何脚本或资源。

Scenarios

scenarios 目录包含一个或多个子目录，每个子目录包含与特定测试场景相关的文件：

• config.json 文件，包含场景配置
• scenario.md 文件，包含场景描述
• maintainers.json 文件，列出负责该场景的人员

配置

每个配置文件包含场景中测试的元数据。有三种类型的元数据：

1. 场景范围配置

   • 场景版本过滤器：我们可能希望针对许多版本的 OpenLineage 测试许多版本的生产者，但并非每个测试场景都需要针对每个版本运行。这些过滤器允许我们定义希望运行场景的 OpenLineage 或生产者的最低和最高版本。

2. 测试范围配置

   • name：测试名称
   • path：此测试将使用的预期事件路径
   • test version filters：定义 OpenLineage 或生产者的最低和最高版本。过滤掉的测试的语义测试将被跳过。

3. 测试标签：它们将出现在报告中并反映在兼容性表中

   • facets：测试检查的 facets 列表
   • lineage level：指示数据集血缘级别
     • dataset → 无列级血缘
     • column → 列级血缘可用
     • transformation → 转换信息可用

示例配置

{"component_versions": {"min": "0.0.1","max": "9.99.9"},"openlineage_versions": {"min": "0.0.1","max": "9.99.9"},"tests": [{"name": "name","path": "path/to/file.json","component_versions": {"min": "0.0.1","max": "9.99.9"},"openlineage_versions": {"min": "0.0.1","max": "9.99.9"},"tags": {"facets": ["list","of","supported","facets"],"lineage_level": {"bigquery": ["dataset","column","transformation"]}}}]
}

Events

目录包含预期事件，形式为 JSON 文件。有关设置验证事件的更多信息，请参见事件验证。

消费者

消费者目录包含两个子目录：

• consumers - 包含消费者列表及其测试场景
• scenarios - 场景中使用的输入事件，目录与消费者定义分开，以便事件可被多个消费者用于测试

每个 scenarios 目录中的目录包含以下内容：

• events - 包含用于消费者测试的 openlineage 事件的目录
• maintainers.json - 列出负责场景事件的人员的文件
• scenario.md - 场景事件的人类可读描述（生产者类型、输入、输出、facets、执行的操作）

每个目录代表一个消费者，包含：

• validator - 包含验证逻辑的目录（不同于生产者，生成的 Openlineage 事件可通过通用组件验证）
• mapping.json - 包含 Openlineage 事件与消费者 API 实体之间映射的文件
• maintainers.json - 列出负责组件的人员的文件
• scenarios - 包含场景目录的目录，结构如下：
  • config.json - 包含场景配置的文件
  • scenario.md - 场景的人类可读描述（消费者状态的预期变化）
  • maintainers.json - 列出负责场景的人员的文件
  • validation - 包含用于验证的消费者 API 预期状态的目录

消费者目录结构

consumer
├── consumers
│   └── <consumer name>
│       ├── README.md
│       ├── maintainers.json
│       ├── mapping.json
│       ├── run_dataplex_tests.sh
│       ├── scenarios
│       │   ├── ...
│       │   └── <scenario name>
│       │       └── api_state
│       │           ├── config.json
│       │           ├── maintainers.json
│       │           ├── scenario.md
│       │           └── validation
│       │               ├── ...
│       │               └── validation_file
│       └── validator
│           └── validator.py
└── scenarios├── ...└── <scenario name>├── config.json├── events│   ├── ...│   └── openlineage_event.json├── maintainers.json└── scenario.md

Validator

包含运行消费者测试所需的任何脚本或资源。

Scenarios

scenarios 目录包含为任何消费者运行测试定义的输入事件。每个场景包含：

• 事件文件目录
• maintainers.json 文件，列出负责场景的人员
• scenario.md 文件，包含场景描述，包含对消费者场景创建者有用的信息（例如，哪个生产者创建了它们，它们代表什么等）

配置

示例消费者场景配置

{"tests": [{"name": "name","path": "path/to/file.json","entity": "entity","tags": {"facets": ["list","of","supported","facets"],"producer": "producer"}}]
}

每个配置文件包含场景测试的元数据，与生产者场景不同，我们可以在为现有输入事件定义场景时决定运行哪个场景。因此所有配置都在测试范围内。

1. 配置
   1. name - 测试名称
   2. path - 此测试将使用的预期事件路径
   3. entity - 提示此测试涵盖的实体
2. 测试标签 - 它们将出现在报告中并反映在兼容性表中
   1. facets - 测试检查的 facets 列表
   2. producer - 事件的生产者名称

验证

目录包含表示发送 OpenLineage 事件后消费者预期状态的 JSON 文件。
事件可以是确切的预期状态，也可以使用事件比较中定义的方法。

映射

映射文件包含 OpenLineage 事件与消费者 API 实体之间的映射。它有两个功能，第一个是文档，让任何人知道此消费者从 OpenLineage 事件中提取多少信息。第二个是定义测试的基本期望，即如果测试声称支持特定 facet，则可以检查我们应在此测试中期望哪些实体。

如果可能，文件应包含映射实体列表以及未映射的 facets 列表。

示例映射结构

{"mapped": {"core": {"eventTime": "Consumer entity representing event time","run.id": "Consumer entity ID","job.name": "part of consumer entity name","job.namespace": "part of consumer entity name",...},"ExampleFacet": {"field1": "Consumer entity field","field2": "Consumer entity field"  },...},"knownUnmapped": {"ExampleUnmappedFacet": ["*"],...}
}

辅助脚本

目录包含工作流使用的脚本、操作使用的内部脚本以及生产者和消费者测试使用的公共类。

生成的文件

包含工作流自动生成或更新的文件。

报告

report.json 包含所有测试结果。其主要用途是：

1. 检查新失败 - 我们希望发送失败通知，但如果同一失败在多次运行中发生，我们不希望重复这些通知。
   因此每次将测试中的失败与报告中已有的失败进行比较。如果失败已在报告中，我们不发送通知。
2. 兼容性表的输入 - 报告文件用于生成兼容性表，作为我们最完整的事实来源。

{"name": "component name","component_type": "[producer|consumer]","component_version": "1.2.3","openlineage_version": "1.2.3","scenarios": [{"name": "hive","status": "[SUCCESS|FAILURE]","tests": [{"name": "test_name","status": "[SUCCESS|FAILURE]","validation_type": "[syntax|semantics]","entity_type": "[openlineage|consumer_entity_type]","details": [],"tags": {}}]}]
}

发布和 Spec 版本

为了检查 spec 的更改或新发布，我们需要存储有关已检查的最新版本的信息。
releases.json 存储有关我们上次检查的 OpenLineage 或组件的发布信息。

示例发布条目

[{"name": "openlineage","latest_version": "1.2.3" // 最新已检查发布},{"name": "versioned component","latest_version": "1.2.3" // 最新已检查发布},{"name": "non-versioned component","latest_version": "" // 无发布，意味着我们在每次工作流运行时检查}
]

spec_versions.json 存储有关已检查的 spec 和 facets 的最新版本的信息。

示例 spec 版本条目

{"OpenLineage": {"major": "1","minor": "2","patch": "3"},"ExampleFacet": {"major": "1","minor": "2","patch": "3"}
}

风险提示与免责声明
本文内容基于公开信息研究整理，不构成任何形式的投资建议。历史表现不应作为未来收益保证，市场存在不可预见的波动风险。投资者需结合自身财务状况及风险承受能力独立决策，并自行承担交易结果。作者及发布方不对任何依据本文操作导致的损失承担法律责任。市场有风险，投资须谨慎。