构建可观测数据模型-UModel-云监控-阿里云

Field（字段）是 UModel 中数据的最基本单元，用于定义日志、指标、追踪、实体等数据的具体属性。每个 Field 包含完整的元数据信息，包括名称、类型、约束条件、显示特性等，是构建可观测数据模型的基础组件。

核心概念

Field 的定义和作用

Field 作为各种数据集的基础组成部分，为数据提供结构化的描述能力。在 UModel 中，Field 扮演着数据描述的核心角色：

数据结构定义：描述数据字段的类型、格式和约束。
语义表达：通过显示名称、描述等提供字段的业务语义。
查询能力：控制字段的可过滤、可分析、可排序等特性。
显示控制：定义字段在界面中的展示方式和格式化规则。

字段在数据模型中的位置

TelemetryDataSet/EntitySet
├── fields: Field[]           # 字段列表
├── time_field: string        # 时间字段引用
└── metrics: Metric[]         # 指标定义（MetricSet专有）

Field 属性规范

基础属性

以下是 Field 的核心属性配置：

属性名	类型	必填	默认值	描述	约束条件
`name`	string	是	-	字段在 UModel 系统中的唯一标识符	正则：`^[a-zA-Z][a-zA-Z0-9-_\.]{0,127}$` 长度：0-127字符
`display_name`	semantic_string	否	-	字段的多语言显示名称	支持中英文双语
`description`	semantic_string	否	-	字段的详细描述信息	支持中英文双语
`short_description`	semantic_string	否	-	字段的简短描述信息	支持中英文双语
`type`	enum	是	-	字段的数据类型	见数据类型表格
`launch_stage`	enum	否	preview	字段的发布阶段	见发布阶段表格

数据类型支持

UModel 支持以下数据类型：

类型	描述	适用场景	示例
`string`	字符串类型	文本数据、标识符、枚举值	“nginx-pod-123”, “ERROR”
`integer`	整数类型	计数器、状态码、端口号	8080, 200, 1024
`float`	浮点数类型	百分比、比率、小数值	85.6, 0.95, 3.14
`boolean`	布尔类型	开关状态、标志位	true, false
`time`	时间类型	时间戳、日期时间	“2024-01-15T10:30:00Z”
`json_object`	JSON对象类型	复杂结构化数据	{“status”: “active”, “count”: 5}
`json_array`	JSON数组类型	列表数据、多值字段	[“error”, “warn”, “info”]

发布阶段

字段的生命周期管理通过 launch_stage 属性控制：

阶段	描述	使用建议
`preview`	预览阶段（默认）	新功能测试，可能随时变更
`beta`	测试阶段	功能基本稳定，小范围使用
`ga`	正式发布	生产环境推荐使用
`deprecated`	已废弃	计划删除，不建议新项目使用

约束和验证属性

数值约束属性

用于控制数值类型字段的取值范围：

属性名	类型	适用类型	描述	示例
`min_value`	number	integer, float	字段的最小值	0, -100.5
`max_value`	number	integer, float	字段的最大值	100, 999.99
`default_value`	any	所有类型	字段的默认值	0, “INFO”, true

字符串约束属性

用于控制字符串类型字段的格式和长度：

属性名	类型	适用类型	描述	示例
`pattern`	string	string	正则表达式，用于验证字段值格式	`^[a-zA-Z][a-zA-Z0-9-]*$`
`max_length`	integer	string	字符串的最大长度	128, 255
`example`	any	所有类型	字段值的示例	“web-server-01”

分析特性属性

控制字段在查询和分析中的行为：

属性名	类型	默认值	描述	使用场景
`analysable`	boolean	false	是否可作为 Group By 的列进行聚合分析	维度字段（如地区、服务名）
`filterable`	boolean	false	是否支持索引过滤查询	常用查询条件字段
`orderable`	boolean	false	是否可排序	需要排序的数值或时间字段
`default_order`	enum	asc	默认排序方向：`asc`（升序）或 `desc`（降序）	时间字段通常用 desc

显示格式化

显示格式化属性

控制字段在界面中的显示方式：

属性名	类型	默认值	描述
`unit`	string	-	字段的显示单位，仅用于展示，不会进行格式转换
`data_format`	enum	KMB	字段的格式化方式，见格式化选项表格

unit 使用最佳实践：

优先配置 data_format，在大部分可观测场景下已可满足需求。
如 data_format 不满足需求，建议配置 data_format 为通用的 KMB，并配置 unit 为特定类型。
例如温度字段：data_format: "KMB", unit: "°C"。

数据格式化选项

data_format 支持以下格式化选项：

数值格式化

格式	描述	样例效果
`KMB`	千、百万、十亿格式化	1,234 → 1.23K

存储格式化

格式	描述	样例效果
`byte`	字节格式化	1024 → 1KB
`bit`	位格式化	8192 → 8Kb

速率格式化

