Entity Type Configuration Guide¶

This document explains the three configurations for entity types: Data Schema, Display Columns, and Related Views.

• Data Schema: Defines additional fields that users can attach to entities.
• Display Columns: Defines the default displayed columns, default hidden columns, and fixed columns in the entity list.
• Related Views: Defines associated views such as logs, events, traces, and dashboards displayed on the entity detail page.

Data Schema¶

Data Schema is used to supplement custom fields for entity types. The system first loads the official baseline Schema, then overlays the additional fields configured by the user.

Official Baseline Schema¶

The system provides an official baseline Schema for entity types. Users can view the specific official field details in the frontend interface.

The Data Schema configured by users only needs to declare additional fields; there is no need to redeclare the top-level information and basic fields already defined by the official Schema.

Content that does not need to be redeclared includes:

A field must first be defined in the official Schema or custom_properties to become a valid entity field. Undefined fields, even if they appear in data reporting, display column configuration, or related view variables, will not be saved or displayed as entity fields; the system will ignore such fields.

Basic Structure¶

User-defined fields are uniformly written under custom_properties.

custom_properties:
  - name: service_level_objective
    type: number
    description: "Service Level Objective achievement rate"
    validation:
      min: 0
      max: 100

Field descriptions:

Field Name Conflict Rules¶

Custom field names cannot be the same as official field names.

If a conflict occurs: - The official field is always retained. - The custom field does not take effect. - The user needs to modify the custom field name before saving.

For example, if the official field env already exists, do not configure like this:

custom_properties:
  - name: env
    type: string

When the official field contact already exists, do not attempt to redefine its internal structure:

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

Field Types¶

Configuration Example¶

custom_properties:
  - name: service_level_objective
    type: number
    description: "Service Level Objective achievement rate"
    validation:
      min: 0
      max: 100

  - name: endpoints
    type: array
    description: "Service access endpoints"
    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

Configuration Recommendations¶

• Write user-defined fields only under custom_properties.
• Do not copy the complete official DataSchema.
• Do not redefine official fields.
• Fields not in the official Schema or custom_properties will be ignored and will not be saved or displayed as valid entity fields.
• The array type must define items.
• The enum type must define allowed_values.
• If a custom field needs to be required, use required: true at the field level.

Display Columns¶

Display columns are used to configure how columns are displayed in the entity list.

Basic Structure¶

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 Descriptions¶

Configuration Rules¶

• field must be a field that exists in the entity. It can be an official field or a field newly added by the user in custom_properties. Undefined fields will not be displayed.
• fixed: true indicates a fixed column. Fixed columns are always displayed and do not appear in the display column enable/disable list.
• hidden: false indicates display by default.
• hidden: true indicates not displayed by default, but users can manually enable it in the display column configuration.
• Shorthand forms like name, entity_type are equivalent to field: name, field: entity_type and are displayed by default.

It is not recommended to configure both fixed: true and hidden: true simultaneously. If both appear, it should be treated as a fixed column, meaning it is always displayed.

Example¶

table_columns:
  - field: name
    fixed: true

  - field: project

  - field: owner

  - field: env
    hidden: true

  - field: service_level_objective
    hidden: false

Related Views¶

Related Views are used to bind detail page views based on entity types, such as logs, events, traces, containers, Pods, and dashboard views. When viewing entity details, the system reads and displays the views bound to that entity type.

Official Built-in Views¶

The system may provide some official built-in views based on the entity type. Users can manually turn off official views they do not need to display.

Custom Related Views¶

Custom related views are written under telemetrySelectors.

Basic structure:

telemetrySelectors:
  - name: "Error Logs"
    type: explorer
    viewName: logs
    query: "service='{{metadata.service}}'"

  - name: "Metrics"
    type: dashboard
    timerange: "30m"
    viewName: "Service Overview"

Field Descriptions¶

name¶

The name displayed on the Tab in the entity detail page.

name: "Error Logs"

type¶

The type of related view. Currently, two types are supported:

explorer Type Configuration¶

explorer is used to associate explorer lists such as logs, events, traces, containers, and Pods.

viewName¶

Explorer type. Currently supported:

query¶

Filter conditions, using DQL query syntax.

Supports referencing current entity attributes via variables:

{{metadata.field}}

For example:

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

More complex conditions can also be written:

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

The {{metadata.field}} referenced in query should come from defined entity fields. If the field does not exist or its value is empty, the query condition may fail to match data.

explorer Example¶

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

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

dashboard Type Configuration¶

dashboard is used to display dashboards on the detail page.

timerange¶

The time range for the dashboard query.

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

keys and notinkeys¶

Display the dashboard only when certain entity conditions are met.

# Display when the current entity's database_type value is MySQL
keys: { database_type: "MySQL" }

# Display when the current entity has a host field and the database_type value is MySQL
keys: { host: "*", database_type: "MySQL" }

# Display when the current entity's database_type value is not MySQL
notinkeys: { database_type: "MySQL" }

viewName¶

Dashboard name.

dashboard Example¶

- name: "Metrics"
  type: dashboard
  timerange: "30m"
  viewName: "Service Overview"

- name: "Metrics"
  type: dashboard
  keys: { database_type: "MySQL" }
  timerange: "1h"
  viewName: "Infrastructure MySQL Monitoring View"

Complete Example¶

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

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

  - name: "Service Overview"
    type: dashboard
    timerange: "30m"
    viewName: "Service Overview"

  - name: "Metrics"
    type: dashboard
    keys: { database_type: "MySQL" }
    timerange: "1h"
    viewName: "Infrastructure MySQL Monitoring View"

  - name: "Metrics"
    type: dashboard
    keys: { database_type: "Oracle" }
    timerange: "1h"
    viewName: "Infrastructure Oracle Monitoring View"

Configuration Recommendations¶

• The {{metadata.field}} referenced in explorer.query must be a real attribute that exists in the entity.
• dashboard.viewName must point to an accessible dashboard.
• keys is suitable for displaying different dashboards based on entity attribute values.
• Multiple related views can be configured for one entity type; simply append them under telemetrySelectors.