实体类型配置说明¶

本文说明实体类型的三项配置：Data Schema、显示列、关联视图。

Data Schema：定义用户可附加的实体字段
显示列：定义实体列表中的默认展示列、默认隐藏列和固定列
关联视图：定义实体详情页中展示的日志、事件、链路、仪表板等关联视图

Data Schema¶

Data Schema 用于为实体类型补充自定义字段。系统会先加载官方基准 Schema，再叠加用户配置的附加字段。

官方基准 Schema¶

系统已为实体类型提供官方基准 Schema，用户可在前端界面查看具体的官方字段详情。

用户配置的 Data Schema 只需要声明附加字段，不需要重复声明官方已经定义好的顶层信息和基础字段。

不需要重复声明的内容包括：

类型	示例
顶层元数据	`kind`、顶层 `name`、`version`、`entity_type`
官方来源配置	`sources`
官方基础字段	`name`、`display_name`、`description`、`project`、`env`、`owner`、`lifecycle`、`tier`
官方关系字段	`component_of`、`depends_on`
官方通用扩展字段	`custom_tags`、`contact`、`link`

字段必须先在官方 Schema 或 custom_properties 中定义，才会成为有效实体字段。未定义字段即使出现在数据上报、显示列配置或关联视图变量中，也不会作为实体字段保存或展示，系统会忽略该字段。

基本结构¶

用户自定义字段统一写在 custom_properties 下。

custom_properties:
  - name: service_level_objective
    type: number
    description: "服务目标达成率"
    validation:
      min: 0
      max: 100

字段说明：

字段	说明
`custom_properties`	用户附加字段列表
`name`	自定义字段名，必须填写，不能与官方字段同名
`type`	字段类型
`description`	字段说明
`required`	字段是否必填
`validation`	字段校验规则
`mappings`	字段在不同来源 Payload 中的名称映射
`weight_overrides`	字段级来源权重覆盖

字段名冲突规则¶

自定义字段名不能与官方字段同名。

如果发生冲突：

官方字段始终保留；
自定义字段不生效；
用户需要修改自定义字段名后再保存。

例如，官方字段中已存在 env，则不要这样配置：

custom_properties:
  - name: env
    type: string

官方字段中已存在 contact 时，也不要尝试重新定义它的内部结构：

custom_properties:
  - name: contact
    type: array
    items:
      type: object

字段类型¶

类别	type	说明
基础标量	`string`	字符串，支持长度限制、正则匹配、空字符串过滤
基础标量	`integer`	整数，支持数值范围校验
基础标量	`number`	数字，支持浮点数和精度控制
基础标量	`boolean`	布尔值
集合容器	`array`	数组，必须定义 `items`
集合容器	`object`	对象，支持嵌套字段
语义约束	`enum`	枚举值，必须定义 `allowed_values`
语义约束	`urn`	系统内实体引用
语义约束	`datetime`	时间，使用 ISO 8601 格式
语义约束	`uri`	URL/URI 地址

配置示例¶

custom_properties:
  - name: service_level_objective
    type: number
    description: "服务目标达成率"
    validation:
      min: 0
      max: 100

  - name: endpoints
    type: array
    description: "服务访问端点"
    min_items: 1
    items:
      type: object
      required: [ip, port]
      properties:
        - name: ip
          type: string
          validation:
            pattern: "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$"

        - name: port
          type: number
          validation:
            min: 1
            max: 65535

        - name: protocol
          type: enum
          allowed_values:
            - http
            - https
            - tcp

配置建议¶

用户自定义字段只写在 custom_properties 下；
不要复制完整官方 DataSchema；
不要重复定义官方字段；
不在官方 Schema 或 custom_properties 中的字段，会被忽略，不会作为有效实体字段保存或展示；
array 类型必须定义 items；
enum 类型必须定义 allowed_values；
如果自定义字段需要必填，在字段级使用 required: true。

显示列¶

显示列用于配置实体列表中的列展示方式。

基本结构¶

table_columns:
  - name
  - entity_type

  - field: project
    fixed: true
    hidden: false

  - field: owner
    hidden: false

  - field: env
    hidden: true

  - field: business_owner
    fixed: false
    hidden: false

字段说明¶

字段	说明
`field`	列对应的字段名
`fixed`	是否为固定显示列，默认为 `false`
`hidden`	是否默认隐藏，默认为 `false`

配置规则¶

field 必须是实体中存在的字段，可以是官方字段，也可以是用户在 custom_properties 中新增的字段；未定义字段不会展示；
fixed: true 表示固定列。固定列始终展示，不出现在显示列启用/禁用清单中；
hidden: false 表示默认展示；
hidden: true 表示默认不展示，但用户可以在显示列配置中手动开启；
简写方式如 name、entity_type 等价于 field: name、field: entity_type，并默认展示。

不建议同时配置 fixed: true 和 hidden: true。如同时出现，应按固定列处理，即始终展示。

示例¶

table_columns:
  - field: name
    fixed: true

  - field: project

  - field: owner

  - field: env
    hidden: true

  - field: service_level_objective
    hidden: false

