UModel 建模原则

1.1 域设计原则

原则说明：域（Domain）是UModel中最高层次的组织单位，代表了不同的业务领域或技术栈。

核心要求：

• 谨慎创建：域的创建需要经过团队充分讨论和评估，避免域的随意创建和重复。

• 业务对齐：每个域应当对应明确的业务边界或技术领域。

• 治理责任：每个域需要有明确的负责团队，负责该域下所有UModel资源的质量和一致性。

最佳实践：

# 推荐的域划分示例domains:- name: apm           # 应用性能监控owner: apm-teamdescription: 应用、服务、实例相关的实体和数据- name: infra         # 基础设施监控  owner: infra-teamdescription: 主机、容器、网络等基础设施实体- name: acs           # 阿里云服务owner: cloud-teamdescription: 云产品和资源相关实体

1.2 通用性原则

原则说明：实体定义应当具备良好的通用性和可扩展性，避免过度特化。

核心要求：

• 抽象层次适中：既不过于抽象导致无法使用，也不过于具体导致复用性差。

• 举一反三：考虑同类实体的共同特征，建立可复用的实体模式。

• 面向场景：基于实际使用场景设计实体，而不是基于数据源结构。

设计示例：

# 通用性好的设计entity_set:name: servicedescription: 通用的服务实体，适用于各种服务类型fields:- name: service_name        # 通用字段- name: service_type        # 支持不同类型：web/rpc/db等- name: language           # 开发语言- name: framework          # 技术框架# 避免过度特化的设计  # entity_set:#   name: spring_boot_web_service  # 过于具体

1.3 单一接入原则

原则说明：同一实体或数据集只应当接入一次，避免重复定义造成的数据混乱。

核心要求：

• 唯一数据源：每个实体类型对应唯一的权威数据源。

• 避免重复：不同域之间不应重复定义相同的实体类型。

• 协调机制：建立跨域协调机制，确保实体定义的一致性。

2.1 实体重要性评估

评估维度：

决策矩阵：

2.2 实体质量评估

数量控制标准：

• 生命周期总量：单一实体类型在生命周期内总数量应控制在千级别（<10,000）。

• 单实例规模：单一实体规模上限为10万条记录。

• 增长可控性：实体数量增长应当可预测和可控制。

Schema质量要求：

• 结构清晰：字段定义明确，类型一致。

• 变更稳定：Schema变更频率低，向后兼容。

• 语义完整：提供完整的字段说明和使用示例。

2.3 实体提取成本

成本评估维度：

优化建议：

• 优先选择ETL成本低的实体定义方案。

• 建立自动化的实体发现和维护机制。

• 通过批处理和流处理优化实体生成性能。

2.4 语义完整性

命名规范：

• 一致性：同类概念使用统一的命名模式。

• 可理解性：尽可能使用业界标准的术语。

• 精确性：避免模糊或有歧义的命名，确保语义准确。

语义质量：

• 完整性：每个实体和字段都有完整的中英文描述。

• 准确性：描述与实际功能和数据完全一致，避免歧义。

• 时效性：文档与系统实现保持同步更新。

3.1 关系类型标准化

标准关系类型：

关系选择指南：

1. 优先使用标准关系：尽可能避免创建自定义关系类型。

2. 语义明确：选择最能准确表达业务语义的关系类型。

3. 方向一致：同类关系保持一致的方向定义。

4. 跨域一致：多个域之间的关系方向尽可能保持一致，例如遵循自底向上或自顶向下原则。

3.2 关系方向原则

One-to-Many原则：

• 宿主关系：主机 hosts 进程（一个主机承载多个进程）。

• 包含关系：集群 contains 节点（一个集群包含多个节点）。

• 调用关系：服务A calls 服务B（一个服务可以调用多个服务）。

方向统一性：

• 同类关系在整个系统中保持一致的方向。

• 建立标准的关系方向映射表。

• 在文档中明确说明关系的方向语义。

3.3 EntitySetLink描述准确性

描述要求：

• 主次关系明确：清晰表达关系中的主体和客体。

• 时序关系明确：对于有时序特征的关系，明确先后顺序。

• is_same关系谨慎使用：该关系用于表示实体等价，需要特别谨慎。

# 良好的关系描述示例kind: entity_set_linkschema:url: "umodel.aliyun.com"version: "v0.1.0"metadata:name: "infra.host_hosts_apm.service"display_name:en_us: "Host hosts Service"zh_cn: "主机承载服务"description:en_us: "Indicates that a host provides the runtime environment for services"zh_cn: "表示主机为服务提供运行环境的关系"domain: infraspec:src:domain: infrakind: entity_setname: infra.hostdest:domain: apmkind: entity_setname: apm.serviceentity_link_type: hosts

3.4 跨域关联原则

一般情况，跨域关系需要通过一些计算逻辑才能建立，例如通过IP地址、域名、主机名等字段进行匹配。阿里云可观测2.0中的内置关系提供了自动计算的能力。若您需要手动配置这类跨域关系，请按照以下原则进行配置：

