Field system - Cloud Monitor - Alibaba Cloud Documentation Center

A field is the basic unit of data in UModel, representing specific properties such as logs, metrics, traces, or entities. Each field includes comprehensive metadata, detailing its name, type, constraints, and display characteristics. Fields serve as the essential building blocks for constructing observable data models.

Core concepts

Definition and role of a field

A field is a fundamental part of any dataset, providing a structured description of data. In UModel, fields play a core role in the following areas:

Data structure definition: Specify the type, format, and constraints.
Semantic expression: Convey business meaning through display name and description.
Query capability: Indicate whether the field can be filtered, analyzed, or sorted.
Display control: Define how the field is shown in the user interface, including formatting rules.

Position of fields in the data model

TelemetryDataSet/EntitySet
├── fields: Field[]           # List of fields
├── time_field: string        # Reference to time field
└── metrics: Metric[]         # Metric definitions (MetricSet only)

Field property specifications

Basic properties

The following are the core property configurations for a field:

Property	Type	Required	Default value	Description	Constraints
`name`	string	Yes	-	The unique identifier for the field in the UModel system.	Regular expression: `^[a-zA-Z][a-zA-Z0-9-_\.]{0,127}$` Length: 0 to 127 characters
`display_name`	semantic_string	No	-	The multilingual display name of the field.	Supports Chinese and English.
`description`	semantic_string	No	-	A detailed description of the field.	Supports Chinese and English.
`short_description`	semantic_string	No	-	A short description of the field.	Supports Chinese and English.
`type`	enum	Yes	-	The data type of the field.	See the Data types table.
`launch_stage`	enum	No	preview	The launch stage of the field.	See the Launch stages table.

Supported data types

UModel supports the following data types:

Type	Description	Scenarios	Example
`string`	String type	Text data, identifiers, enumeration values	"nginx-pod-123", "ERROR"
`integer`	Integer type	Counters, status codes, port numbers	8080, 200, 1024
`float`	Floating-point number type	Percentages, ratios, decimal values	85.6, 0.95, 3.14
`boolean`	Boolean type	Switch statuses, flags	true, false
`time`	Time type	Timestamps, date and time	"2024-01-15T10:30:00Z"
`json_object`	JSON object type	Complex structured data	{"status": "active", "count": 5}
`json_array`	JSON array type	List data, multi-value fields	["error", "warn", "info"]

Launch stages

The lifecycle of a field is managed by the launch_stage property:

Stage	Description	Recommended use
`preview`	Preview stage (default)	For testing new features. Subject to change.
`beta`	Beta stage	Feature is mostly stable. For limited use.
`ga`	General Availability (GA)	Recommended for production environments.
`deprecated`	Deprecated	Scheduled for removal. Not recommended for new projects.

Constraint and validation properties

Numeric constraint properties

These properties control the value range for numeric field types:

Property	Type	Applicable types	Description	Example
`min_value`	number	integer, float	The minimum value of the field.	0, -100.5
`max_value`	number	integer, float	The maximum value of the field.	100, 999.99
`default_value`	any	All types	The default value of the field.	0, "INFO", true

String constraint properties

These properties control the format and length for string field types:

Property	Type	Applicable types	Description	Example
`pattern`	string	string	A regular expression to validate the field value format.	`^[a-zA-Z][a-zA-Z0-9-]*$`
`max_length`	integer	string	The maximum length of the string.	128, 255
`example`	any	All types	An example of a field value.	"web-server-01"

Analysis properties

These properties control the behavior of a field in queries and analysis:

Property	Type	Default value	Description	Scenarios
`analysable`	boolean	false	Specifies whether the field can be used as a column for Group By aggregation analysis.	Dimension fields, such as region or service name.
`filterable`	boolean	false	Specifies whether the field supports indexed filter queries.	Fields commonly used in query conditions.
`orderable`	boolean	false	Specifies whether the field can be sorted.	Numeric or time fields that require sorting.
`default_order`	enum	asc	The default sort direction: `asc` (ascending) or `desc` (descending).	Time fields usually use desc.

Display formatting

Display format properties

These properties control how a field is displayed in the user interface:

Property	Type	Default value	Description
`unit`	string	-	The display unit for the field. This is for display only and does not perform format conversion.
`data_format`	enum	KMB	The formatting method for the field. See the Data formatting options table.

Best practices for using units:

Set data_format first. It meets the requirements of most observability scenarios.
If data_format does not meet your requirements, set data_format to the general KMB format and set unit to a specific type.
For example, for a temperature field: data_format: "KMB", unit: "°C".

Data formatting options

The data_format property supports the following options:

Numeric formats

Format	Description	Example effect
`KMB`	Formats numbers into thousands (K), millions (M), and billions (B).	1,234 → 1.23K

Storage formats

Format	Description	Example effect
`byte`	Formats into bytes.	1024 → 1 KB
`bit`	Formats into bits.	8192 → 8 Kb

Rate formats

