From cb016029d0ee6db00685193b9b434267286e91ce Mon Sep 17 00:00:00 2001 From: qiansheng91 Date: Mon, 15 Jun 2026 14:29:04 +0800 Subject: [PATCH] feat(docs): generated bilingual Schema reference (L0 Core) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a Schema reference to the docs site, organized per the UModel standard's L0 Core abstractions — EntitySet / DataSet / Link / Storage — with shared building blocks (metadata, schema, telemetry_data, field_spec, metric, link) documented once and referenced from each schema. Generated from the source schemas (schemas/core + schemas/includes) by tools/docs/gen_schema_reference.py so the reference cannot drift. Per-schema pages show the standard envelope note, inheritance links, and a depth-limited bilingual spec table; internal-only reference links are stripped. - tools/docs/gen_schema_reference.py: generator (+ --check drift mode) - docs/{en,zh}/reference/schema/**: 25 generated pages per locale - docs/.vitepress/config/schema-sidebar.json + en.ts/zh.ts: sidebar wiring - Makefile: `make docs-schema` regenerates; docs-schema-check added to `make ci` --- Makefile | 10 +- docs/.vitepress/config/en.ts | 9 +- docs/.vitepress/config/schema-sidebar.json | 246 ++++++++++ docs/.vitepress/config/zh.ts | 9 +- .../schema/core/dataset/entity-source.md | 14 + .../schema/core/dataset/event-set.md | 18 + .../reference/schema/core/dataset/explorer.md | 13 + .../reference/schema/core/dataset/log-set.md | 13 + .../schema/core/dataset/metric-set.md | 20 + .../schema/core/dataset/profile-set.md | 15 + .../schema/core/dataset/runbook-set.md | 18 + .../schema/core/dataset/trace-set.md | 19 + docs/en/reference/schema/core/entity-set.md | 20 + .../reference/schema/core/link/data-link.md | 17 + .../schema/core/link/entity-set-link.md | 18 + .../schema/core/link/entity-source-link.md | 22 + .../schema/core/link/explorer-link.md | 15 + .../schema/core/link/runbook-link.md | 16 + .../schema/core/link/storage-link.md | 15 + .../schema/core/storage/aliyun-prometheus.md | 16 + .../schema/core/storage/elasticsearch.md | 26 ++ .../schema/core/storage/external-storage.md | 16 + .../en/reference/schema/core/storage/mysql.md | 26 ++ .../schema/core/storage/prometheus.md | 25 ++ .../schema/core/storage/sls-entitystore.md | 15 + .../schema/core/storage/sls-logstore.md | 21 + .../schema/core/storage/sls-metricstore.md | 15 + docs/en/reference/schema/index.md | 55 +++ docs/en/reference/schema/shared-types.md | 163 +++++++ .../schema/core/dataset/entity-source.md | 14 + .../schema/core/dataset/event-set.md | 18 + .../reference/schema/core/dataset/explorer.md | 13 + .../reference/schema/core/dataset/log-set.md | 13 + .../schema/core/dataset/metric-set.md | 20 + .../schema/core/dataset/profile-set.md | 15 + .../schema/core/dataset/runbook-set.md | 18 + .../schema/core/dataset/trace-set.md | 19 + docs/zh/reference/schema/core/entity-set.md | 20 + .../reference/schema/core/link/data-link.md | 17 + .../schema/core/link/entity-set-link.md | 18 + .../schema/core/link/entity-source-link.md | 22 + .../schema/core/link/explorer-link.md | 15 + .../schema/core/link/runbook-link.md | 16 + .../schema/core/link/storage-link.md | 15 + .../schema/core/storage/aliyun-prometheus.md | 16 + .../schema/core/storage/elasticsearch.md | 26 ++ .../schema/core/storage/external-storage.md | 16 + .../zh/reference/schema/core/storage/mysql.md | 26 ++ .../schema/core/storage/prometheus.md | 25 ++ .../schema/core/storage/sls-entitystore.md | 15 + .../schema/core/storage/sls-logstore.md | 21 + .../schema/core/storage/sls-metricstore.md | 15 + docs/zh/reference/schema/index.md | 55 +++ docs/zh/reference/schema/shared-types.md | 163 +++++++ tools/docs/gen_schema_reference.py | 424 ++++++++++++++++++ 55 files changed, 1956 insertions(+), 4 deletions(-) create mode 100644 docs/.vitepress/config/schema-sidebar.json create mode 100644 docs/en/reference/schema/core/dataset/entity-source.md create mode 100644 docs/en/reference/schema/core/dataset/event-set.md create mode 100644 docs/en/reference/schema/core/dataset/explorer.md create mode 100644 docs/en/reference/schema/core/dataset/log-set.md create mode 100644 docs/en/reference/schema/core/dataset/metric-set.md create mode 100644 docs/en/reference/schema/core/dataset/profile-set.md create mode 100644 docs/en/reference/schema/core/dataset/runbook-set.md create mode 100644 docs/en/reference/schema/core/dataset/trace-set.md create mode 100644 docs/en/reference/schema/core/entity-set.md create mode 100644 docs/en/reference/schema/core/link/data-link.md create mode 100644 docs/en/reference/schema/core/link/entity-set-link.md create mode 100644 docs/en/reference/schema/core/link/entity-source-link.md create mode 100644 docs/en/reference/schema/core/link/explorer-link.md create mode 100644 docs/en/reference/schema/core/link/runbook-link.md create mode 100644 docs/en/reference/schema/core/link/storage-link.md create mode 100644 docs/en/reference/schema/core/storage/aliyun-prometheus.md create mode 100644 docs/en/reference/schema/core/storage/elasticsearch.md create mode 100644 docs/en/reference/schema/core/storage/external-storage.md create mode 100644 docs/en/reference/schema/core/storage/mysql.md create mode 100644 docs/en/reference/schema/core/storage/prometheus.md create mode 100644 docs/en/reference/schema/core/storage/sls-entitystore.md create mode 100644 docs/en/reference/schema/core/storage/sls-logstore.md create mode 100644 docs/en/reference/schema/core/storage/sls-metricstore.md create mode 100644 docs/en/reference/schema/index.md create mode 100644 docs/en/reference/schema/shared-types.md create mode 100644 docs/zh/reference/schema/core/dataset/entity-source.md create mode 100644 docs/zh/reference/schema/core/dataset/event-set.md create mode 100644 docs/zh/reference/schema/core/dataset/explorer.md create mode 100644 docs/zh/reference/schema/core/dataset/log-set.md create mode 100644 docs/zh/reference/schema/core/dataset/metric-set.md create mode 100644 docs/zh/reference/schema/core/dataset/profile-set.md create mode 100644 docs/zh/reference/schema/core/dataset/runbook-set.md create mode 100644 docs/zh/reference/schema/core/dataset/trace-set.md create mode 100644 docs/zh/reference/schema/core/entity-set.md create mode 100644 docs/zh/reference/schema/core/link/data-link.md create mode 100644 docs/zh/reference/schema/core/link/entity-set-link.md create mode 100644 docs/zh/reference/schema/core/link/entity-source-link.md create mode 100644 docs/zh/reference/schema/core/link/explorer-link.md create mode 100644 docs/zh/reference/schema/core/link/runbook-link.md create mode 100644 docs/zh/reference/schema/core/link/storage-link.md create mode 100644 docs/zh/reference/schema/core/storage/aliyun-prometheus.md create mode 100644 docs/zh/reference/schema/core/storage/elasticsearch.md create mode 100644 docs/zh/reference/schema/core/storage/external-storage.md create mode 100644 docs/zh/reference/schema/core/storage/mysql.md create mode 100644 docs/zh/reference/schema/core/storage/prometheus.md create mode 100644 docs/zh/reference/schema/core/storage/sls-entitystore.md create mode 100644 docs/zh/reference/schema/core/storage/sls-logstore.md create mode 100644 docs/zh/reference/schema/core/storage/sls-metricstore.md create mode 100644 docs/zh/reference/schema/index.md create mode 100644 docs/zh/reference/schema/shared-types.md create mode 100644 tools/docs/gen_schema_reference.py diff --git a/Makefile b/Makefile index d9100c6..8a0a09c 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help check-env install-env setup setup-ui expand doc example-validate check-manifest +.PHONY: help check-env install-env setup setup-ui expand doc docs-schema docs-schema-check example-validate check-manifest .PHONY: build build-service build-cli install-cli build-ui build-sdk-go dev quickstart dev-api dev-web deploy serve-ui status stop-all stop-dev stop-deploy test test-service test-ui test-ui-e2e test-capability test-quickstart-health test-ladybug verify verify-go verify-python verify-java guard ci clean VENV_PYTHON := .venv/bin/python @@ -186,6 +186,12 @@ schemas-embed-check: doc: @bash ./tools/converters/batch_convert_html.sh +docs-schema: + @$(PYTHON) ./tools/docs/gen_schema_reference.py + +docs-schema-check: + @$(PYTHON) ./tools/docs/gen_schema_reference.py --check + example-validate: @$(PYTHON) ./tools/validators/umodel_validator.py --batch examples @@ -206,7 +212,7 @@ test: guard test-service verify check-manifest: @$(PYTHON) ./tools/verify/check_manifest.py -ci: guard schemas-embed-check build-service test-service test-capability test-quickstart-health verify check-manifest example-validate +ci: guard schemas-embed-check build-service test-service test-capability test-quickstart-health verify check-manifest example-validate docs-schema-check @echo "Local CI passed." check-env: diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts index a108b70..7f1917a 100644 --- a/docs/.vitepress/config/en.ts +++ b/docs/.vitepress/config/en.ts @@ -1,4 +1,5 @@ import type { LocaleSpecificConfig, DefaultTheme } from 'vitepress' +import schemaSidebar from './schema-sidebar.json' const nav: DefaultTheme.NavItem[] = [ { text: 'Guide', link: '/en/getting-started/quickstart', activeMatch: '/en/(getting-started|concepts|guides|architecture)/' }, @@ -67,6 +68,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [ items: [ { text: 'CLI', link: '/en/reference/cli' }, { text: 'MCP', link: '/en/reference/mcp' }, + { text: 'Schema', link: '/en/reference/schema/' }, { text: 'Web UI API Map', link: '/en/ui-api' }, { text: 'UI Architecture', link: '/en/ui-architecture' }, { text: 'SDK Specification', link: '/en/umodel-sdk-specification' }, @@ -81,13 +83,18 @@ const sidebar: DefaultTheme.SidebarItem[] = [ }, ] +const schemaNav: DefaultTheme.SidebarItem[] = [ + { text: 'Schema Reference', link: '/en/reference/schema/' }, + ...(schemaSidebar.en as DefaultTheme.SidebarItem[]), +] + export const en: LocaleSpecificConfig & { label: string; link?: string } = { label: 'English', lang: 'en-US', link: '/en/', themeConfig: { nav, - sidebar: { '/en/': sidebar }, + sidebar: { '/en/reference/schema/': schemaNav, '/en/': sidebar }, outline: { level: [2, 3], label: 'On this page' }, docFooter: { prev: 'Previous', next: 'Next' }, editLink: { diff --git a/docs/.vitepress/config/schema-sidebar.json b/docs/.vitepress/config/schema-sidebar.json new file mode 100644 index 0000000..1d89219 --- /dev/null +++ b/docs/.vitepress/config/schema-sidebar.json @@ -0,0 +1,246 @@ +{ + "en": [ + { + "text": "EntitySet", + "collapsed": false, + "items": [ + { + "text": "entity_set", + "link": "/en/reference/schema/core/entity-set" + } + ] + }, + { + "text": "DataSet", + "collapsed": false, + "items": [ + { + "text": "entity_source", + "link": "/en/reference/schema/core/dataset/entity-source" + }, + { + "text": "event_set", + "link": "/en/reference/schema/core/dataset/event-set" + }, + { + "text": "explorer", + "link": "/en/reference/schema/core/dataset/explorer" + }, + { + "text": "log_set", + "link": "/en/reference/schema/core/dataset/log-set" + }, + { + "text": "metric_set", + "link": "/en/reference/schema/core/dataset/metric-set" + }, + { + "text": "profile_set", + "link": "/en/reference/schema/core/dataset/profile-set" + }, + { + "text": "runbook_set", + "link": "/en/reference/schema/core/dataset/runbook-set" + }, + { + "text": "trace_set", + "link": "/en/reference/schema/core/dataset/trace-set" + } + ] + }, + { + "text": "Link", + "collapsed": false, + "items": [ + { + "text": "data_link", + "link": "/en/reference/schema/core/link/data-link" + }, + { + "text": "entity_set_link", + "link": "/en/reference/schema/core/link/entity-set-link" + }, + { + "text": "entity_source_link", + "link": "/en/reference/schema/core/link/entity-source-link" + }, + { + "text": "explorer_link", + "link": "/en/reference/schema/core/link/explorer-link" + }, + { + "text": "runbook_link", + "link": "/en/reference/schema/core/link/runbook-link" + }, + { + "text": "storage_link", + "link": "/en/reference/schema/core/link/storage-link" + } + ] + }, + { + "text": "Storage", + "collapsed": false, + "items": [ + { + "text": "aliyun_prometheus", + "link": "/en/reference/schema/core/storage/aliyun-prometheus" + }, + { + "text": "elasticsearch", + "link": "/en/reference/schema/core/storage/elasticsearch" + }, + { + "text": "external_storage", + "link": "/en/reference/schema/core/storage/external-storage" + }, + { + "text": "mysql", + "link": "/en/reference/schema/core/storage/mysql" + }, + { + "text": "prometheus", + "link": "/en/reference/schema/core/storage/prometheus" + }, + { + "text": "sls_entitystore", + "link": "/en/reference/schema/core/storage/sls-entitystore" + }, + { + "text": "sls_logstore", + "link": "/en/reference/schema/core/storage/sls-logstore" + }, + { + "text": "sls_metricstore", + "link": "/en/reference/schema/core/storage/sls-metricstore" + } + ] + }, + { + "text": "Shared types", + "link": "/en/reference/schema/shared-types" + } + ], + "zh": [ + { + "text": "EntitySet（实体集）", + "collapsed": false, + "items": [ + { + "text": "entity_set", + "link": "/zh/reference/schema/core/entity-set" + } + ] + }, + { + "text": "DataSet（数据集）", + "collapsed": false, + "items": [ + { + "text": "entity_source", + "link": "/zh/reference/schema/core/dataset/entity-source" + }, + { + "text": "event_set", + "link": "/zh/reference/schema/core/dataset/event-set" + }, + { + "text": "explorer", + "link": "/zh/reference/schema/core/dataset/explorer" + }, + { + "text": "log_set", + "link": "/zh/reference/schema/core/dataset/log-set" + }, + { + "text": "metric_set", + "link": "/zh/reference/schema/core/dataset/metric-set" + }, + { + "text": "profile_set", + "link": "/zh/reference/schema/core/dataset/profile-set" + }, + { + "text": "runbook_set", + "link": "/zh/reference/schema/core/dataset/runbook-set" + }, + { + "text": "trace_set", + "link": "/zh/reference/schema/core/dataset/trace-set" + } + ] + }, + { + "text": "Link（链接）", + "collapsed": false, + "items": [ + { + "text": "data_link", + "link": "/zh/reference/schema/core/link/data-link" + }, + { + "text": "entity_set_link", + "link": "/zh/reference/schema/core/link/entity-set-link" + }, + { + "text": "entity_source_link", + "link": "/zh/reference/schema/core/link/entity-source-link" + }, + { + "text": "explorer_link", + "link": "/zh/reference/schema/core/link/explorer-link" + }, + { + "text": "runbook_link", + "link": "/zh/reference/schema/core/link/runbook-link" + }, + { + "text": "storage_link", + "link": "/zh/reference/schema/core/link/storage-link" + } + ] + }, + { + "text": "Storage（存储）", + "collapsed": false, + "items": [ + { + "text": "aliyun_prometheus", + "link": "/zh/reference/schema/core/storage/aliyun-prometheus" + }, + { + "text": "elasticsearch", + "link": "/zh/reference/schema/core/storage/elasticsearch" + }, + { + "text": "external_storage", + "link": "/zh/reference/schema/core/storage/external-storage" + }, + { + "text": "mysql", + "link": "/zh/reference/schema/core/storage/mysql" + }, + { + "text": "prometheus", + "link": "/zh/reference/schema/core/storage/prometheus" + }, + { + "text": "sls_entitystore", + "link": "/zh/reference/schema/core/storage/sls-entitystore" + }, + { + "text": "sls_logstore", + "link": "/zh/reference/schema/core/storage/sls-logstore" + }, + { + "text": "sls_metricstore", + "link": "/zh/reference/schema/core/storage/sls-metricstore" + } + ] + }, + { + "text": "共享类型", + "link": "/zh/reference/schema/shared-types" + } + ] +} diff --git a/docs/.vitepress/config/zh.ts b/docs/.vitepress/config/zh.ts index ff6fce8..7fd1284 100644 --- a/docs/.vitepress/config/zh.ts +++ b/docs/.vitepress/config/zh.ts @@ -1,4 +1,5 @@ import type { LocaleSpecificConfig, DefaultTheme } from 'vitepress' +import schemaSidebar from './schema-sidebar.json' const nav: DefaultTheme.NavItem[] = [ { text: '指南', link: '/zh/getting-started/quickstart', activeMatch: '/zh/(getting-started|concepts|guides|architecture)/' }, @@ -67,6 +68,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [ items: [ { text: 'CLI', link: '/zh/reference/cli' }, { text: 'MCP', link: '/zh/reference/mcp' }, + { text: 'Schema', link: '/zh/reference/schema/' }, { text: 'Web UI API 映射', link: '/zh/ui-api' }, { text: 'UI 架构', link: '/zh/ui-architecture' }, { text: 'SDK 规范', link: '/zh/umodel-sdk-specification' }, @@ -81,13 +83,18 @@ const sidebar: DefaultTheme.SidebarItem[] = [ }, ] +const schemaNav: DefaultTheme.SidebarItem[] = [ + { text: 'Schema 参考', link: '/zh/reference/schema/' }, + ...(schemaSidebar.zh as DefaultTheme.SidebarItem[]), +] + export const zh: LocaleSpecificConfig & { label: string; link?: string } = { label: '简体中文', lang: 'zh-CN', link: '/zh/', themeConfig: { nav, - sidebar: { '/zh/': sidebar }, + sidebar: { '/zh/reference/schema/': schemaNav, '/zh/': sidebar }, outline: { level: [2, 3], label: '本页目录' }, docFooter: { prev: '上一页', next: '下一页' }, editLink: { diff --git a/docs/en/reference/schema/core/dataset/entity-source.md b/docs/en/reference/schema/core/dataset/entity-source.md new file mode 100644 index 0000000..f1fafc5 --- /dev/null +++ b/docs/en/reference/schema/core/dataset/entity-source.md @@ -0,0 +1,14 @@ +# entity_source + +EntitySource defines the import job for a specific entity and its source storage (e.g. SLS LogStore / MetricStore). + +**Kind**: `entity_source` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `constructor` | map<string, any> | yes | | Constructor/scheduling configuration of the import job, supports flexible key-value pairs. | +| `storages` | array<map> | yes | | List of source storage configurations, each element is a map supporting flexible fields. | diff --git a/docs/en/reference/schema/core/dataset/event-set.md b/docs/en/reference/schema/core/dataset/event-set.md new file mode 100644 index 0000000..c97270c --- /dev/null +++ b/docs/en/reference/schema/core/dataset/event-set.md @@ -0,0 +1,18 @@ +# event_set + +EventSet is a collection of related events that share certain common attributes or characteristics. + +**Kind**: `event_set` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `entity_fields` | object | | | Entity fields, used to identify the ID, domain and type of entity | +| `entity_fields.entity_id` | `string` | | `__entity_id__` | Entity ID field, used to identify the ID of entity | +| `entity_fields.domain` | `string` | | `__domain__` | Domain field which entity belongs to | +| `entity_fields.entity_type` | `string` | | `__entity_type__` | Entity type field, used to identify the type of entity | diff --git a/docs/en/reference/schema/core/dataset/explorer.md b/docs/en/reference/schema/core/dataset/explorer.md new file mode 100644 index 0000000..bf7e69e --- /dev/null +++ b/docs/en/reference/schema/core/dataset/explorer.md @@ -0,0 +1,13 @@ +# explorer + +**Kind**: `explorer` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `type` | `string` | yes | | The kind of explorer. | +| `query` | `string` | | | The default query of explorer. | +| `config` | map<string, any> | | | The config dynamic of explorer. | diff --git a/docs/en/reference/schema/core/dataset/log-set.md b/docs/en/reference/schema/core/dataset/log-set.md new file mode 100644 index 0000000..692675a --- /dev/null +++ b/docs/en/reference/schema/core/dataset/log-set.md @@ -0,0 +1,13 @@ +# log_set + +LogSet is a collection of related log entries that share certain common attributes or characteristics. + +**Kind**: `log_set` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` fields + +_This element has no additional `spec` fields beyond the inherited base._ diff --git a/docs/en/reference/schema/core/dataset/metric-set.md b/docs/en/reference/schema/core/dataset/metric-set.md new file mode 100644 index 0000000..007bdb7 --- /dev/null +++ b/docs/en/reference/schema/core/dataset/metric-set.md @@ -0,0 +1,20 @@ +# metric_set + +MetricSet is used to define metrics. A metric set is a collection of metrics with the same attributes, generally used to describe a class of metrics for a certain type of observable entity, such as CPU, memory, disk a… + +**Kind**: `metric_set` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `labels` | object | | | The list of labels for the MetricSet. It is recommended to use dynamic to automatically generate labels. Note: The labels here are the general labels of the MetricSet. It is generally recommended that the MetricSet on… | +| `labels.keys` | array<[field_spec](../../shared-types#field_spec)> | | | The list of labels. The value format is reference to the field definition. | +| `labels.dynamic` | `boolean` | | `false` | Whether the key is dynamic. It is generally recommended to set it to true. | +| `labels.filter` | `string` | | | The filter of the label. When dynamic is true, it will be filtered according to this filter. | +| `label_keys` | array<[field_spec](../../shared-types#field_spec)> | | | The label keys of the MetricSet. It is currently deprecated and will be deleted. Please use the labels field instead. | +| `metrics` | array<[metric](../../shared-types#metric)> | | | The detailed list of metrics. | +| `query_type` | enum: `prom`, `spl`, `cms` | | | The query type of the metric. The value can be prom, spl or cms. | +| `needs_processing` | `boolean` | | `false` | Whether the MetricSet needs to be processed again. That is, whether the metrics in the MetricSet need to be processed again to be used. For example, the counter/summary/histogram metrics in Prometheus need to be proce… | diff --git a/docs/en/reference/schema/core/dataset/profile-set.md b/docs/en/reference/schema/core/dataset/profile-set.md new file mode 100644 index 0000000..88cfb55 --- /dev/null +++ b/docs/en/reference/schema/core/dataset/profile-set.md @@ -0,0 +1,15 @@ +# profile_set + +ProfileSet is used to define Profile data sets. A Profile data set is a collection of Profile data with the same attributes, generally used to describe a class of Profile data for a certain type of observable entity,… + +**Kind**: `profile_set` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `protocol` | `string` | | `pprof` | The profiling protocol used. Specifies the format and standard for profiling data. | diff --git a/docs/en/reference/schema/core/dataset/runbook-set.md b/docs/en/reference/schema/core/dataset/runbook-set.md new file mode 100644 index 0000000..6d00036 --- /dev/null +++ b/docs/en/reference/schema/core/dataset/runbook-set.md @@ -0,0 +1,18 @@ +# runbook_set + +RunbookSet is used to define a collection of operational runbooks for entities and data, including analysis tools, operation guides and best practices. + +**Kind**: `runbook_set` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `observations` | array<[observation](../../shared-types#observation)> | | | List of observation configurations | +| `actions` | array<object> | | | List of action configurations | +| `toolkits` | array<object> | | | List of toolkit configurations, each toolkit contains shared config and a set of tools | +| `knowledge` | array<object> | | | List of knowledge base configurations | +| `automations` | array<object> | | | List of automation configurations | +| `skills` | array<object> | | | List of skill configurations following Agent Skills specification | diff --git a/docs/en/reference/schema/core/dataset/trace-set.md b/docs/en/reference/schema/core/dataset/trace-set.md new file mode 100644 index 0000000..a4d98de --- /dev/null +++ b/docs/en/reference/schema/core/dataset/trace-set.md @@ -0,0 +1,19 @@ +# trace_set + +TraceSet is a collection of related trace records that share certain common attributes or characteristics. Each TraceSet must include the following fields: trace_id_field, span_id_field, parent_span_id_field, and prot… + +**Kind**: `trace_set` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `attribute_fields` | array<[field_spec](../../shared-types#field_spec)> | | | The attributes of the TraceSet. The value format is a list of field specifications that define the trace attributes. It is currently not used. | +| `trace_id_field` | `string` | yes | `traceId` | The field name of trace_id of the TraceSet. | +| `span_id_field` | `string` | yes | `spanId` | The field name of span_id of the TraceSet. | +| `parent_span_id_field` | `string` | | `parentSpanId` | The field name of parent_span_id of the TraceSet. | +| `protocol` | `string` | | `opentelemetry` | The tracing protocol used. Specifies the format and standard for trace data. | diff --git a/docs/en/reference/schema/core/entity-set.md b/docs/en/reference/schema/core/entity-set.md new file mode 100644 index 0000000..8b17fa7 --- /dev/null +++ b/docs/en/reference/schema/core/entity-set.md @@ -0,0 +1,20 @@ +# entity_set + +EntitySet is used to define the entity, which is a collection of entities that share the same properties. In the modeling scenario, entities can be defined according to needs, such as in the IT observable scenario, it… + +**Kind**: `entity_set` + +> Every element shares the standard envelope `kind` · [metadata](../shared-types#metadata) · [schema](../shared-types#schema). + +**Inherits**: [telemetry_data](../shared-types#telemetry_data) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `first_observed_time_field` | `string` | | | The field containing the first observed time of the Entity. | +| `last_observed_time_field` | `string` | | | The field containing the last observed time of the Entity. | +| `primary_key_fields` | array<string> | | | The primary key fields of the Entity. The value format is a list of field names that uniquely identify an entity. | +| `id_generator` | `string` | | | Entity 的 ID 生成器。表示该 EntitySet 的ID如何通过PrimaryKeyFields 生成。该字段类型为 string，需要符合 SPL 的表达式语法，执行返回为 string。如果为空，则使用默认的生成方式： lower(to_hex(md5(cast(join(primaryKeys, '#$#') as varbinary)))) ，即将 PrimaryKeyFields 拼接成字符串，然后进行 MD5… | +| `keep_alive_seconds` | `number` | | `3600` | The duration to keep active is, after the last observed time plus the keep-alive seconds, the Entity will be considered as disappeared. Default is 3600 seconds (1 hour). | +| `dynamic` | `bool` | | `false` | Whether the Entity is dynamically generated, default is false. If true, the Entity is a dynamic entity, which will be bound to a Storage, and the content of the Entity will be obtained from the Storage, rather than be… | diff --git a/docs/en/reference/schema/core/link/data-link.md b/docs/en/reference/schema/core/link/data-link.md new file mode 100644 index 0000000..9a9fb08 --- /dev/null +++ b/docs/en/reference/schema/core/link/data-link.md @@ -0,0 +1,17 @@ +# data_link + +DataLink is used to define the relationship between EntitySet/Link and DataSet, and also describe the relationship between two DataSet. DataLink must contain the source DataSet, destination DataSet and link type. + +**Kind**: `data_link` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [link](../../shared-types#link) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `fields_mapping` | map<string, string> | | | The mapping relationship between the fields of the source DataSet and the destination DataSet. | +| `data_link_type` | enum: `produce`, `related_to` | | | The type of the DataLink. The value cannot be empty. The value must be one of the following: produce, related_to. | +| `data_filter` | `string` | | | The data filter, used to filter data. For example, there is a general MetricSet that contains various types of metrics, and the source entity may be DBClient, then the metrics of all db types can be filtered out throu… | diff --git a/docs/en/reference/schema/core/link/entity-set-link.md b/docs/en/reference/schema/core/link/entity-set-link.md new file mode 100644 index 0000000..7c4ed67 --- /dev/null +++ b/docs/en/reference/schema/core/link/entity-set-link.md @@ -0,0 +1,18 @@ +# entity_set_link + +EntitySetLink is used to define the relationship between two EntitySet. EntitySetLink must contain the source EntitySet, destination EntitySet and link type. + +**Kind**: `entity_set_link` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [link](../../shared-types#link) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `fields_mapping` | map<string, string> | | | The destination EntitySet fields mapping of the EntitySetLink. | +| `constructor` | object | | | The constructor configuration for EntitySetLink. If this field is configured, the background will automatically create and maintain tasks to automatically generate EntitySetLink. | +| `entity_link_type` | `string` | yes | | The type of the EntityLinkSet. The value cannot be empty. The recommended values are: - calls - runs - instance_of - parent_of - contains - balances - can_access - clustered_by - manages - monitors - sends_to - affect… | +| `dynamic` | `bool` | | `false` | Whether the EntitySetLink is dynamically generated, default is false. If true, the EntitySetLink is a dynamic Link, which will be bound to a Storage, and the content of the Link will be obtained from the Storage, rath… | diff --git a/docs/en/reference/schema/core/link/entity-source-link.md b/docs/en/reference/schema/core/link/entity-source-link.md new file mode 100644 index 0000000..139c6af --- /dev/null +++ b/docs/en/reference/schema/core/link/entity-source-link.md @@ -0,0 +1,22 @@ +# entity_source_link + +EntitySourceLink is used to define the relationship between EntitySource and EntitySet. + +**Kind**: `entity_source_link` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [link](../../shared-types#link) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `src` | object | yes | | The identifier of the source Set. The value cannot be empty. | +| `src.domain` | `string` | yes | | The domain of the source Set. | +| `src.kind` | enum: `entity_source` | yes | | The type of the source Set. The value cannot be empty. | +| `src.name` | `string` | yes | | The name of the source Set. The value cannot be empty. | +| `dest` | object | yes | | The identifier of the destination Set. The value cannot be empty. | +| `dest.domain` | `string` | yes | | The domain of the destination Set. | +| `dest.kind` | enum: `entity_set` | yes | | The type of the destination Set. The value cannot be empty. | +| `dest.name` | `string` | yes | | The name of the destination Set. The value cannot be empty. | diff --git a/docs/en/reference/schema/core/link/explorer-link.md b/docs/en/reference/schema/core/link/explorer-link.md new file mode 100644 index 0000000..6eb9be9 --- /dev/null +++ b/docs/en/reference/schema/core/link/explorer-link.md @@ -0,0 +1,15 @@ +# explorer_link + +**Kind**: `explorer_link` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [link](../../shared-types#link) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `token_mapping` | map<string, string> | | | The mapping relationship between the fields of the source dataset set and the destination explorer | +| `token_replace` | map<string, string> | | | The replace relationship between the fields of the source dataset set and the destination explorer | +| `config` | map<string, string> | | | The config dynamic of explorer. | diff --git a/docs/en/reference/schema/core/link/runbook-link.md b/docs/en/reference/schema/core/link/runbook-link.md new file mode 100644 index 0000000..9fe4c3f --- /dev/null +++ b/docs/en/reference/schema/core/link/runbook-link.md @@ -0,0 +1,16 @@ +# runbook_link + +RunbookLink is used to define the relationship between entity sets and runbook sets. + +**Kind**: `runbook_link` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [link](../../shared-types#link) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `token_replace` | map<string, string> | | | The mapping relationship of context variables, used to provide dynamic context variables when executing the Runbook. | +| `fields_mapping` | map<string, string> | | | The field mapping from source dataset fields to destination Runbook fields, used to pass field values from the dataset to Runbook input parameters. | diff --git a/docs/en/reference/schema/core/link/storage-link.md b/docs/en/reference/schema/core/link/storage-link.md new file mode 100644 index 0000000..bd8bc06 --- /dev/null +++ b/docs/en/reference/schema/core/link/storage-link.md @@ -0,0 +1,15 @@ +# storage_link + +StorageLink is used to define the relationship between EntitySet/DataSet and Storage. StorageLink must contain the source Set, destination Storage. + +**Kind**: `storage_link` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**Inherits**: [link](../../shared-types#link) + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `fields_mapping` | map<string, string> | | | Used to define simple field mapping relationships, such as the mapping relationship between the name of Field in DataSet and the name of Field in Storage. | diff --git a/docs/en/reference/schema/core/storage/aliyun-prometheus.md b/docs/en/reference/schema/core/storage/aliyun-prometheus.md new file mode 100644 index 0000000..43c7fba --- /dev/null +++ b/docs/en/reference/schema/core/storage/aliyun-prometheus.md @@ -0,0 +1,16 @@ +# aliyun_prometheus + +The aliyun_prometheus is used to define the aliyun prometheus instance. + +**Kind**: `aliyun_prometheus` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `region` | `string` | yes | | The region of the Aliyun Prometheus instance. | +| `instance_id` | `string` | yes | | The instance ID of Aliyun Prometheus. | +| `sls_project` | `string` | | | The SLS project name where the Aliyun Prometheus data is stored. | +| `sls_metricstore` | `string` | | | The SLS metricstore name where the Aliyun Prometheus data is stored. | diff --git a/docs/en/reference/schema/core/storage/elasticsearch.md b/docs/en/reference/schema/core/storage/elasticsearch.md new file mode 100644 index 0000000..a281105 --- /dev/null +++ b/docs/en/reference/schema/core/storage/elasticsearch.md @@ -0,0 +1,26 @@ +# elasticsearch + +Elasticsearch storage, used to define the Elasticsearch cluster, index, and connection metadata required for query planning. + +**Kind**: `elasticsearch` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `endpoint` | `string` | yes | | The Elasticsearch cluster endpoint, for example https://es.example.com:9200. | +| `index` | `string` | yes | | The default index name to query. It may also be an Elasticsearch-supported index wildcard expression. | +| `index_pattern` | `string` | | | Index pattern for time-rolled indices, for example logs-${yyyy.MM.dd}. When empty, query planning uses the index field. | +| `version` | `string` | | | The Elasticsearch version or version family, for example 7.x or 8.x. | +| `query_dialect` | enum: `elasticsearch_dsl`, `lucene`, `eql` | | `elasticsearch_dsl` | Query generation dialect. Elasticsearch Query DSL is used by default. | +| `time_field` | `string` | | | Time field used to push request time ranges into Elasticsearch queries. | +| `default_size` | `integer` | | `1000` | Default query size when no explicit limit is provided. | +| `max_size` | `integer` | | `10000` | Maximum query size allowed by the planner to avoid producing excessively large query plans. | +| `routing` | `string` | | | Optional Elasticsearch routing value for queries that should target a fixed routing key. | +| `credential_ref` | `string` | | | Credential reference, for example secret://es-prod-readonly. Plaintext usernames, passwords, or tokens must not be stored in UModel. | +| `tls_verify` | `boolean` | | `true` | Whether TLS certificates should be verified. Defaults to true. | +| `headers` | map<string, string> | | | Non-sensitive HTTP headers for tenant or routing context. Authentication secrets must not be stored here. | +| `properties` | map<string, string> | | | Additional non-sensitive Elasticsearch configuration, stored as key-value pairs. | +| `tags` | map<string, string> | | | Tags used to describe this Elasticsearch storage. | diff --git a/docs/en/reference/schema/core/storage/external-storage.md b/docs/en/reference/schema/core/storage/external-storage.md new file mode 100644 index 0000000..cfc5e98 --- /dev/null +++ b/docs/en/reference/schema/core/storage/external-storage.md @@ -0,0 +1,16 @@ +# external_storage + +External storage, used to store details of custom storage. + +**Kind**: `external_storage` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `type` | `string` | yes | | The type of the external storage. | +| `name` | `string` | yes | | The name of the external storage. | +| `properties` | map<string, string> | | | Details of the external storage, stored as key-value pairs. | +| `tags` | map<string, string> | | | This field is used to represent the tags of the external storage. | diff --git a/docs/en/reference/schema/core/storage/mysql.md b/docs/en/reference/schema/core/storage/mysql.md new file mode 100644 index 0000000..eb90570 --- /dev/null +++ b/docs/en/reference/schema/core/storage/mysql.md @@ -0,0 +1,26 @@ +# mysql + +MySQL storage, used to define the MySQL instance, database, table, and connection metadata required for query planning. + +**Kind**: `mysql` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `endpoint` | `string` | yes | | The MySQL instance endpoint, usually in host:port format. | +| `database` | `string` | yes | | The default database name to query. | +| `table` | `string` | | | The default table name to query. It can be overridden by the DataSet or query parameters. | +| `sql_template` | `string` | | | Optional SQL template for special query planning scenarios. The template must keep read-only semantics and should not contain INSERT, UPDATE, DELETE, DDL, or similar statements. | +| `sql_dialect` | enum: `mysql`, `ansi` | | `mysql` | SQL dialect. MySQL storage uses mysql by default. | +| `time_field` | `string` | | | Time field used to push request time ranges into SQL WHERE conditions. | +| `time_unit` | enum: `second`, `millisecond`, `microsecond`, `nanosecond`, `datetime` | | `second` | Time unit of time_field. Defaults to second. | +| `default_limit` | `integer` | | `1000` | Default SQL LIMIT when no explicit limit is provided. | +| `max_limit` | `integer` | | `10000` | Maximum SQL LIMIT allowed by the planner to avoid producing excessively large query plans. | +| `read_only` | `boolean` | | `true` | Indicates whether this storage should only plan read-only queries. Defaults to true; UModel PaaS query planning should not generate write statements. | +| `credential_ref` | `string` | | | Credential reference, for example secret://mysql-prod-readonly. Plaintext usernames, passwords, or tokens must not be stored in UModel. | +| `tls_mode` | enum: `disabled`, `preferred`, `required`, `verify_ca`, `verify_identity` | | `preferred` | MySQL TLS mode. Defaults to preferred. | +| `properties` | map<string, string> | | | Additional non-sensitive MySQL configuration, stored as key-value pairs. | +| `tags` | map<string, string> | | | Tags used to describe this MySQL storage. | diff --git a/docs/en/reference/schema/core/storage/prometheus.md b/docs/en/reference/schema/core/storage/prometheus.md new file mode 100644 index 0000000..ee96e80 --- /dev/null +++ b/docs/en/reference/schema/core/storage/prometheus.md @@ -0,0 +1,25 @@ +# prometheus + +Prometheus storage, used to define open-source Prometheus or Prometheus-compatible endpoint metadata for query planning. + +**Kind**: `prometheus` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `endpoint` | `string` | yes | | The endpoint URL of Prometheus or a Prometheus-compatible service, for example http://prometheus:9090. | +| `api_prefix` | `string` | | `/api/v1` | Prometheus HTTP API prefix. Defaults to /api/v1. | +| `default_query_type` | enum: `instant`, `range` | | `instant` | Default PromQL query type. instant means instant query and range means range query. | +| `default_step` | `string` | | | Default step for range queries, for example 60s or 1m. | +| `lookback_delta` | `string` | | | Default PromQL lookback window used by query planning, for example 5m. | +| `tenant` | `string` | | | Optional tenant identifier for multi-tenant Prometheus-compatible systems. | +| `tenant_header` | `string` | | | Tenant HTTP header name used by multi-tenant systems, for example X-Scope-OrgID. | +| `credential_ref` | `string` | | | Credential reference, for example secret://prometheus-prod-readonly. Plaintext usernames, passwords, or tokens must not be stored in UModel. | +| `tls_verify` | `boolean` | | `true` | Whether TLS certificates should be verified. Defaults to true. | +| `external_labels` | map<string, string> | | | Prometheus external labels used to enrich query-planning context or describe result origin. | +| `headers` | map<string, string> | | | Non-sensitive HTTP headers for tenant or routing context. Authentication secrets must not be stored here. | +| `properties` | map<string, string> | | | Additional non-sensitive Prometheus configuration, stored as key-value pairs. | +| `tags` | map<string, string> | | | Tags used to describe this Prometheus storage. | diff --git a/docs/en/reference/schema/core/storage/sls-entitystore.md b/docs/en/reference/schema/core/storage/sls-entitystore.md new file mode 100644 index 0000000..d0d2836 --- /dev/null +++ b/docs/en/reference/schema/core/storage/sls-entitystore.md @@ -0,0 +1,15 @@ +# sls_entitystore + +SLS EntityStore storage, usually used to store observable entities and relationship data. + +**Kind**: `sls_entitystore` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `region` | `string` | yes | | The region of the SLS EntityStore. | +| `project` | `string` | yes | | The project of the SLS EntityStore. | +| `workspace` | `string` | yes | | The workspace of the SLS EntityStore. | diff --git a/docs/en/reference/schema/core/storage/sls-logstore.md b/docs/en/reference/schema/core/storage/sls-logstore.md new file mode 100644 index 0000000..718f9ff --- /dev/null +++ b/docs/en/reference/schema/core/storage/sls-logstore.md @@ -0,0 +1,21 @@ +# sls_logstore + +SLS LogStore storage, usually used to store log data. + +**Kind**: `sls_logstore` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `region` | `string` | yes | | The region of the SLS LogStore. | +| `project` | `string` | yes | | The project of the SLS LogStore. | +| `store` | `string` | yes | | The name of the SLS LogStore. | +| `search_filter` | `string` | | `*` | The filter condition of the logstore, if the logstore contains multiple types of data, you can use this field to filter the target data. | +| `spl_filter` | `string` | | | The SPL filter condition of the logstore, compared to the search_filter field, SPL filter conditions are more flexible and support more complex filter conditions, but the performance is relatively poor. | +| `spl_view` | `string` | | | The SPL view of the logstore, usually used to dynamically generate entity lists, connections, etc. Note: This scenario requires re-generating the view each time, and the performance is very poor. | +| `spl_notebook` | `string` | | | The result calculated by the SPL Notebook, compared to the spl_view field, it is relatively independent, can be executed directly and can join multiple data sources. Note: This scenario requires re-calculating and gen… | +| `sql_filter` | `string` | | | The SQL filter condition of the logstore, compared to the search_filter field, SQL filter conditions are more flexible and support more complex filter conditions, but the performance is relatively poor. | +| `sql_view` | `string` | | | The SQL view of the logstore, usually used to dynamically generate entity lists, connections, etc. Note: This scenario requires re-generating the view each time, and the performance is very poor. | diff --git a/docs/en/reference/schema/core/storage/sls-metricstore.md b/docs/en/reference/schema/core/storage/sls-metricstore.md new file mode 100644 index 0000000..8ee9e1e --- /dev/null +++ b/docs/en/reference/schema/core/storage/sls-metricstore.md @@ -0,0 +1,15 @@ +# sls_metricstore + +SLS MetricStore storage, usually used to store metric data. + +**Kind**: `sls_metricstore` + +> Every element shares the standard envelope `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` fields + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `region` | `string` | yes | | The region of the SLS MetricStore. | +| `project` | `string` | yes | | The project of the SLS MetricStore. | +| `store` | `string` | yes | | The name of the SLS MetricStore. | diff --git a/docs/en/reference/schema/index.md b/docs/en/reference/schema/index.md new file mode 100644 index 0000000..a2666f6 --- /dev/null +++ b/docs/en/reference/schema/index.md @@ -0,0 +1,55 @@ +# Schema Reference + +UModel schemas are organized as a layered standard. This reference documents the **L0 Core** abstractions — the base vocabulary every model is built from. + +## Standard layers + +| Layer | Name | Status | +|---|---|---| +| **L0** | **UModel Core** — EntitySet, DataSet, Link, Storage | Documented below | +| L1 | Semantic Conventions — shared service/host/pod/database semantics | Roadmap | +| L2 | Domain Profiles — DevOps, APM, Kubernetes, AIOps, … | Roadmap | +| L3 | Conformance — automated standard-compliance checks | Roadmap | + +See the contribution guide for how to propose L1–L3 content. + +## L0 Core abstractions + +### EntitySet + +- [entity_set](./core/entity-set) + +### DataSet + +- [entity_source](./core/dataset/entity-source) +- [event_set](./core/dataset/event-set) +- [explorer](./core/dataset/explorer) +- [log_set](./core/dataset/log-set) +- [metric_set](./core/dataset/metric-set) +- [profile_set](./core/dataset/profile-set) +- [runbook_set](./core/dataset/runbook-set) +- [trace_set](./core/dataset/trace-set) + +### Link + +- [data_link](./core/link/data-link) +- [entity_set_link](./core/link/entity-set-link) +- [entity_source_link](./core/link/entity-source-link) +- [explorer_link](./core/link/explorer-link) +- [runbook_link](./core/link/runbook-link) +- [storage_link](./core/link/storage-link) + +### Storage + +- [aliyun_prometheus](./core/storage/aliyun-prometheus) +- [elasticsearch](./core/storage/elasticsearch) +- [external_storage](./core/storage/external-storage) +- [mysql](./core/storage/mysql) +- [prometheus](./core/storage/prometheus) +- [sls_entitystore](./core/storage/sls-entitystore) +- [sls_logstore](./core/storage/sls-logstore) +- [sls_metricstore](./core/storage/sls-metricstore) + +### Building blocks + +- [Shared types](./shared-types) diff --git a/docs/en/reference/schema/shared-types.md b/docs/en/reference/schema/shared-types.md new file mode 100644 index 0000000..f2c8a2b --- /dev/null +++ b/docs/en/reference/schema/shared-types.md @@ -0,0 +1,163 @@ +# Shared types + +Reusable building blocks referenced by the schemas above. Documented once here. + +## metadata + +The MetaData module is used to define the meta data of all element in UModel. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `name` | `string` | yes | | The name of the Element in UModel System. The value cannot be empty.The value format is lowercase alphanumeric characters. | +| `display_name` | semantic_string (i18n) | | | The display name of the Element in UModel System. The value cannot be empty. | +| `description` | semantic_string (i18n) | | | The description of the Element in UModel System. | +| `short_description` | semantic_string (i18n) | | | The short description of the Element in UModel System. | +| `domain` | `string` | yes | | The domain of the Field. The value format is 'domain.domain'. it can be connected in the form of a dot. | +| `launch_stage` | enum: `preview`, `beta`, `ga`, `deprecated` | | `preview` | The launch stage of the Element. The default value is preview. | +| `icon` | `string` | | | The icon of the Element in UModel System. The value format is 'url'. | +| `uri` | `string` | | | This field is used to represent the unique identifier of the Element. | +| `tags` | map<string, string> | | | This field is used to represent the tags of the Element. | +| `properties` | map<string, string> | | | This field is used to represent the additional properties of the Element. | +| `common_schema_info` | object | | | Background: In the use of Alibaba Cloud Observability business, the built-in UModel data will be defaulted as a common UModel (CommonSchema), and the common UModel data will be configured as a reference (CommonSchemaR… | +| `common_schema_info.group` | `string` | | | The group of the common schema | +| `common_schema_info.version` | `string` | | | The version of the common schema | + +## schema + +The Schema module is used to define the version information of the Schema. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `url` | `string` | yes | | The url of the schema. The Core part is "umodel.aliyun.com" | +| `version` | `string` | yes | | The version of the schema. The format is "v1.2.3". | + +## telemetry_data + +The general representation of observable data, which is similar to the structure of a database table, but with the addition of time fields for the "observation" characteristics. Additionally, several fields are added… + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `fields` | array<[field_spec](shared-types#field_spec)> | | | The fields of the TelemetryData. | +| `time_field` | `string` | | | The time field of the TelemetryData. It is generally required to be a timestamp type, supporting seconds, milliseconds, microseconds, and nanoseconds. | +| `display_field` | `string` | | | Note: This field is deprecated. Please use the `name_fields` field instead. The display field of the TelemetryData. It is the default displayed field. | +| `name_fields` | array<string> | | | The name fields of the TelemetryData. It is recommended to configure the display fields in order of importance. Front-end, algorithms, etc. will freely choose according to the characteristics in various scenarios. For… | +| `hidden_fields` | array<string> | | | The hidden fields of the TelemetryData. | +| `tag_fields` | array<string> | | | The tag fields of the TelemetryData. The tag fields are aggregated by default for display and analysis. | +| `ordered_fields` | array<string> | | | The ordered fields of the TelemetryData. It is the ordered field of the current data set. | +| `default_order` | enum: `asc`, `desc` | | | The default order of the TelemetryData. The default value is asc. | + +## link + +The Link module is used to define the relationship between two entity set, data set, storage set and metric set. The Link module is the abstract module of all link module. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `src` | object | | | The identify of source Set. The value cannot be empty. | +| `src.domain` | `string` | yes | | The domain of the source Set. | +| `src.kind` | `string` | yes | | The type of the source Set. The value cannot be empty. | +| `src.name` | `string` | yes | | The name of the source Set. The value cannot be empty. | +| `src.filter` | `string` | | | The filter of the source Set. It is used for some Link scenarios, such as only entities with "region=cn-beijing" in the EntitySet have this association. This method is deprecated, please use filter_by_entity instead. | +| `dest` | object | | | The identify of the destination Set. The value cannot be empty. | +| `dest.domain` | `string` | yes | | The domain of the destination Set. | +| `dest.kind` | `string` | yes | | The type of the destination Set. The value cannot be empty. | +| `dest.name` | `string` | yes | | The name of the destination Set. The value cannot be empty. | +| `filter_by_entity` | `string` | | | In the Link that is only for some entities, used to identify the filtering conditions for these entities. | +| `priority` | `integer` | | `5` | The priority of the Link. The value can be empty. The default value is 5. | + +## field_spec + +The most basic definition of a field, which is the fundamental unit of data for logs, metrics, traces, entities, etc. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `name` | `string` | yes | | The name of the Field in UModel System. The value cannot be empty.The value format is lowercase alphanumeric characters. | +| `display_name` | semantic_string (i18n) | | | The display name of the Element in UModel System. The value cannot be empty. | +| `description` | semantic_string (i18n) | | | The description of the Element in UModel System. | +| `short_description` | semantic_string (i18n) | | | The short description of the Element in UModel System. | +| `launch_stage` | enum: `preview`, `beta`, `ga`, `deprecated` | | `preview` | The launch stage of the Element. The default value is preview. | +| `type` | enum: `string`, `integer`, `float`, `boolean`, `time`, `json_object`, `json_array` | yes | | The type of the Field. The value must be one of the following: string, integer, float, boolean, time, json_object, json_array. The value cannot be empty. | +| `value_mapping` | map<string, string> | | | For the mapping and interpretation of enumeration values, in order to better display the meaning of the mapping value, the value field of the mapping is defined separately. The value contains 4 fields: "name", "displa… | +| `unit` | `string` | | | The unit of the Metric. The value format is a string. Note: The unit is only used for display and will not be converted, such as ms will not be automatically converted to s. Best practice: First configure data_format,… | +| `data_format` | enum: `KMB`, `milli`, `byte`, `bit`, `byte_ies_sec`, `bit_ies_sec`, `iops`, `reqps` … (47 values) | | `KMB` | The formatting method for metrics, value format is string. Supported formatting options: Numeric formatting: - KMB: Thousands, millions, billions formatting, example: K,Mil,Bil - milli: Process as millisecond format,… | +| `analysable` | `bool` | | `false` | Used to denote whether the field is analyzable, i.e., serving as a column for Group By. default value is false. | +| `filterable` | `bool` | | `false` | Used to indicate whether this field can support filtering, i.e., it supports indexed filtering. default value is false. | +| `orderable` | `bool` | | `false` | Used to indicate whether the field is sortable. default value is false. | +| `default_order` | enum: `asc`, `desc` | | | Used to indicate the default sorting order of the field. The value must be one of the following: asc, desc. default value is asc. | +| `pattern` | `string` | | | Regular expression, used to define the range of values for this field (String). | +| `max_length` | `integer` | | | The max length of string value. Only valid for string type. | +| `example` | `any` | | | examples of the field value. The value can be empty. | +| `max_value` | `number` | | | The maximum value of the field. The value can be empty. Only valid for integer and float types. | +| `min_value` | `number` | | | The minimum value of the field. The value can be empty. Only valid for integer and float types. | +| `default_value` | `any` | | | The default value of the field. The value can be empty. | +| `icon` | `string` | | | The icon of the Element in UModel System. The value format is 'url'. | +| `uri` | `string` | | | This field is used to represent the unique identifier of the field. | +| `tags` | map<string, string> | | | This field is used to represent the tags of the Field. | +| `properties` | map<string, string> | | | This field is used to represent the additional properties of the Field. | + +## metric + +The Metric module is used to define the metric information. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `name` | `string` | yes | | The name of the Metric. The value cannot be empty. | +| `display_name` | semantic_string (i18n) | | | The display name of the Metric. The value cannot be empty. | +| `description` | semantic_string (i18n) | | | The description of the Metric. | +| `short_description` | semantic_string (i18n) | | | The short description of the Metric. | +| `launch_stage` | enum: `preview`, `beta`, `ga`, `deprecated` | | `preview` | The launch stage of the Element. The default value is preview. | +| `unit` | `string` | | | The unit of the Metric. The value format is a string. Note: The unit is only used for display and will not be converted, such as ms will not be automatically converted to s. Best practice: First configure data_format,… | +| `data_format` | enum: `KMB`, `milli`, `byte`, `bit`, `byte_ies_sec`, `bit_ies_sec`, `iops`, `reqps` … (47 values) | | `KMB` | The formatting method for metrics, value format is string. Supported formatting options: Numeric formatting: - KMB: Thousands, millions, billions formatting, example: K,Mil,Bil - milli: Process as millisecond format,… | +| `max_value` | `number` | | | The maximum value of the field. The value can be empty. Only valid for integer and float types. | +| `min_value` | `number` | | | The minimum value of the field. The value can be empty. Only valid for integer and float types. | +| `default_value` | `any` | | | The default value of the field. The value can be empty. | +| `icon` | `string` | | | This field is used to represent the icon of the Metric. | +| `labels` | array<[field_spec](shared-types#field_spec)> | | | This field is used to represent the labels of the Metric. It is the additional labels of the Metric on top of the labels in the MetricSet. | +| `golden_metric` | `boolean` | | `false` | Whether the metric is a golden metric. | +| `generator` | `string` | | | This field represents the generator of the Metric. If the mode is PromMode, this field is a PromQL statement that can be executed to get a Measure type metric directly. For example: rate(request_count{}[1m]). If the m… | +| `aggregator` | `string` | | | The aggregation method of the metric. If the metric is already aggregated, and the aggregation method is consistent in multiple dimension combinations, this field does not need to be configured, otherwise it needs to… | +| `interval_us` | object | | | The interval of the metric, value format is integer or array of integers, in microseconds. - When single integer: represents a fixed collection interval - When array of integers: represents multiple collection interva… | +| `type` | `string` | | `gauge` | This field indicates the metric type. For metrics that do not need to be processed again, this field should be fixed to gauge. | +| `query_mode` | enum: `range`, `instant`, `both` | | | This metric query mode. The value must be one of the following: range, instant, both. | +| `display_type` | `string` | | | This metric display type. | +| `statistics` | array<string> | | | The statistics method when generating this metric, that is, the metric has multiple generation methods. It is currently only used in the cloud monitor service scenario. | +| `tags` | map<string, string> | | | This field is used to represent the tags of the Metric. | +| `properties` | map<string, string> | | | This field is used to represent the additional properties of the Metric. | +| `default_fill_policy` | `string` | | | The default fill policy of the Metric. The value can be null, 0, last, next. | + +## observation + +Observation configuration definition for phenomenon observation and conclusion judgment. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `name` | `string` | yes | | Observation name, must be unique within the same RunbookSet. | +| `display_name` | semantic_string (i18n) | yes | | Observation display name. | +| `short_description` | semantic_string (i18n) | yes | | Observation short description. | +| `description` | semantic_string (i18n) | | | Observation detailed description. | +| `phenomenon` | object | yes | | Phenomenon definition, describing what to observe and how. | +| `phenomenon.phenomenon_type` | `string` | yes | | Phenomenon type such as query, action, dashboard, event. | +| `phenomenon.inputs` | array<object> | | | Phenomenon related input configurations, used to guide the upper layer to select default parameters for filling in. Including Dashboard variables, Query input parameters, etc. | +| `phenomenon.outputs` | array<object> | | | Optional, phenomenon related output configurations, used to guide the upper layer to parse the query results. | +| `phenomenon.properties` | map<string, string> | | | Phenomenon related properties, freely extensible based on type. | +| `conclusions` | array<object> | yes | | List of conclusion configurations based on phenomenon observation results. | +| `conclusions.condition_type` | `string` | yes | | Condition type for conclusion activation. Can be bool expression calculated after query/action execution, or prompts for LLM to judge. | +| `conclusions.condition` | `string` | yes | | Condition for conclusion activation. | +| `conclusions.severity` | enum: `info`, `warning`, `error`, `fatal` | yes | | Conclusion severity level. | +| `conclusions.display_name` | semantic_string (i18n) | yes | | Conclusion display name. | +| `conclusions.short_description` | semantic_string (i18n) | yes | | Conclusion short description. | +| `conclusions.description` | semantic_string (i18n) | | | Conclusion detailed description. | +| `conclusions.group` | `string` | yes | | Conclusion group. In the same conclusion group, only the highest level of conclusion is returned. | +| `conclusions.properties` | map<string, string> | | | Conclusion related properties. | +| `properties` | map<string, string> | | | Observation property configurations. | +| `tags` | map<string, string> | | | Observation tags. | + +## value_mapping + +The ValueMapping module is used to define the value mapping relationship. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `name` | `string` | yes | | The name of the Element in UModel System. The value cannot be empty.The value format is lowercase alphanumeric characters. | +| `display_name` | semantic_string (i18n) | | | The display name of the Element in UModel System. The value cannot be empty. | +| `description` | semantic_string (i18n) | | | The description of the Element in UModel System. | +| `short_description` | semantic_string (i18n) | | | The short description of the Element in UModel System. | diff --git a/docs/zh/reference/schema/core/dataset/entity-source.md b/docs/zh/reference/schema/core/dataset/entity-source.md new file mode 100644 index 0000000..15387e5 --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/entity-source.md @@ -0,0 +1,14 @@ +# entity_source + +EntitySource 用于定义特定 Entity 数据的导入任务以及其源数据存储（如 SLS LogStore / MetricStore）。 + +**Kind**: `entity_source` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `constructor` | map<string, any> | 是 | | 导入任务的构造/调度配置，支持灵活扩展键值对。 | +| `storages` | array<map> | 是 | | 源数据存储配置列表，每个元素为一个 map，支持灵活扩展字段。 | diff --git a/docs/zh/reference/schema/core/dataset/event-set.md b/docs/zh/reference/schema/core/dataset/event-set.md new file mode 100644 index 0000000..775f057 --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/event-set.md @@ -0,0 +1,18 @@ +# event_set + +EventSet 用于定义事件，事件集是具有相同属性的事件的集合。 + +**Kind**: `event_set` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `entity_fields` | object | | | 实体字段，用于标识实体的 ID、域和类型 | +| `entity_fields.entity_id` | `string` | | `__entity_id__` | 实体 ID 字段 | +| `entity_fields.domain` | `string` | | `__domain__` | 实体所属的域字段 | +| `entity_fields.entity_type` | `string` | | `__entity_type__` | 实体类型字段，用于标识实体的类型 | diff --git a/docs/zh/reference/schema/core/dataset/explorer.md b/docs/zh/reference/schema/core/dataset/explorer.md new file mode 100644 index 0000000..8407962 --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/explorer.md @@ -0,0 +1,13 @@ +# explorer + +**Kind**: `explorer` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `type` | `string` | 是 | | Explorer 的类型。 | +| `query` | `string` | | | Explorer 的默认查询。 | +| `config` | map<string, any> | | | Explorer 的配置动态。 | diff --git a/docs/zh/reference/schema/core/dataset/log-set.md b/docs/zh/reference/schema/core/dataset/log-set.md new file mode 100644 index 0000000..0e3ea68 --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/log-set.md @@ -0,0 +1,13 @@ +# log_set + +LogSet 用于定义日志，日志集是具有相同属性的日志的集合。 + +**Kind**: `log_set` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` 字段 + +_除继承的基类外，该元素没有额外的 `spec` 字段。_ diff --git a/docs/zh/reference/schema/core/dataset/metric-set.md b/docs/zh/reference/schema/core/dataset/metric-set.md new file mode 100644 index 0000000..674f316 --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/metric-set.md @@ -0,0 +1,20 @@ +# metric_set + +MetricSet 用于定义指标，指标集是具有相同属性的指标的集合，一般用于描述某类可观测实体的一类指标，例如主机的CPU、内存、磁盘等指标。 + +**Kind**: `metric_set` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `labels` | object | | | 指标集的标签列表，建议标签通过 dynamic 方式自动生成。注意：此处的标签是 MetricSet 的通用标签，一般建议 MetricSet 只定义通用标签，不在 Metric 下定义额外的标签。 | +| `labels.keys` | array<[field_spec](../../shared-types#field_spec)> | | | 标签列表，值格式参考 field 定义。 | +| `labels.dynamic` | `boolean` | | `false` | 是否动态生成，一般建议设置为 true。 | +| `labels.filter` | `string` | | | 标签的过滤器，在 dynamic 为 true 时，会根据此过滤器进行过滤。 | +| `label_keys` | array<[field_spec](../../shared-types#field_spec)> | | | 指标集的标签键。当前已废弃，待删除，请使用 labels 字段代替。 | +| `metrics` | array<[metric](../../shared-types#metric)> | | | 详细的指标列表。 | +| `query_type` | enum: `prom`, `spl`, `cms` | | | 指标的查询语法，取值包括：prom、spl、cms 。 | +| `needs_processing` | `boolean` | | `false` | 是否需要二次处理，即该 MetricSet 中指标是否需要二次处理才能被使用。例如 Prometheus 中的 counter/summary/histogram 等指标需要二次处理才能被使用。 | diff --git a/docs/zh/reference/schema/core/dataset/profile-set.md b/docs/zh/reference/schema/core/dataset/profile-set.md new file mode 100644 index 0000000..28c5d4b --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/profile-set.md @@ -0,0 +1,15 @@ +# profile_set + +ProfileSet 用于定义 Profile 数据集，Profile 数据集是具有相同属性的 Profile 数据的集合，一般用于描述某类可观测实体的一类 Profile 数据，例如主机的 CPU、内存、磁盘等 Profile 数据。 + +**Kind**: `profile_set` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `protocol` | `string` | | `pprof` | 使用的 Profile 协议。指定 Profile 数据的格式和标准。 | diff --git a/docs/zh/reference/schema/core/dataset/runbook-set.md b/docs/zh/reference/schema/core/dataset/runbook-set.md new file mode 100644 index 0000000..5d212f4 --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/runbook-set.md @@ -0,0 +1,18 @@ +# runbook_set + +RunbookSet 用于定义实体、数据的操作手册集合，包含分析工具、操作指南和最佳实践。 + +**Kind**: `runbook_set` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `observations` | array<[observation](../../shared-types#observation)> | | | 观察配置列表 | +| `actions` | array<object> | | | 操作能力配置列表 | +| `toolkits` | array<object> | | | 工具箱配置列表，每个工具箱包含共享配置和一组工具 | +| `knowledge` | array<object> | | | 知识库配置列表 | +| `automations` | array<object> | | | 自动化配置列表 | +| `skills` | array<object> | | | 技能配置列表，遵循 Agent Skills 规范 | diff --git a/docs/zh/reference/schema/core/dataset/trace-set.md b/docs/zh/reference/schema/core/dataset/trace-set.md new file mode 100644 index 0000000..534762c --- /dev/null +++ b/docs/zh/reference/schema/core/dataset/trace-set.md @@ -0,0 +1,19 @@ +# trace_set + +TraceSet 是具有某些共同属性或特征的相关追踪记录的集合。TraceSet 必须包含以下字段：trace_id_field、span_id_field、parent_span_id_field 和 protocol（默认值为opentelemetry）。 + +**Kind**: `trace_set` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [telemetry_data](../../shared-types#telemetry_data) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `attribute_fields` | array<[field_spec](../../shared-types#field_spec)> | | | TraceSet 的属性列表，值格式为定义追踪属性的字段规格列表。当前未使用。 | +| `trace_id_field` | `string` | 是 | `traceId` | TraceSet 的 trace_id 字段名称。 | +| `span_id_field` | `string` | 是 | `spanId` | TraceSet 的 span_id 字段名称。 | +| `parent_span_id_field` | `string` | | `parentSpanId` | TraceSet 的 parent_span_id 字段名称。 | +| `protocol` | `string` | | `opentelemetry` | 使用的追踪协议。指定追踪数据的格式和标准。 | diff --git a/docs/zh/reference/schema/core/entity-set.md b/docs/zh/reference/schema/core/entity-set.md new file mode 100644 index 0000000..b0d4be2 --- /dev/null +++ b/docs/zh/reference/schema/core/entity-set.md @@ -0,0 +1,20 @@ +# entity_set + +EntitySet 用于定义实体，实体集是具有相同属性的实体的集合，类似于数据库中的表、编程中的类概念。在建模场景中，可根据需要定义关心的实体，例如IT可观测场景中，需要定义主机、容器、进程、应用、Code Repo、运维人员等。 + +**Kind**: `entity_set` + +> 每个元素共享标准信封 `kind` · [metadata](../shared-types#metadata) · [schema](../shared-types#schema). + +**继承**: [telemetry_data](../shared-types#telemetry_data) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `first_observed_time_field` | `string` | | | Entity 的首次被观测时间所在字段。 | +| `last_observed_time_field` | `string` | | | Entity 最近被观测时间所在字段。 | +| `primary_key_fields` | array<string> | | | Entity 的主键字段。值格式为唯一标识实体的字段名称列表。 | +| `id_generator` | `string` | | | Entity 的 ID 生成器。表示该 EntitySet 的ID如何通过PrimaryKeyFields 生成。该字段类型为 string，需要符合 SPL 的表达式语法，执行返回为 string。如果为空，则使用默认的生成方式： lower(to_hex(md5(cast(join(primaryKeys, '#$#') as varbinary)))) ，即将 PrimaryKeyFields 拼接成字符串，然后进行 MD5… | +| `keep_alive_seconds` | `number` | | `3600` | 保持活跃的持续时间，在最后观测时间加上保活秒数后，Entity 将被视为消失。默认为3600秒（1小时）。 | +| `dynamic` | `bool` | | `false` | 是否为动态生成，默认为false。为true时表示该实体为动态实体，会绑定 Storage，每次实体的内容由Storage 处获取，而非存储在 EntityStore 中。 | diff --git a/docs/zh/reference/schema/core/link/data-link.md b/docs/zh/reference/schema/core/link/data-link.md new file mode 100644 index 0000000..138c67a --- /dev/null +++ b/docs/zh/reference/schema/core/link/data-link.md @@ -0,0 +1,17 @@ +# data_link + +DataLink 用于定义 EntitySet/Link 和 DataSet 之间的关系，同时也可以描述两个 DataSet 之间的关系。DataLink 必须包含源 DataSet 、目标 DataSet 和链接类型。 + +**Kind**: `data_link` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [link](../../shared-types#link) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `fields_mapping` | map<string, string> | | | 源 DataSet/EntitySet 和目标 DataSet 字段之间的映射关系。 | +| `data_link_type` | enum: `produce`, `related_to` | | | DataLink 的类型。值不能为空。值必须是以下之一：produce（产生）、related_to（有关联，即弱连接）。 | +| `data_filter` | `string` | | | 关联目标数据的过滤器，即目标 DataSet 中只有部分数据和源数据有关联。例如存在一个通用的MetricSet，包含各种调用类型的指标，而源实体可能是DBClient，则可通过 data_fiter = "type='db'" 过滤出所有 db 类型的指标。注意：data_filter 需要使用query类型的filter语法。此方式过于复杂，不建议使用。 | diff --git a/docs/zh/reference/schema/core/link/entity-set-link.md b/docs/zh/reference/schema/core/link/entity-set-link.md new file mode 100644 index 0000000..b778b29 --- /dev/null +++ b/docs/zh/reference/schema/core/link/entity-set-link.md @@ -0,0 +1,18 @@ +# entity_set_link + +EntitySetLink 用于定义两个 EntitySet 之间的关系。EntitySetLink 必须包含源 EntitySet 、目标 EntitySet 和链接类型。 + +**Kind**: `entity_set_link` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [link](../../shared-types#link) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `fields_mapping` | map<string, string> | | | EntitySetLink 的目标 EntitySet 字段映射。 | +| `constructor` | object | | | EntitySetLink 的自动化生成配置。若配置了此字段，则后台会自动创建并维护任务，自动生成 EntitySetLink。 | +| `entity_link_type` | `string` | 是 | | EntityLinkSet 的链接类型。值不能为空。建议的取值有： - calls (调用) - runs (运行) - instance_of (实例) - parent_of (父级) - contains (包含) - balances (平衡) - can_access (可访问) - clustered_by (集群化) - manages (管理) - monitors (监控) - sends_to (发送到) -… | +| `dynamic` | `bool` | | `false` | 是否为动态生成，默认为false。为true时表示该 EntitySetLink 为动态 Link，会绑定 Storage，每次 Link 的内容由Storage 处获取，而非存储在 EntityStore 中。 | diff --git a/docs/zh/reference/schema/core/link/entity-source-link.md b/docs/zh/reference/schema/core/link/entity-source-link.md new file mode 100644 index 0000000..04d9400 --- /dev/null +++ b/docs/zh/reference/schema/core/link/entity-source-link.md @@ -0,0 +1,22 @@ +# entity_source_link + +EntitySourceLink 用于定义 EntitySource 与 EntitySet 之间的关联关系。 + +**Kind**: `entity_source_link` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [link](../../shared-types#link) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `src` | object | 是 | | 源 Set 的标识。值不能为空。 | +| `src.domain` | `string` | 是 | | 源 Set 的域。 | +| `src.kind` | enum: `entity_source` | 是 | | 源 Set 的类型。值不能为空。 | +| `src.name` | `string` | 是 | | 源 Set 的名称。值不能为空。 | +| `dest` | object | 是 | | 目标 Set 的标识。值不能为空。 | +| `dest.domain` | `string` | 是 | | 目标 Set 的域。 | +| `dest.kind` | enum: `entity_set` | 是 | | 目标 Set 的类型。值不能为空。 | +| `dest.name` | `string` | 是 | | 目标 Set 的名称。值不能为空。 | diff --git a/docs/zh/reference/schema/core/link/explorer-link.md b/docs/zh/reference/schema/core/link/explorer-link.md new file mode 100644 index 0000000..a98aa9a --- /dev/null +++ b/docs/zh/reference/schema/core/link/explorer-link.md @@ -0,0 +1,15 @@ +# explorer_link + +**Kind**: `explorer_link` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [link](../../shared-types#link) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `token_mapping` | map<string, string> | | | 源 Dataset 和目标 Explorer 之间的字段映射关系。 | +| `token_replace` | map<string, string> | | | 源 Dataset 和目标 Explorer 之间的字段替换关系。 | +| `config` | map<string, string> | | | Explorer 的配置动态。 | diff --git a/docs/zh/reference/schema/core/link/runbook-link.md b/docs/zh/reference/schema/core/link/runbook-link.md new file mode 100644 index 0000000..1523596 --- /dev/null +++ b/docs/zh/reference/schema/core/link/runbook-link.md @@ -0,0 +1,16 @@ +# runbook_link + +RunbookLink 用于定义实体集合与操作手册集合之间的关联关系。 + +**Kind**: `runbook_link` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [link](../../shared-types#link) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `token_replace` | map<string, string> | | | 上下文变量的映射关系，用于在执行 Runbook 时提供动态上下文变量。 | +| `fields_mapping` | map<string, string> | | | 源数据集字段到目标 Runbook 字段的映射关系，用于将数据集中的字段值传递给 Runbook 的输入参数。 | diff --git a/docs/zh/reference/schema/core/link/storage-link.md b/docs/zh/reference/schema/core/link/storage-link.md new file mode 100644 index 0000000..389334f --- /dev/null +++ b/docs/zh/reference/schema/core/link/storage-link.md @@ -0,0 +1,15 @@ +# storage_link + +StorageLink 用于定义 EntitySet/DataSet 和 Storage 之间的关系。StorageLink 必须包含源 Set 、目标 Storage。 + +**Kind**: `storage_link` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +**继承**: [link](../../shared-types#link) + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `fields_mapping` | map<string, string> | | | 用于定义简单的字段映射关系，例如 DataSet 中 Field 的名称与 Storage 中字段名称的映射关系。 | diff --git a/docs/zh/reference/schema/core/storage/aliyun-prometheus.md b/docs/zh/reference/schema/core/storage/aliyun-prometheus.md new file mode 100644 index 0000000..9fe46c9 --- /dev/null +++ b/docs/zh/reference/schema/core/storage/aliyun-prometheus.md @@ -0,0 +1,16 @@ +# aliyun_prometheus + +阿里云 Prometheus 实例的定义，用于描述阿里云 Prometheus 实例的配置和连接信息。 + +**Kind**: `aliyun_prometheus` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `region` | `string` | 是 | | 阿里云 Prometheus 实例所属区域。 | +| `instance_id` | `string` | 是 | | 阿里云 Prometheus 的实例ID。 | +| `sls_project` | `string` | | | 阿里云 Prometheus 数据存储所在的 SLS 项目名称。 | +| `sls_metricstore` | `string` | | | 阿里云 Prometheus 数据存储所在的 SLS 时序库名称。 | diff --git a/docs/zh/reference/schema/core/storage/elasticsearch.md b/docs/zh/reference/schema/core/storage/elasticsearch.md new file mode 100644 index 0000000..ca2753f --- /dev/null +++ b/docs/zh/reference/schema/core/storage/elasticsearch.md @@ -0,0 +1,26 @@ +# elasticsearch + +Elasticsearch 存储，用于描述 Elasticsearch 集群、索引以及查询规划所需的连接信息。 + +**Kind**: `elasticsearch` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `endpoint` | `string` | 是 | | Elasticsearch 集群访问地址，例如 https://es.example.com:9200。 | +| `index` | `string` | 是 | | 默认查询索引名称，也可以是 Elasticsearch 支持的索引通配表达式。 | +| `index_pattern` | `string` | | | 面向按时间滚动索引的索引模式，例如 logs-${yyyy.MM.dd}。如果为空，查询规划使用 index 字段。 | +| `version` | `string` | | | Elasticsearch 版本号或版本族，例如 7.x、8.x。 | +| `query_dialect` | enum: `elasticsearch_dsl`, `lucene`, `eql` | | `elasticsearch_dsl` | 查询生成方言。默认生成 Elasticsearch Query DSL。 | +| `time_field` | `string` | | | 时间过滤字段名，用于将请求时间范围下推到 Elasticsearch 查询中。 | +| `default_size` | `integer` | | `1000` | 未显式指定 limit 时生成查询的默认 size。 | +| `max_size` | `integer` | | `10000` | 查询规划允许生成的最大 size，用于避免生成过大的查询计划。 | +| `routing` | `string` | | | 可选的 Elasticsearch routing 值。用于规划需要固定 routing 的查询。 | +| `credential_ref` | `string` | | | 凭据引用标识，例如 secret://es-prod-readonly。不得在 UModel 中保存明文用户名、密码或 Token。 | +| `tls_verify` | `boolean` | | `true` | 是否校验 TLS 证书。默认值为 true。 | +| `headers` | map<string, string> | | | 非敏感 HTTP 头，用于租户、路由等查询上下文。不得存放认证密钥。 | +| `properties` | map<string, string> | | | Elasticsearch 的额外非敏感配置，以键值对形式存储。 | +| `tags` | map<string, string> | | | 用于标注该 Elasticsearch 存储的标签。 | diff --git a/docs/zh/reference/schema/core/storage/external-storage.md b/docs/zh/reference/schema/core/storage/external-storage.md new file mode 100644 index 0000000..23e2597 --- /dev/null +++ b/docs/zh/reference/schema/core/storage/external-storage.md @@ -0,0 +1,16 @@ +# external_storage + +外部存储，用于存放自定义存储的详细信息。 + +**Kind**: `external_storage` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `type` | `string` | 是 | | 外部存储的类型。 | +| `name` | `string` | 是 | | 外部存储的名称。 | +| `properties` | map<string, string> | | | 外部存储的详细信息，以键值对形式存储。 | +| `tags` | map<string, string> | | | 用于表示该外部存储的标签。 | diff --git a/docs/zh/reference/schema/core/storage/mysql.md b/docs/zh/reference/schema/core/storage/mysql.md new file mode 100644 index 0000000..24e4f9e --- /dev/null +++ b/docs/zh/reference/schema/core/storage/mysql.md @@ -0,0 +1,26 @@ +# mysql + +MySQL 存储，用于描述 MySQL 实例、数据库、表以及查询规划所需的连接信息。 + +**Kind**: `mysql` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `endpoint` | `string` | 是 | | MySQL 实例访问地址，格式通常为 host:port。 | +| `database` | `string` | 是 | | 默认查询数据库名称。 | +| `table` | `string` | | | 默认查询表名。若 DataSet 或查询参数中指定表名，可覆盖此字段。 | +| `sql_template` | `string` | | | 可选 SQL 模板，用于特殊查询规划场景。模板必须保持只读语义，不应包含 INSERT、UPDATE、DELETE、DDL 等语句。 | +| `sql_dialect` | enum: `mysql`, `ansi` | | `mysql` | SQL 方言。MySQL 存储默认使用 mysql。 | +| `time_field` | `string` | | | 时间过滤字段名，用于将请求时间范围下推到 SQL WHERE 条件中。 | +| `time_unit` | enum: `second`, `millisecond`, `microsecond`, `nanosecond`, `datetime` | | `second` | time_field 的时间单位。默认值为 second。 | +| `default_limit` | `integer` | | `1000` | 未显式指定 limit 时生成查询的默认 LIMIT。 | +| `max_limit` | `integer` | | `10000` | 查询规划允许生成的最大 LIMIT，用于避免生成过大的查询计划。 | +| `read_only` | `boolean` | | `true` | 标识该存储是否只能规划只读查询。默认值为 true；UModel PaaS 查询规划不应生成写入语句。 | +| `credential_ref` | `string` | | | 凭据引用标识，例如 secret://mysql-prod-readonly。不得在 UModel 中保存明文用户名、密码或 Token。 | +| `tls_mode` | enum: `disabled`, `preferred`, `required`, `verify_ca`, `verify_identity` | | `preferred` | MySQL TLS 模式。默认值为 preferred。 | +| `properties` | map<string, string> | | | MySQL 的额外非敏感配置，以键值对形式存储。 | +| `tags` | map<string, string> | | | 用于标注该 MySQL 存储的标签。 | diff --git a/docs/zh/reference/schema/core/storage/prometheus.md b/docs/zh/reference/schema/core/storage/prometheus.md new file mode 100644 index 0000000..a1a1c20 --- /dev/null +++ b/docs/zh/reference/schema/core/storage/prometheus.md @@ -0,0 +1,25 @@ +# prometheus + +Prometheus 存储，用于描述开源 Prometheus 或 Prometheus 兼容接口的配置和查询规划信息。 + +**Kind**: `prometheus` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `endpoint` | `string` | 是 | | Prometheus 或 Prometheus 兼容服务的访问地址，例如 http://prometheus:9090。 | +| `api_prefix` | `string` | | `/api/v1` | Prometheus HTTP API 前缀。默认值为 /api/v1。 | +| `default_query_type` | enum: `instant`, `range` | | `instant` | 默认 PromQL 查询类型。instant 表示即时查询，range 表示区间查询。 | +| `default_step` | `string` | | | 区间查询的默认 step，例如 60s、1m。 | +| `lookback_delta` | `string` | | | PromQL 查询规划使用的默认回看窗口，例如 5m。 | +| `tenant` | `string` | | | 可选租户标识，用于多租户 Prometheus 兼容系统。 | +| `tenant_header` | `string` | | | 多租户系统使用的租户 HTTP 头名称，例如 X-Scope-OrgID。 | +| `credential_ref` | `string` | | | 凭据引用标识，例如 secret://prometheus-prod-readonly。不得在 UModel 中保存明文用户名、密码或 Token。 | +| `tls_verify` | `boolean` | | `true` | 是否校验 TLS 证书。默认值为 true。 | +| `external_labels` | map<string, string> | | | Prometheus 外部标签，用于 query planning 时补充查询上下文或结果来源说明。 | +| `headers` | map<string, string> | | | 非敏感 HTTP 头，用于租户、路由等查询上下文。不得存放认证密钥。 | +| `properties` | map<string, string> | | | Prometheus 的额外非敏感配置，以键值对形式存储。 | +| `tags` | map<string, string> | | | 用于标注该 Prometheus 存储的标签。 | diff --git a/docs/zh/reference/schema/core/storage/sls-entitystore.md b/docs/zh/reference/schema/core/storage/sls-entitystore.md new file mode 100644 index 0000000..812c1c3 --- /dev/null +++ b/docs/zh/reference/schema/core/storage/sls-entitystore.md @@ -0,0 +1,15 @@ +# sls_entitystore + +SLS EntityStore 存储，一般用于存储可观测实体以及关系数据。 + +**Kind**: `sls_entitystore` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `region` | `string` | 是 | | SLS EntityStore 的区域。 | +| `project` | `string` | 是 | | SLS EntityStore 的项目。 | +| `workspace` | `string` | 是 | | SLS EntityStore 的工作空间。 | diff --git a/docs/zh/reference/schema/core/storage/sls-logstore.md b/docs/zh/reference/schema/core/storage/sls-logstore.md new file mode 100644 index 0000000..e0a3512 --- /dev/null +++ b/docs/zh/reference/schema/core/storage/sls-logstore.md @@ -0,0 +1,21 @@ +# sls_logstore + +SLS LogStore 存储，一般用于存储日志数据。 + +**Kind**: `sls_logstore` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `region` | `string` | 是 | | SLS LogStore 的区域。 | +| `project` | `string` | 是 | | SLS LogStore 的项目。 | +| `store` | `string` | 是 | | SLS LogStore 的名称。 | +| `search_filter` | `string` | | `*` | 日志库的过滤条件，如果日志库中存储了多种类型的数据，可使用此字段过滤目标数据。 | +| `spl_filter` | `string` | | | 日志库的 SPL 过滤条件，相比 search_filter 字段，SPL 过滤条件更加灵活，支持更复杂的过滤条件，但性能相对较差。 | +| `spl_view` | `string` | | | 基于 SPL 生成的视图，一般用于动态生成实体列表、连接等场景。注意：此场景每次需要重新生成视图，性能较差。 | +| `spl_notebook` | `string` | | | 基于 SPL Notebook 计算出的结果，相比 spl_view 字段，相对更加独立，可直接执行且能 Join 多种数据源。注意：此场景每次需要重新计算生成，性能较差。 | +| `sql_filter` | `string` | | | 日志库的 SQL 过滤条件，相比 search_filter 字段，SQL 过滤条件更加灵活，支持更复杂的过滤条件，但性能相对较差。 | +| `sql_view` | `string` | | | 基于 SQL 生成的视图，一般用于动态生成实体列表、连接等场景。注意：此场景每次需要重新生成视图，性能较差。 | diff --git a/docs/zh/reference/schema/core/storage/sls-metricstore.md b/docs/zh/reference/schema/core/storage/sls-metricstore.md new file mode 100644 index 0000000..007cd36 --- /dev/null +++ b/docs/zh/reference/schema/core/storage/sls-metricstore.md @@ -0,0 +1,15 @@ +# sls_metricstore + +SLS MetricStore 存储，一般用于存储指标数据。 + +**Kind**: `sls_metricstore` + +> 每个元素共享标准信封 `kind` · [metadata](../../shared-types#metadata) · [schema](../../shared-types#schema). + +## `spec` 字段 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `region` | `string` | 是 | | SLS MetricStore 的区域。 | +| `project` | `string` | 是 | | SLS MetricStore 的项目。 | +| `store` | `string` | 是 | | SLS MetricStore 的名称。 | diff --git a/docs/zh/reference/schema/index.md b/docs/zh/reference/schema/index.md new file mode 100644 index 0000000..610caf5 --- /dev/null +++ b/docs/zh/reference/schema/index.md @@ -0,0 +1,55 @@ +# Schema 参考 + +UModel 的 schema 按分层标准组织。本参考记录 **L0 Core** 抽象——构建一切模型的基础词汇。 + +## 标准分层 + +| 层级 | 名称 | 状态 | +|---|---|---| +| **L0** | **UModel Core** —— EntitySet、DataSet、Link、Storage | 见下文 | +| L1 | Semantic Conventions —— 通用 service/host/pod/database 语义 | 规划中 | +| L2 | Domain Profiles —— DevOps、APM、Kubernetes、AIOps…… | 规划中 | +| L3 | Conformance —— 自动化标准兼容性校验 | 规划中 | + +L1–L3 的贡献方式见贡献指南。 + +## L0 Core 抽象 + +### EntitySet（实体集） + +- [entity_set](./core/entity-set) + +### DataSet（数据集） + +- [entity_source](./core/dataset/entity-source) +- [event_set](./core/dataset/event-set) +- [explorer](./core/dataset/explorer) +- [log_set](./core/dataset/log-set) +- [metric_set](./core/dataset/metric-set) +- [profile_set](./core/dataset/profile-set) +- [runbook_set](./core/dataset/runbook-set) +- [trace_set](./core/dataset/trace-set) + +### Link（链接） + +- [data_link](./core/link/data-link) +- [entity_set_link](./core/link/entity-set-link) +- [entity_source_link](./core/link/entity-source-link) +- [explorer_link](./core/link/explorer-link) +- [runbook_link](./core/link/runbook-link) +- [storage_link](./core/link/storage-link) + +### Storage（存储） + +- [aliyun_prometheus](./core/storage/aliyun-prometheus) +- [elasticsearch](./core/storage/elasticsearch) +- [external_storage](./core/storage/external-storage) +- [mysql](./core/storage/mysql) +- [prometheus](./core/storage/prometheus) +- [sls_entitystore](./core/storage/sls-entitystore) +- [sls_logstore](./core/storage/sls-logstore) +- [sls_metricstore](./core/storage/sls-metricstore) + +### 构建块 + +- [共享类型](./shared-types) diff --git a/docs/zh/reference/schema/shared-types.md b/docs/zh/reference/schema/shared-types.md new file mode 100644 index 0000000..3121b8c --- /dev/null +++ b/docs/zh/reference/schema/shared-types.md @@ -0,0 +1,163 @@ +# 共享类型 + +上述 schema 引用的可复用构建块，在此统一记录一次。 + +## metadata + +MetaData 用于定义 UModel 系统中所有元素的元数据。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `name` | `string` | 是 | | 元素在 UModel 系统中的名称。值不能为空。值格式为小写字母数字字符。 | +| `display_name` | semantic_string (i18n) | | | 元素在 UModel 系统中的显示名称。值不能为空。 | +| `description` | semantic_string (i18n) | | | 元素在 UModel 系统中的描述。 | +| `short_description` | semantic_string (i18n) | | | 元素在 UModel系统中的简短描述。 | +| `domain` | `string` | 是 | | 域。值格式为'domain.domain'。可以以点连接。 | +| `launch_stage` | enum: `preview`, `beta`, `ga`, `deprecated` | | `preview` | 元素的发布阶段。默认值为 preview。 | +| `icon` | `string` | | | 元素在UModel系统中的图标。值格式为'url'。 | +| `uri` | `string` | | | 用于表示该元素唯一标识。 | +| `tags` | map<string, string> | | | 用于表示该元素的标签。 | +| `properties` | map<string, string> | | | 用于表示该元素的附加属性。 | +| `common_schema_info` | object | | | 背景：在阿里云可观测业务使用中，内置的UModel数据会作为公共UModel（CommonSchema）默认存在，公共UModel数据以引用方式（CommonSchemaRef）配置在UModel，在查询时动态生成UModel实例并附加该字段作为额外说明。 使用方式：该字段不需要手动配置，仅供查看。若存在该字段，则说明对应的UModel实例只可查看，不支持编辑或删除；若不存在该字段，则可根据业务需求按需编辑。 | +| `common_schema_info.group` | `string` | | | CommonSchema的Group信息 | +| `common_schema_info.version` | `string` | | | CommonSchema的版本号 | + +## schema + +用于定义 Schema 的版本信息。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `url` | `string` | 是 | | Schema 的 URL。Core 部分都为 "umodel.aliyun.com" | +| `version` | `string` | 是 | | Schema 的版本。命名格式为 "v1.2.3"。 | + +## telemetry_data + +可观测数据（遥测数据、TelemetryData）的通用表示，从结构上类似于数据库的表，但针对“观测”特点，附加了时间字段。此外增加了若干字段，用于表示该数据集的特性。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `fields` | array<[field_spec](shared-types#field_spec)> | | | 可观测数据的字段列表。 | +| `time_field` | `string` | | | 可观测数据的时间字段。一般要求时间字段为时间戳类型，支持秒、毫秒、微秒、纳秒。 | +| `display_field` | `string` | | | 注意：定位和 `name_fields` 有一定重叠，字段已废弃，请使用 `name_fields` 字段第一个值替代。可观测数据的显示字段。即默认展示的字段。 | +| `name_fields` | array<string> | | | 可观测数据的显示字段。建议按照显示重要性配置先后顺序，前端、算法等在各类场景会根据特点自由选择，例如极窄/引用场景下只取name_fields的第一个值。 例如：服务操作实体，建议取值为 ["operation_name", "service_name"]； K8s Pod 实体，建议取值为 ["pod_name", "namespace", "cluster"]。 | +| `hidden_fields` | array<string> | | | 可观测数据的隐藏字段。即不用作展示的字段。 | +| `tag_fields` | array<string> | | | 可观测数据的标签字段。标签字段默认聚合在一起显示和分析。 | +| `ordered_fields` | array<string> | | | 可观测数据的排序字段。即当前数据集的排序字段。 | +| `default_order` | enum: `asc`, `desc` | | | 可观测数据的默认排序。默认值为 asc。 | + +## link + +Link 用于定义两个 Set 之间的关系。是所有 Link 的抽象模块。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `src` | object | | | 源 Set 的标识。值不能为空。 | +| `src.domain` | `string` | 是 | | 源 Set 的域。 | +| `src.kind` | `string` | 是 | | 源 Set 的类型。值不能为空。 | +| `src.name` | `string` | 是 | | 源 Set 的名称。值不能为空。 | +| `src.filter` | `string` | | | 对于源 Set 的过滤器，用于部分 Link 的场景，例如 EntitySet 中只有"region=cn-beijing"的实体存在此关联。该方式已废弃，请使用 filter_by_entity 替代。 | +| `dest` | object | | | 目标 Set 的标识。值不能为空。 | +| `dest.domain` | `string` | 是 | | 目标 Set 的域。 | +| `dest.kind` | `string` | 是 | | 目标 Set 的类型。值不能为空。 | +| `dest.name` | `string` | 是 | | 目标 Set 的名称。值不能为空。 | +| `filter_by_entity` | `string` | | | 在部分Entity具备的Link中，用于标识这部分Entity的过滤条件。 | +| `priority` | `integer` | | `5` | Link 的优先级。值可以为空。默认值为5。 | + +## field_spec + +字段是日志、指标、追踪、实体等数据的最基本定义，是数据的基本单位。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `name` | `string` | 是 | | Field 在 UModel 系统中的名称。值不能为空。值格式为小写字母数字字符。 | +| `display_name` | semantic_string (i18n) | | | Field 在 UModel 系统中的显示名称。值不能为空。 | +| `description` | semantic_string (i18n) | | | Field 在 UModel 系统中的描述。 | +| `short_description` | semantic_string (i18n) | | | Field 在 UModel 系统中的简短描述。 | +| `launch_stage` | enum: `preview`, `beta`, `ga`, `deprecated` | | `preview` | 元素的发布阶段。默认值为 preview。 | +| `type` | enum: `string`, `integer`, `float`, `boolean`, `time`, `json_object`, `json_array` | 是 | | 字段的类型。值必须是以下之一：string、integer、float、boolean、time、json_object、json_array。值不能为空。 | +| `value_mapping` | map<string, string> | | | 对于枚举值的映射和解释，为了更好的展示映射值含义，对于 mapping 的 value 字段单独定义，value 包含4个字段："name"、"display_name"、"description"和"short_description"。例如，"status"字段的值是"1"，映射为 ：name 为 "running" ，display_name 为"运行中"，description 为"运行中......"，short_des… | +| `unit` | `string` | | | 指标的单位，值格式为字符串。 注意：单位仅用于展示，不会进行格式转换，例如 ms 不会自动根据大小转换为 s。 最佳实践：首先配置 data_format ，在大部分可观测场景下，data_format 即可满足需求，unit 填写为空即可。 若不满足需求，一般建议 data_format 配置通用的 KMB， 并配置 unit 为特定类型。比如温度，可以配置 data_format 为 KMB， 并配置 unit 为 °C。 | +| `data_format` | enum: `KMB`, `milli`, `byte`, `bit`, `byte_ies_sec`, `bit_ies_sec`, `iops`, `reqps` … (47 values) | | `KMB` | 指标的格式化方式，值格式为字符串。支持的格式化选项： 数值格式化： - KMB: 千、百万、十亿格式化，样例：K,Mil,Bil - milli: 处理为毫秒格式，样例：1,000,000 存储格式化： - byte: 处理为字节格式，样例：B/KB/MB - bit: 处理为位格式，样例：b/Kb/Mb 速率格式化： - byte_ies_sec: 每秒字节（byte per second）格式化，样例：B/s/KB/s/MB/… | +| `analysable` | `bool` | | `false` | 用于表示字段是否可分析，即作为Group By的列。默认值为false。 | +| `filterable` | `bool` | | `false` | 用于表示字段是否可过滤，即支持索引过滤。默认值为false。 | +| `orderable` | `bool` | | `false` | 用于表示字段是否可排序。默认值为false。 | +| `default_order` | enum: `asc`, `desc` | | | 用于表示字段的默认排序顺序。值必须是以下之一：asc、desc。默认值为asc。 | +| `pattern` | `string` | | | 正则表达式，用于定义字段的值范围（字符串）。 | +| `max_length` | `integer` | | | 字符串值的最大长度。仅适用于字符串类型。 | +| `example` | `any` | | | 字段值的示例。值可以为空。 | +| `max_value` | `number` | | | 字段的最大值。值可以为空。仅适用于整数和浮点类型。 | +| `min_value` | `number` | | | 字段的最小值。值可以为空。仅适用于整数和浮点类型。 | +| `default_value` | `any` | | | 字段的默认值。值可以为空。 | +| `icon` | `string` | | | Field 在 UModel 系统中的图标。值格式为'url'。 | +| `uri` | `string` | | | 用于表示该字段唯一标识。 | +| `tags` | map<string, string> | | | 用于表示该 Field 的标签。 | +| `properties` | map<string, string> | | | 用于表示该 Field 的附加属性。 | + +## metric + +Metric 用于定义指标信息。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `name` | `string` | 是 | | 指标的名称。值不能为空。 | +| `display_name` | semantic_string (i18n) | | | 指标的显示名称。 | +| `description` | semantic_string (i18n) | | | 指标的描述。值格式为语义字符串。 | +| `short_description` | semantic_string (i18n) | | | 指标的简短描述。值格式为语义字符串。 | +| `launch_stage` | enum: `preview`, `beta`, `ga`, `deprecated` | | `preview` | 元素的发布阶段。默认值为 preview。 | +| `unit` | `string` | | | 指标的单位，值格式为字符串。 注意：单位仅用于展示，不会进行格式转换，例如 ms 不会自动根据大小转换为 s。 最佳实践：首先配置 data_format ，在大部分可观测场景下，data_format 即可满足需求，unit 填写为空即可。 若不满足需求，一般建议 data_format 配置通用的 KMB， 并配置 unit 为特定类型。比如温度，可以配置 data_format 为 KMB， 并配置 unit 为 °C。 | +| `data_format` | enum: `KMB`, `milli`, `byte`, `bit`, `byte_ies_sec`, `bit_ies_sec`, `iops`, `reqps` … (47 values) | | `KMB` | 指标的格式化方式，值格式为字符串。支持的格式化选项： 数值格式化： - KMB: 千、百万、十亿格式化，样例：K,Mil,Bil - milli: 处理为毫秒格式，样例：1,000,000 存储格式化： - byte: 处理为字节格式，样例：B/KB/MB - bit: 处理为位格式，样例：b/Kb/Mb 速率格式化： - byte_ies_sec: 每秒字节（byte per second）格式化，样例：B/s/KB/s/MB/… | +| `max_value` | `number` | | | 字段的最大值。值可以为空。仅适用于整数和浮点类型。 | +| `min_value` | `number` | | | 字段的最小值。值可以为空。仅适用于整数和浮点类型。 | +| `default_value` | `any` | | | 字段的默认值。值可以为空。 | +| `icon` | `string` | | | 用于表示该指标的图标。 | +| `labels` | array<[field_spec](shared-types#field_spec)> | | | 用于表示该指标自身额外的标签。即在 MetricSet 的标签基础上，该指标还具有的额外标签。 | +| `golden_metric` | `boolean` | | `false` | 是否为黄金指标。 | +| `generator` | `string` | | | 指标的生成方式，如果是 PromMode，该字段为 PromQL语句，能够执行并得到一个可直接使用的 Measure 类型指标。 例如：rate(request_count{}[1m])，在一些场景下结合 aggregator 字段，能够计算出聚合维度的指标，例如 sum(rate(request_count{}[1m])) by (label1, label2) 如果是 SQL/SPLMode，该字段为 SQL/SPL语句的计算… | +| `aggregator` | `string` | | | 指标的聚合方式。如果指标本身是聚合的，且聚合方式在多种维度组合下均一致，则不需要配置次字段，其他情况需要配置。一些示例场景如下： 1. Prometheus指标和Metric从时间线维度相同 1.1 rate(cpu_usage_seconds_total{}[1m]) 即可计算出单机指标，cpu_usage_seconds_total 代表主机级别的统计值，这时需要配置 Aggregator 为 avg 1.2 avg(rate… | +| `interval_us` | object | | | 指标的间隔，值格式为整数或整数数组，单位为微秒。 - 当为单个整数时：表示固定的采集间隔 - 当为整数数组时：表示多个采集间隔，用于支持不同精度的数据采集 | +| `type` | `string` | | `gauge` | 指标的类型。对于无需二次处理的指标，该字段应固定为 gauge。 | +| `query_mode` | enum: `range`, `instant`, `both` | | | 指标期望的查询模式。值必须是以下之一：range, instant, both。 | +| `display_type` | `string` | | | 指标的显示类型。当前未使用。 | +| `statistics` | array<string> | | | 生成该指标时的统计方式，即该指标有多种生成方式。当前仅在基础云监控场景下使用。 | +| `tags` | map<string, string> | | | 用于表示该指标的标签。 | +| `properties` | map<string, string> | | | 用于表示该指标的附加属性。 | +| `default_fill_policy` | `string` | | | 指标的默认填充策略。 值可以是 null, 0, last, next。 | + +## observation + +观察配置定义，用于定义现象观察和结论判断。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `name` | `string` | 是 | | 观察名称，在同一个RunbookSet中必须唯一。 | +| `display_name` | semantic_string (i18n) | 是 | | 观察显示名称。 | +| `short_description` | semantic_string (i18n) | 是 | | 观察简短描述。 | +| `description` | semantic_string (i18n) | | | 观察详细描述信息。 | +| `phenomenon` | object | 是 | | 现象定义，描述要观察什么以及如何观察。 | +| `phenomenon.phenomenon_type` | `string` | 是 | | 现象类型，如query（查询）、action（动作）、dashboard（大盘）、event（事件）等。 | +| `phenomenon.inputs` | array<object> | | | 现象相关输入配置，用于指引上层如何选择默认的参数进行填入。包括 Dashboard 变量、Query 输入参数等 | +| `phenomenon.outputs` | array<object> | | | 可选，现象相关输出配置，用于指引上层如何解析查询结果。 | +| `phenomenon.properties` | map<string, string> | | | 现象相关属性配置，根据 type 类型自由扩展。 | +| `conclusions` | array<object> | 是 | | 结论配置列表，根据现象观察结果进行判断。 | +| `conclusions.condition_type` | `string` | 是 | | 结论生效条件类型，根据现象类型，条件执行方式不同。可以是 query/action 执行结果后的 bool 表达式计算，也可以是由 LLM 进行判断的 prompts。 | +| `conclusions.condition` | `string` | 是 | | 结论生效条件，根据现象类型，条件执行方式不同。 | +| `conclusions.severity` | enum: `info`, `warning`, `error`, `fatal` | 是 | | 结论严重程度。 | +| `conclusions.display_name` | semantic_string (i18n) | 是 | | 结论显示名称。 | +| `conclusions.short_description` | semantic_string (i18n) | 是 | | 结论简短描述。 | +| `conclusions.description` | semantic_string (i18n) | | | 结论详细描述。 | +| `conclusions.group` | `string` | 是 | | 结论分组。在同一个结论分组下，只返回最高等级的结论。 | +| `conclusions.properties` | map<string, string> | | | 结论相关属性配置。 | +| `properties` | map<string, string> | | | 观察属性配置。 | +| `tags` | map<string, string> | | | 观察标签。 | + +## value_mapping + +ValueMapping 用于定义值的映射关系。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `name` | `string` | 是 | | 在 UModel 系统中的名称。值不能为空。值格式为小写字母数字字符。 | +| `display_name` | semantic_string (i18n) | | | 在 UModel 系统中的显示名称。值不能为空。 | +| `description` | semantic_string (i18n) | | | 在 UModel 系统中的描述。 | +| `short_description` | semantic_string (i18n) | | | 在 UModel 系统中的简短描述。 | diff --git a/tools/docs/gen_schema_reference.py b/tools/docs/gen_schema_reference.py new file mode 100644 index 0000000..9799f14 --- /dev/null +++ b/tools/docs/gen_schema_reference.py @@ -0,0 +1,424 @@ +#!/usr/bin/env python3 +"""Generate the UModel **Schema reference** (bilingual) from the source schemas. + +Source of truth: ``schemas/core/**/*.schema.yaml`` and ``schemas/includes/*.schema.yaml``. +Output: ``docs/{en,zh}/reference/schema/**`` Markdown (consumed by the VitePress site) +plus a sidebar fragment imported by the VitePress config. + +Organized per the UModel standard layering (see the contribution spec): the L0 Core +abstractions — **EntitySet / DataSet / Link / Storage** — with shared building blocks +(``metadata``, ``schema``, ``telemetry_data``, ``link``, ``field_spec``, ``metric`` …) +documented once on a shared-types page and referenced from each schema. + +These Markdown files are a GENERATED ARTIFACT. Do not hand-edit them; change the +schemas or this generator and re-run. + +Usage:: + + python3 tools/docs/gen_schema_reference.py # (re)generate + python3 tools/docs/gen_schema_reference.py --check # CI drift gate: non-zero exit if output would change +""" +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parents[2] +CORE = ROOT / "schemas" / "core" +INCLUDES = ROOT / "schemas" / "includes" +OUT = {lang: ROOT / "docs" / lang / "reference" / "schema" for lang in ("en", "zh")} +SIDEBAR = ROOT / "docs" / ".vitepress" / "config" / "schema-sidebar.json" + +LANGS = ("en", "zh") +LK = {"en": "en_us", "zh": "zh_cn"} + +# L0 Core abstraction categories. dir + the entity_set special-case. +CATEGORIES = [ + ("entity-set", {"en": "EntitySet", "zh": "EntitySet（实体集）"}), + ("dataset", {"en": "DataSet", "zh": "DataSet（数据集）"}), + ("link", {"en": "Link", "zh": "Link（链接）"}), + ("storage", {"en": "Storage", "zh": "Storage（存储）"}), +] + +# Shared includes documented once on the shared-types page (name -> heading). +SHARED_TYPES = [ + "metadata", + "schema", + "telemetry_data", + "link", + "field_spec", + "metric", + "observation", + "value_mapping", +] + +# Property names whose array items are a well-known shared type -> link instead of inline. +ARRAY_SHARED = {"fields": "field_spec", "labels": "field_spec", "metrics": "metric"} + +# UI strings. +T = { + "en": { + "title": "Schema Reference", + "kind": "Kind", + "field": "Field", + "type": "Type", + "required": "Required", + "default": "Default", + "description": "Description", + "envelope": "Every element shares the standard envelope", + "inherits": "Inherits", + "spec_fields": "`spec` fields", + "no_spec": "This element has no additional `spec` fields beyond the inherited base.", + "see_source": "see schema source", + "shared_intro": "Reusable building blocks referenced by the schemas above. Documented once here.", + "yes": "yes", + "values": "values", + }, + "zh": { + "title": "Schema 参考", + "kind": "Kind", + "field": "字段", + "type": "类型", + "required": "必填", + "default": "默认值", + "description": "说明", + "envelope": "每个元素共享标准信封", + "inherits": "继承", + "spec_fields": "`spec` 字段", + "no_spec": "除继承的基类外，该元素没有额外的 `spec` 字段。", + "see_source": "见 schema 源文件", + "shared_intro": "上述 schema 引用的可复用构建块，在此统一记录一次。", + "yes": "是", + "values": "个取值", + }, +} + + +def load(path: Path) -> dict: + with path.open(encoding="utf-8") as fh: + return yaml.safe_load(fh) or {} + + +def lang_text(desc, lang: str) -> str: + """Pull a bilingual description, sanitize internal links, collapse + truncate.""" + if not isinstance(desc, dict): + return "" + raw = desc.get(LK[lang]) or desc.get(LK["en" if lang == "zh" else "zh"]) or "" + if not isinstance(raw, str): + return "" + # Strip internal references that must not leak into public docs. + raw = re.sub(r"\s*(参考|See|see)\s*[:：]\s*https?://alidocs\.dingtalk\.com/\S*", "", raw) + raw = re.sub(r"https?://alidocs\.dingtalk\.com/\S*", "", raw) + raw = re.sub(r"\s+", " ", raw).strip() + if len(raw) > 220: + raw = raw[:217].rstrip() + "…" + return raw.replace("|", r"\|") + + +def first_version(schema: dict) -> dict: + versions = schema.get("versions") or [] + return versions[0] if versions else {} + + +def constraint_of(prop: dict) -> dict: + c = prop.get("constraint") + return c if isinstance(c, dict) else {} + + +def is_required(prop: dict) -> bool: + return bool(constraint_of(prop).get("required")) + + +def default_of(prop: dict) -> str: + c = constraint_of(prop) + if "default_value" in c and c["default_value"] is not None: + v = c["default_value"] + if isinstance(v, bool): + v = "true" if v else "false" + return f"`{v}`" + return "" + + +def type_str(prop: dict, link_prefix: str) -> str: + """Human-readable type, linking shared types where possible.""" + c = constraint_of(prop) + t = prop.get("type") + ref = prop.get("type_ref") + if ref: + name = ref.split(":")[0] + if name in SHARED_TYPES: + return f"[{name}]({link_prefix}shared-types#{name})" + return f"`{name}`" + # enum may be expressed as type: enum, or via constraint.enum on any type + enum = c.get("enum") if isinstance(c.get("enum"), dict) else None + if t == "enum" or enum: + vals = (enum or {}).get("values") or [] + shown = ", ".join(f"`{v}`" for v in vals[:8]) + if len(vals) > 8: + shown += f" … ({len(vals)} {T['en']['values']})" + return f"enum: {shown}" if shown else "enum" + if t == "array": + item = (c.get("array") or {}).get("item") or {} + iref = item.get("type_ref") + if iref: + name = iref.split(":")[0] + if name in SHARED_TYPES: + return f"array<[{name}]({link_prefix}shared-types#{name})>" + return f"array<{item.get('type', 'object')}>" + if t == "map": + m = c.get("map") or {} + kt = (m.get("key") or {}).get("type", "string") + vt = (m.get("value") or {}).get("type", "string") + return f"map<{kt}, {vt}>" + if t == "semantic_string": + return "semantic_string (i18n)" + if t == "object": + return "object" + return f"`{t}`" if t else "object" + + +def collect_rows(props: dict, lang: str, link_prefix: str, prefix: str = "", depth: int = 0): + """Flatten properties into table rows (depth-limited, shared structures linked).""" + rows = [] + if not isinstance(props, dict): + return rows + for name, prop in props.items(): + if not isinstance(prop, dict): + continue + path = f"{prefix}{name}" + # Collapse well-known arrays of shared types to a single linked row. + shared = ARRAY_SHARED.get(name) + if shared and prop.get("type") == "array": + tstr = f"array<[{shared}]({link_prefix}shared-types#{shared})>" + else: + tstr = type_str(prop, link_prefix) + req = T[lang]["yes"] if is_required(prop) else "" + rows.append((f"`{path}`", tstr, req, default_of(prop), lang_text(prop.get("description"), lang))) + # Recurse into nested objects (cap depth) unless collapsed to a shared link. + if shared and prop.get("type") == "array": + continue + if depth < 1: + sub = None + if prop.get("type") == "object" and isinstance(prop.get("properties"), dict): + sub = prop["properties"] + elif prop.get("type") == "array": + item = (constraint_of(prop).get("array") or {}).get("item") or {} + if isinstance(item.get("properties"), dict) and not item.get("type_ref"): + sub = item["properties"] + if sub: + rows.extend(collect_rows(sub, lang, link_prefix, prefix=f"{path}.", depth=depth + 1)) + return rows + + +def render_table(props: dict, lang: str, link_prefix: str) -> str: + rows = collect_rows(props, lang, link_prefix) + if not rows: + return "" + h = T[lang] + out = [f"| {h['field']} | {h['type']} | {h['required']} | {h['default']} | {h['description']} |", + "|---|---|---|---|---|"] + for f, t, r, d, desc in rows: + out.append(f"| {f} | {t} | {r} | {d} | {desc} |") + return "\n".join(out) + + +def extends_links(node: dict, lang: str, link_prefix: str) -> str: + refs = node.get("extends") or [] + parts = [] + for ref in refs: + name = ref.split(":")[0] + if name in SHARED_TYPES: + parts.append(f"[{name}]({link_prefix}shared-types#{name})") + else: + parts.append(f"`{name}`") + return ", ".join(parts) + + +def link_prefix_for(rel_path: str) -> str: + """Relative prefix from a page (path relative to schema root) back to schema root.""" + return "../" * rel_path.count("/") + + +def kind_value(spec_props: dict) -> str: + kind = spec_props.get("kind") or {} + vals = ((constraint_of(kind).get("enum")) or {}).get("values") or [] + return vals[0] if vals else "" + + +def render_schema_page(name: str, schema: dict, lang: str, rel_path: str) -> str: + h = T[lang] + lp = link_prefix_for(rel_path) + ver = first_version(schema) + spec_props = (ver.get("spec") or {}).get("properties") or {} + inner_spec = spec_props.get("spec") or {} + lines = [f"# {name}", ""] + desc = lang_text(schema.get("description"), lang) + if desc: + lines += [desc, ""] + kv = kind_value(spec_props) + if kv: + lines += [f"**{h['kind']}**: `{kv}`", ""] + lines += [f"> {h['envelope']} `kind` · [metadata]({lp}shared-types#metadata) · [schema]({lp}shared-types#schema).", ""] + inh = extends_links(inner_spec, lang, lp) + if inh: + lines += [f"**{h['inherits']}**: {inh}", ""] + lines += [f"## {h['spec_fields']}", ""] + table = render_table(inner_spec.get("properties") or {}, lang, lp) + lines += [table if table else f"_{h['no_spec']}_", ""] + return "\n".join(lines) + + +def render_shared_page(includes: dict, lang: str) -> str: + h = T[lang] + lines = [f"# {'Shared types' if lang == 'en' else '共享类型'}", "", h["shared_intro"], ""] + for name in SHARED_TYPES: + schema = includes.get(name) + if not schema: + continue + ver = first_version(schema) + props = (ver.get("spec") or {}).get("properties") or {} + lines += [f"## {name}", ""] + desc = lang_text(schema.get("description"), lang) + if desc: + lines += [desc, ""] + table = render_table(props, lang, "") + if table: + lines += [table, ""] + return "\n".join(lines) + + +def main() -> int: + ap = argparse.ArgumentParser() + ap.add_argument("--check", action="store_true", help="fail if generated output would change") + args = ap.parse_args() + + includes = {p.stem.replace(".schema", ""): load(p) for p in INCLUDES.glob("*.schema.yaml")} + core = {} + for p in CORE.rglob("*.schema.yaml"): + core[p.stem.replace(".schema", "")] = (p.relative_to(CORE).parts[0], load(p)) + + # category -> list of (name, schema) + cats = {key: [] for key, _ in CATEGORIES} + for name, (subdir, schema) in sorted(core.items()): + if name == "entity_set": + cats["entity-set"].append((name, schema)) + elif subdir == "dataset": + cats["dataset"].append((name, schema)) + elif subdir == "link": + cats["link"].append((name, schema)) + elif subdir == "storage": + cats["storage"].append((name, schema)) + + files: dict[str, str] = {} # rel path (no lang) -> content is per-lang; store per lang below + per_lang_files: dict[str, dict[str, str]] = {lang: {} for lang in LANGS} + sidebar = {lang: [] for lang in LANGS} + + for lang in LANGS: + # per-schema pages + for key, label in CATEGORIES: + items = cats[key] + if not items: + continue + sb_items = [] + for name, schema in items: + if key == "entity-set": + rel = f"core/{name.replace('_', '-')}.md" + else: + rel = f"core/{key}/{name.replace('_', '-')}.md" + per_lang_files[lang][rel] = render_schema_page(name, schema, lang, rel) + sb_items.append({"text": name, "link": f"/{lang}/reference/schema/{rel[:-3]}"}) + sidebar[lang].append({"text": label[lang], "collapsed": False, "items": sb_items}) + # shared types + per_lang_files[lang]["shared-types.md"] = render_shared_page(includes, lang) + sidebar[lang].append({ + "text": "Shared types" if lang == "en" else "共享类型", + "link": f"/{lang}/reference/schema/shared-types", + }) + # index + per_lang_files[lang]["index.md"] = render_index(cats, lang) + + import json + sidebar_json = json.dumps(sidebar, ensure_ascii=False, indent=2) + "\n" + + if args.check: + changed = [] + for lang in LANGS: + for rel, content in per_lang_files[lang].items(): + path = OUT[lang] / rel + if not path.exists() or path.read_text(encoding="utf-8") != content: + changed.append(str(path)) + if not SIDEBAR.exists() or SIDEBAR.read_text(encoding="utf-8") != sidebar_json: + changed.append(str(SIDEBAR)) + if changed: + print("Schema docs are stale; run `make docs-schema`. Changed:", file=sys.stderr) + for c in changed: + print(f" {c}", file=sys.stderr) + return 1 + print("Schema docs up to date.") + return 0 + + written = 0 + for lang in LANGS: + for rel, content in per_lang_files[lang].items(): + path = OUT[lang] / rel + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + written += 1 + SIDEBAR.write_text(sidebar_json, encoding="utf-8") + print(f"Generated {written} schema pages + sidebar for {len(LANGS)} locales.") + return 0 + + +def render_index(cats: dict, lang: str) -> str: + if lang == "en": + lines = [ + "# Schema Reference", "", + "UModel schemas are organized as a layered standard. This reference documents the " + "**L0 Core** abstractions — the base vocabulary every model is built from.", "", + "## Standard layers", "", + "| Layer | Name | Status |", "|---|---|---|", + "| **L0** | **UModel Core** — EntitySet, DataSet, Link, Storage | Documented below |", + "| L1 | Semantic Conventions — shared service/host/pod/database semantics | Roadmap |", + "| L2 | Domain Profiles — DevOps, APM, Kubernetes, AIOps, … | Roadmap |", + "| L3 | Conformance — automated standard-compliance checks | Roadmap |", "", + "See the contribution guide for how to propose L1–L3 content.", "", + "## L0 Core abstractions", "", + ] + cat_label = {"entity-set": "EntitySet", "dataset": "DataSet", "link": "Link", "storage": "Storage"} + else: + lines = [ + "# Schema 参考", "", + "UModel 的 schema 按分层标准组织。本参考记录 **L0 Core** 抽象——构建一切模型的基础词汇。", "", + "## 标准分层", "", + "| 层级 | 名称 | 状态 |", "|---|---|---|", + "| **L0** | **UModel Core** —— EntitySet、DataSet、Link、Storage | 见下文 |", + "| L1 | Semantic Conventions —— 通用 service/host/pod/database 语义 | 规划中 |", + "| L2 | Domain Profiles —— DevOps、APM、Kubernetes、AIOps…… | 规划中 |", + "| L3 | Conformance —— 自动化标准兼容性校验 | 规划中 |", "", + "L1–L3 的贡献方式见贡献指南。", "", + "## L0 Core 抽象", "", + ] + cat_label = {"entity-set": "EntitySet（实体集）", "dataset": "DataSet（数据集）", "link": "Link（链接）", "storage": "Storage（存储）"} + for key, _ in CATEGORIES: + items = cats[key] + if not items: + continue + lines += [f"### {cat_label[key]}", ""] + for name, _schema in items: + if key == "entity-set": + link = f"./core/{name.replace('_', '-')}" + else: + link = f"./core/{key}/{name.replace('_', '-')}" + lines.append(f"- [{name}]({link})") + lines.append("") + tail = "[Shared types](./shared-types)" if lang == "en" else "[共享类型](./shared-types)" + lines += [f"### {'Building blocks' if lang == 'en' else '构建块'}", "", f"- {tail}", ""] + return "\n".join(lines) + + +if __name__ == "__main__": + raise SystemExit(main())