格式	描述	样例效果
`byte_ies_sec`	每秒字节数格式化	1048576 → 1MB/s
`bit_ies_sec`	每秒位数格式化	1000000 → 1Mbps
`iops`	每秒IO操作数格式化	1000 → 1K io/s
`reqps`	每秒请求数格式化	5000 → 5K req/s

百分比格式化

格式	描述	取值范围	样例效果
`percent`	百分比格式化	1-100	85 → 85%
`percent_decimal`	小数百分比格式化	0-1	0.85 → 85%

时间格式化

格式	描述	样例效果
`localtime`	本地时间格式	1705310400 → 2024-01-15 18:00:00
`localtimems`	毫秒时间转本地时间	1705310400000 → 2024-01-15 18:00:00.000
`localtimeus`	微秒时间转本地时间	1705310400000000 → 2024-01-15 18:00:00.000000
`localtimens`	纳秒时间转本地时间	1705310400000000000 → 2024-01-15 18:00:00.000000000
`UTC±n`	特定时区时间	UTC+8, UTC-5 等

持续时间格式化

格式	描述	样例效果
`dtdhms`	天时分秒格式	90061 → 1d 01:01:01
`dthms`	时分秒格式	3661 → 01:01:01
`d` / `h` / `m` / `s`	按天/时/分/秒格式化	3600 → 1h
`ms` / `us` / `ns`	按毫秒/微秒/纳秒格式化	1500 → 1.5s

值映射和扩展属性

值映射属性

为枚举类型字段提供值到显示内容的映射：

属性名	类型	描述
`value_mapping`	map	枚举值的映射配置，key 为原始值，value 为映射对象

值映射对象包含以下属性：

name: 映射后的名称标识符
display_name: 多语言显示名称
description: 多语言描述信息
short_description: 多语言简短描述

扩展属性

用于附加元数据和自定义配置：

属性名	类型	描述	示例
`icon`	string	字段图标的URL地址（实验性功能）	`https://example.com/icon.png`
`uri`	string	字段的唯一标识URI（实验性功能）	`/metrics/cpu_usage`
`tags`	map	字段的标签信息，用于分类和检索	`{"category": "performance"}`
`properties`	map	字段的附加属性信息	`{"alert_threshold": "80"}`

典型配置示例

监控指标字段

CPU使用率字段

属性	值	说明
name	`cpu_usage_percent`	字段标识符
display_name	`{"zh_cn": "CPU使用率", "en_us": "CPU Usage"}`	多语言显示名
type	`float`	浮点数类型
min_value	`0.0`	最小值
max_value	`100.0`	最大值
data_format	`percent`	百分比格式化
unit	``	单位不用额外配置
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析
orderable	`true`	支持排序

内存使用量字段

属性	值	说明
name	`memory_used_bytes`	字段标识符
display_name	`{"zh_cn": "内存使用量", "en_us": "Memory Used"}`	多语言显示名
type	`integer`	整数类型
min_value	`0`	最小值
data_format	`byte`	字节格式化
unit	``	单位不用额外配置
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析

日志字段

日志级别字段

属性	值	说明
name	`log_level`	字段标识符
display_name	`{"zh_cn": "日志级别", "en_us": "Log Level"}`	多语言显示名
type	`string`	字符串类型
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析
value_mapping	见值映射示例	枚举值映射

日志级别值映射示例：

{
  "DEBUG": {
    "name": "debug",
    "display_name": {"zh_cn": "调试", "en_us": "Debug"}
  },
  "INFO": {
    "name": "info", 
    "display_name": {"zh_cn": "信息", "en_us": "Info"}
  },
  "ERROR": {
    "name": "error",
    "display_name": {"zh_cn": "错误", "en_us": "Error"}
  }
}

HTTP状态码字段

属性	值	说明
name	`http_status_code`	字段标识符
type	`integer`	整数类型
min_value	`100`	HTTP状态码最小值
max_value	`599`	HTTP状态码最大值
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析

链路追踪字段

Trace ID字段

属性	值	说明
name	`trace_id`	字段标识符
type	`string`	字符串类型
pattern	`^[a-f0-9]{32}$`	32位十六进制格式
max_length	`32`	固定长度32字符
filterable	`true`	支持过滤查询
analysable	`false`	高基数，不建议聚合

操作持续时间字段

属性	值	说明
name	`duration_ms`	字段标识符
type	`float`	浮点数类型
min_value	`0.0`	最小值
data_format	`ms`	毫秒格式化
unit		单位不用额外配置
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析
orderable	`true`	支持排序
default_order	`desc`	默认降序排列

实体标识字段

主机名字段

属性	值	说明
name	`hostname`	字段标识符
type	`string`	字符串类型
max_length	`128`	最大长度
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析

Pod名称字段

属性	值	说明
name	`pod_name`	字段标识符
type	`string`	字符串类型
pattern	`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`	K8s命名规范
max_length	`63`	Kubernetes最大长度限制
filterable	`true`	支持过滤查询
analysable	`true`	支持聚合分析