Format	Description	Example effect
`byte_ies_sec`	Formats into bytes per second.	1048576 → 1 MB/s
`bit_ies_sec`	Formats into bits per second.	1000000 → 1 Mbps
`iops`	Formats into I/O operations per second.	1000 → 1K io/s
`reqps`	Formats into requests per second.	5000 → 5K req/s

Percentage formats

Format	Description	Value range	Example effect
`percent`	Formats as a percentage.	1 to 100	85 → 85%
`percent_decimal`	Formats a decimal as a percentage.	0 to 1	0.85 → 85%

Time formats

Format	Description	Example effect
`localtime`	Local time format.	1705310400 → 2024-01-15 18:00:00
`localtimems`	Converts milliseconds to local time.	1705310400000 → 2024-01-15 18:00:00.000
`localtimeus`	Converts microseconds to local time.	1705310400000000 → 2024-01-15 18:00:00.000000
`localtimens`	Converts nanoseconds to local time.	1705310400000000000 → 2024-01-15 18:00:00.000000000
`UTC±n`	Specific time zone.	For example, UTC+8 or UTC-5.

Duration formats

Format	Description	Example effect
`dtdhms`	Days, hours, minutes, and seconds format.	90061 → 1d 01:01:01
`dthms`	Hours, minutes, and seconds format.	3661 → 01:01:01
`d` / `h` / `m` / `s`	Formats into days, hours, minutes, or seconds.	3600 → 1h
`ms` / `us` / `ns`	Formats into milliseconds, microseconds, or nanoseconds.	1500 → 1.5s

Value mapping and extension properties

Value mapping property

Provides a mapping from enumeration values to display content:

Property	Type	Description
`value_mapping`	map	The mapping configuration for enumeration values. The key is the original value and the value is the mapping object.

A value mapping object contains the following properties:

name: The identifier for the mapped name.
display_name: The multilingual display name.
description: The multilingual description.
short_description: The multilingual short description.

Extension properties

Used to attach metadata and custom configurations:

Property	Type	Description	Example
`icon`	string	The URL of the field's icon (experimental feature).	`https://example.com/icon.png`
`uri`	string	The unique identifier URI for the field (experimental feature).	`/metrics/cpu_usage`
`tags`	map	Tag information for the field, used for classification and retrieval.	`{"category": "performance"}`
`properties`	map	Additional property information for the field.	`{"alert_threshold": "80"}`

Typical configuration examples

Metric fields

CPU utilization field

Property	Value	Description
name	`cpu_usage_percent`	Field identifier
display_name	`"CPU Usage"`	Multilingual display name
type	`float`	Floating-point number type
min_value	`0.0`	Minimum value
max_value	`100.0`	Maximum value
data_format	`percent`	Percentage format
unit	``	No additional unit configuration is needed.
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.
orderable	`true`	Supports sorting.

Memory usage field

Property	Value	Description
name	`memory_used_bytes`	Field identifier
display_name	`"Memory Used"`	Multilingual display name
type	`integer`	Integer type
min_value	`0`	Minimum value
data_format	`byte`	Byte format
unit	``	No additional unit configuration is needed.
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.

Log fields

Log level field

Property	Value	Description
name	`log_level`	Field identifier
display_name	`"Log Level"`	Multilingual display name
type	`string`	String type
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.
value_mapping	See the value mapping example.	Enumeration value mapping.

Example of log level value mapping:

{
  "DEBUG": {
    "name": "debug",
    "display_name": "Debug"
  },
  "INFO": {
    "name": "info", 
    "display_name": "Info"
  },
  "ERROR": {
    "name": "error",
    "display_name": "Error"
  }
}

HTTP status code field

Property	Value	Description
name	`http_status_code`	Field identifier
type	`integer`	Integer type
min_value	`100`	Minimum HTTP status code.
max_value	`599`	Maximum HTTP status code.
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.

Tracing Analysis fields

Trace ID field

Property	Value	Description
name	`trace_id`	Field identifier
type	`string`	String type
pattern	`^[a-f0-9]{32}$`	32-character hexadecimal format.
max_length	`32`	Fixed length of 32 characters.
filterable	`true`	Supports filter queries.
analysable	`false`	High cardinality. Aggregation is not recommended.

Operation duration field

Property	Value	Description
name	`duration_ms`	Field identifier
type	`float`	Floating-point number type
min_value	`0.0`	Minimum value
data_format	`ms`	Millisecond format
unit		No additional unit configuration is needed.
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.
orderable	`true`	Supports sorting.
default_order	`desc`	Default sort order is descending.

Entity identifier fields

Hostname field

Property	Value	Description
name	`hostname`	Field identifier
type	`string`	String type
max_length	`128`	Maximum length
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.

Pod name field

Property	Value	Description
name	`pod_name`	Field identifier
type	`string`	String type
pattern	`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`	Kubernetes naming convention.
max_length	`63`	Kubernetes maximum length limit.
filterable	`true`	Supports filter queries.
analysable	`true`	Supports aggregation analysis.