• 需求驱动：跨域的关联关系计算两个域都可实现，建议由最迫切需要该关联关系的业务模块负责配置。

• 性能优化：需要评估关联计算对底层存储计算性能的影响，并合理配置定期计算的频率。

• 数据质量：确保关联数据的准确性和时效性，避免关联数据不准确或过期导致的数据错误。

• 关联灵活性：选择功能丰富的定时、实时计算引擎，建议使用 SLS 提供的定时SQL功能实现。

3.5 关联数量控制

数量限制原则：

• 避免笛卡尔积：预防关联关系导致的数据爆炸。

• 分层设计：通过分层架构控制关联复杂度。

• 渐进式关联：先建立核心关联，再逐步扩展。

3.6 关联规则协作原则

责任分配原则：

• 业务责任：由最了解业务逻辑的团队负责定义关联规则。

• 技术责任：由平台团队提供关联计算的技术支持。

• 质量责任：建立关联质量的监控和反馈机制。

协作机制：

• 跨域关联需要相关域的团队共同评审。

• 建立关联变更的影响评估机制。

• 定期评估关联关系的有效性和准确性。

4.1 基础命名规范

字段名称格式：[a-z][a-z0-9_]*

命名原则：

• 小写字母开头：所有字段名必须以小写字母开头。

• 下划线分隔：使用下划线分隔多个单词。

• 语义明确：字段名应当清楚表达其含义。

• 长度适中：避免过长或过短的字段名。

示例：

# 正确的字段命名fields:- name: service_name- name: cpu_usage- name: last_update_time# 错误的字段命名# - name: ServiceName     # 驼峰命名# - name: cpu-usage       # 使用连字符# - name: 1st_metric      # 数字开头

4.2 EntitySet命名规范

格式要求：{domain}.{name}

命名原则：

• 域前缀必须：必须以域名开头，确保全局唯一性。

• 名称简洁：name部分应当简洁明了，避免冗余。

• 语义清晰：名称应当准确反映实体的业务含义。

示例：

# 正确的EntitySet命名entity_sets:- name: apm.service          # APM域的服务实体- name: infra.host          # 基础设施域的主机实体- name: acs.ecs.instance    # 阿里云ECS实例# 错误的EntitySet命名  # - name: service            # 缺少域前缀# - name: apm_service_entity # 冗余的entity后缀

4.3 DataSet命名规范

格式要求：{domain}.{DataSetShortType}.{name}

DataSetShortType类型：

• metric - 指标数据集。

• trace - 链路追踪数据集。

• log - 日志数据集。

• event - 事件数据集。

• profile - 性能剖析数据集。

示例：

# 正确的DataSet命名data_sets:- name: apm.metric.jvm           # APM域的JVM指标- name: apm.trace.http_request   # APM域的HTTP请求链路- name: infra.metric.system      # 基础设施系统指标- name: acs.log.access          # 阿里云访问日志# 错误的DataSet命名# - name: apm.jvm_metric         # 缺少DataSetShortType# - name: metric.apm.jvm         # 顺序错误

4.4 Link命名规范

格式要求：{src_object_name}_{LinkType}_{dest_object_name}

命名原则：

• 关系明确：链接名称应当清楚表达关系类型。

• 方向一致：源实体在前，目标实体在后。

• 类型标准：使用标准的关系类型名称。

示例：

# 正确的Link命名entity_set_links:- name: apm.service_calls_apm.service          # 服务调用关系- name: apm.service_contains_apm.operation     # 服务包含接口- name: infra.server_host_apm.instance         # 主机承载APM实例# 错误的Link命名# - name: service_link                          # 不明确的关系# - name: calls_service_service                 # 缺少域前缀

4.5 必填项规范

国际化要求：所有面向用户的文本都必须提供中英文版本

必填元数据：

# 必填的国际化字段示例display_name:en_us: "Service Name"zh_cn: "服务名称"description:en_us: "The unique identifier of the service"zh_cn: "服务的唯一标识符"short_description:en_us: "Service ID"zh_cn: "服务 ID"

质量要求：

• 准确翻译：中英文描述应当准确对应。

• 术语一致：使用统一的术语表。

• 语法正确：确保语法和拼写正确。

• 中英文衔接：中英文之间添加空格，更加清晰。

4.6 特殊情况处理

豁免机制：对于现有系统已经定义的特殊格式，可以通过@exempt注解申请豁免。

• 注意： 这种豁免机制只在于阿里云可观测团队内的 CommonSchema 规范审核，对于企业内部建模，请根据实际情况进行调整。

使用场景：

• 云产品原生字段格式与规范不符。

• 第三方系统集成的字段命名。

• 历史遗留系统的兼容性要求。

豁免示例：

fields:- name: StatusCode  # @exempt 该云产品本身字段定义为该格式description:en_us: "HTTP status code from cloud product API"zh_cn: "来自云产品 API 的 HTTP 状态码"exempt_reason: "阿里云 ECS API 原生字段格式"

审批要求：

• 提供详细的豁免理由。

• 评估对系统一致性的影响。

• 定期review豁免项的必要性。