关联视图用于基于实体类型绑定详情页视图，例如日志、事件、链路、容器、Pod 和仪表板视图。查看实体详情时，系统会读取该实体类型绑定的视图并展示。

官方内置视图¶

系统可能会根据实体类型提供部分官方内置视图。用户可以手动关闭不需要展示的官方视图。

自定义关联视图¶

自定义关联视图写在 telemetrySelectors 下。

基本结构：

telemetrySelectors:
  - name: "错误日志"
    type: explorer
    viewName: logs
    query: "service='{{metadata.service}}'"

  - name: "指标"
    type: dashboard
    timerange: "30m"
    viewName: "服务概览"

字段说明¶

`name`¶

实体详情页中 Tab 展示的名称。

name: "错误日志"

`type`¶

关联视图类型，目前支持两类：

type	说明
`dashboard`	仪表板
`explorer`	查看器

`explorer` 类型配置¶

explorer 用于关联日志、事件、链路、容器、Pod 等查看器列表。

`viewName`¶

查看器类型，当前支持：

viewName	说明
`logs`	日志查看器
`event`	事件查看器
`trace`	链路查看器
`container`	容器查看器
`pod`	Pod 查看器

`query`¶

过滤条件，使用 DQL 查询语法。

支持通过变量引用当前实体属性：

{{metadata.field}}

例如：

query: "service='{{metadata.service}}'"

也可以写更复杂的条件：

query: "service='{{metadata.service}}' AND df_status NOT IN ['ok','info']"

query 中引用的 {{metadata.field}} 应来自已定义的实体字段；字段不存在或值为空时，查询条件可能无法匹配数据。

`explorer` 示例¶

- name: "错误日志"
  type: explorer
  viewName: logs
  query: "service='{{metadata.service}}' AND df_status NOT IN ['ok','info']"

- name: "事件"
  type: explorer
  viewName: event
  query: "service='{{metadata.service}}'"

`dashboard` 类型配置¶

dashboard 用于在详情页展示仪表板。

`timerange`¶

仪表板查询的时间范围。

timerange: "30m"
timerange: "1h"
timerange: "24h"

`keys` 和 `notinkeys`¶

当满足某个实体条件时才显示该仪表板。

# 当前实体的 database_type 值为 MySQL 时显示
keys: { database_type: "MySQL" }

# 当前实体存在 host 字段，且 database_type 值为 MySQL 时显示
keys: { host: "*", database_type: "MySQL" }

# 当前实体的 database_type 值不为 MySQL 时显示
notinkeys: { database_type: "MySQL" }

`viewName`¶

仪表板名称。

注意

必须填写可访问的仪表板名称；
名称需要与仪表板保持一致，否则无法正确打开；
若存在同名系统视图和用户视图，优先应用用户视图。

`dashboard` 示例¶

- name: "指标"
  type: dashboard
  timerange: "30m"
  viewName: "服务概览"

- name: "指标"
  type: dashboard
  keys: { database_type: "MySQL" }
  timerange: "1h"
  viewName: "基础设施 MySQL 监控视图"

完整示例¶

telemetrySelectors:
  - name: "错误日志"
    type: explorer
    viewName: logs
    query: "service='{{metadata.service}}' AND df_status NOT IN ['ok','info']"

  - name: "事件"
    type: explorer
    viewName: event
    query: "service='{{metadata.service}}'"

  - name: "服务概览"
    type: dashboard
    timerange: "30m"
    viewName: "服务概览"

  - name: "指标"
    type: dashboard
    keys: { database_type: "MySQL" }
    timerange: "1h"
    viewName: "基础设施 MySQL 监控视图"

  - name: "指标"
    type: dashboard
    keys: { database_type: "Oracle" }
    timerange: "1h"
    viewName: "基础设施 Oracle 监控视图"

配置建议¶

explorer.query 中引用的 {{metadata.field}} 必须是实体中真实存在的属性；
dashboard.viewName 必须指向可访问的仪表板；
keys 适合用于按实体属性值展示不同仪表板；
一个实体类型可配置多个关联视图，直接在 telemetrySelectors 下追加即可。

实体类型配置说明¶

Data Schema¶

官方基准 Schema¶

基本结构¶

字段名冲突规则¶

字段类型¶

配置示例¶

配置建议¶

显示列¶

基本结构¶

字段说明¶

配置规则¶

示例¶

关联视图¶

官方内置视图¶

自定义关联视图¶

字段说明¶

name¶

type¶

explorer 类型配置¶

viewName¶

query¶

explorer 示例¶

dashboard 类型配置¶

timerange¶

keys 和 notinkeys¶

viewName¶

dashboard 示例¶

完整示例¶

配置建议¶

文档内容是否对您有帮助？ ×

`name`¶

`type`¶

`explorer` 类型配置¶

`viewName`¶

`query`¶

`explorer` 示例¶

`dashboard` 类型配置¶

`timerange`¶

`keys` 和 `notinkeys`¶

`viewName`¶

`dashboard` 示例¶