OpenTelemetry Collector 组件弃用元数据规范增强方案

在OpenTelemetry Collector项目中，组件生命周期管理是一个重要环节。近期社区针对组件弃用(deprecated)状态的元数据规范提出了增强需求，旨在完善组件弃用过程的标准化管理。

背景与需求

当前OpenTelemetry Collector使用metadata.yaml文件中的deprecated字段来标记组件状态，但缺乏两个关键信息：

1. 弃用开始日期
2. 迁移指导说明

这导致用户在遇到弃用组件时，无法准确判断弃用时间节点，也难以获得明确的迁移路径。为解决这一问题，社区提出了增强元数据生成器(mdatagen)的功能需求。

技术方案设计

元数据字段扩展

新的元数据规范将扩展为支持以下字段结构：

deprecation:
  traces:
    date: "2025-02-01"  # 符合ISO 8601标准的日期格式
    migration: "迁移到新组件X的详细说明..."
  metrics:
    date: "2025-03-01"
    migration: "无可用迁移方案"

这种嵌套结构设计考虑到了组件可能对不同信号类型(如traces、metrics、logs)分别弃用的情况，为每种信号类型提供独立的弃用日期和迁移说明。

验证机制

mdatagen工具将增加以下验证逻辑：

1. 日期格式必须严格符合"YYYY-MM-DD"格式
2. 迁移说明字段不能为空，即使明确说明"无迁移方案"也需要显式声明
3. 当组件标记为弃用时，必须提供完整的弃用信息

文档生成

增强后的元数据将自动反映在生成的README.md中，包括：

• 明确的弃用日期标记
• 详细的迁移指导
• 按信号类型分类的弃用信息

实现考量

1. 向后兼容性：新规范需要保持与现有元数据文件的兼容，确保不破坏已有组件的构建流程。

2. 多信号支持：考虑到组件可能只弃用部分信号类型，数据结构设计需要支持细粒度的弃用声明。

3. 自动化检查：在CI流程中集成新的验证规则，确保新增或修改的弃用声明符合规范要求。

4. 用户体验：生成的文档需要清晰呈现弃用信息，帮助用户快速理解组件状态和迁移路径。

技术价值

这项增强将带来以下技术优势：

1. 提升透明度：明确的弃用日期帮助用户评估升级紧迫性
2. 降低迁移成本：详细的迁移说明减少用户调研时间
3. 规范管理：统一的元数据规范便于自动化工具处理
4. 历史追溯：标准化的日期格式支持组件生命周期分析

通过这项改进，OpenTelemetry Collector项目的组件管理将更加规范，为用户提供更完善的升级指导，同时也为维护者提供了更清晰的组件状态管理工具。