Entity Type Management¶

This document explains how to customize entity types to extend the asset management capabilities of the unified catalog.

Navigate to Unified Catalog > Entity List, click the "Settings" icon on the left sidebar, and select "Manage Entity Types" to enter the entity type management page.

Create Entity Type¶

Click "Create Entity Type" in the upper right corner of the entity type management page.
Fill in the basic information:
- Entity Type: A globally unique identifier, e.g., kubernetes_deployment.
- Display Name: Enter the display name for the entity type.
- Description: Optionally add a description explaining the purpose of this type.
- Expand the "Advanced Configuration (Optional)" section to customize the Data Schema, display columns, and associated views via YAML.
- Click "Save" to complete the creation.

Note

Entity type identifiers must be unique. The system will prompt an error if a duplicate exists.
Before deleting a type, ensure no entities are associated with it; otherwise, deletion is not possible.

Advanced Configuration (Optional)¶

When creating or editing an entity type, the "Advanced Configuration (Optional)" section is displayed below the basic information. The system generates the following configuration based on a default template. You can use the default configuration directly or edit the YAML as needed.

Data Schema Configuration¶

Defines the fields, sources, required status, validation rules, etc., for the entity type. By default, a YAML preview is generated based on the system's default DataSchema template.

Official Entity Types: Use dataschema.yaml as the base, supporting the addition of custom_properties.
Custom Entity Types: Use the unified catalog's default template as the base, supporting custom fields, sources, required status, enumerations, default values, and validation rules.

Click to view Data Schema Configuration Instructions.

Default Display Column Configuration¶

Used to configure fixed columns, default columns, and optional columns in the entity list.

Configuration rules:

field: The field name.
fixed: Whether it is a fixed display column. Default is false. Fixed columns are always displayed and do not appear in the display column enable/disable list.
hidden: Whether it is hidden by default. Default is false. false means displayed by default, true means not displayed by default but can be enabled in the display column configuration.
Shorthand forms like name, entity_type are equivalent to field: name, field: entity_type and are displayed by default.
User's personal column preferences take precedence over the type's default configuration.

Click to view Default Display Column Configuration Instructions.

Configures the associated views on the entity details page.

For official configurations, you can enable or disable built-in associated views via YAML.
Supports adding custom associated views via YAML.
For log-associated views requiring a default index, configure it via the index field in the YAML. Use an array for multiple indices.

Configuration example:

telemetry:
  - name: { zh-CN: "错误日志", en-US: "Error Logs" }
    type: explorer
    viewName: logs
    index: ["app-prod", "gateway-prod"]
    query: "service='{{metadata.service}}' AND df_status NOT IN ['ok','info']"

Click to view Associated View Configuration Instructions.

Entity Type List¶

The entity type list page displays all entity types within the current workspace, including system-preset, official built-in, and custom types. The list shows each type's display name, entity type identifier, description, entity count, and classification tags.

Type Categories¶

Category	Included Types
System-preset	`system` (System)
Official built-in	Service, Host, Database, Queue, K8s Service, Deployment, etc.
Custom	User-created types (e.g., K8s resources, business domains, etc.)

Permission Restrictions

The system type supports editing and Health Configuration.
Other official built-in types only support editing.
Custom types support editing and deletion.

Health Configuration¶

Only the system type supports health configuration, used to uniformly set the default health calculation method for all entities of this system type.

Click "Health Configuration" in the row operation menu for the system type and choose one of the following two methods:

Method	Description
Enable Health Calculation	Toggle switch controls whether health calculation is enabled. When turned off, all entities under this system type will not calculate health, the catalog list will not show health status, and filtering by health is not supported.
Default Algorithm	Use the platform's built-in aggregation algorithm mentioned above to calculate health.
Custom Function	Call a Func platform function to calculate health. After selecting this, you need to specify a specific Func function.

Effective Rules

The configuration here serves as the default rule for this system type and applies to all system entities.
When creating or editing a specific system entity, you can choose to follow the default configuration or specify a custom function individually. Entities specified individually are not affected by changes to the configuration here.
If the custom function configured here is deleted or becomes unavailable, the health of entities following the default configuration will be displayed as "Unknown". Entities specified individually are not affected.

What is System Health¶

A system (system) is a user-built business aggregation entity representing a business system or platform collection (e.g., "Payment System", "Order System"). Since alerts/incidents are typically associated with its underlying entities (like services, hosts, databases) rather than the system itself directly, system health is calculated by aggregating the unresolved alert statuses of its constituent entities.

Simply put: System health reflects how well "the various parts that make up this system" are running overall.

Health Status Explanation¶

System health is divided into four statuses:

Status	Score Range	Meaning	Common Scenarios
Healthy	80–100	Constituent entities are running well overall, with no unresolved alerts.	All constituent entities have no active alerts.
Attention	60–79	Constituent entities have anomalies requiring attention.	Some entities have warning or error level alerts.
Critical	0–59	Constituent entities have severe anomalies, immediate action is recommended.	Core entities have fatal/critical alerts, or multiple entities are failing simultaneously.
Unknown	—	Health cannot be calculated temporarily.	The system currently has no constituent entities, or the initial calculation after system creation has not completed.

Default Algorithm Explanation¶

The default algorithm calculates based on the following three-step aggregation:

1. Determine Constituent Entities and Their Importance

System health is calculated based on its constituent entities (e.g., services, hosts, databases, etc.). Different entities have varying impact on the system:

Each entity has a base importance level. Entities with higher levels have a greater impact on system health.
You can also adjust the health impact weight for a specific constituent entity within the system, overriding the default level.
If an entity is set to "Exclude from calculation", its alerts do not affect system health.

2. Assess the Alert Impact of Individual Entities

When a constituent entity has unresolved alerts, the platform deducts points based on the alert severity:

Alert Severity	Impact on Entity
fatal / critical	Severe deduction
error	Moderate deduction
warning	Minor deduction
info / resolved	No deduction

When the same entity has multiple active alerts simultaneously, the platform takes the top 3 most impactful active faults, applying a diminishing coefficient (100% for the 1st, 50% for the 2nd, 25% for the 3rd). This avoids score distortion from a large number of low-level alerts while not underestimating the risk of concurrent multiple faults.

3. Weighted Calculation of System Total Score and Status Determination

The system score is calculated using a weighted average:

Multiply the alert deduction of each constituent entity by its importance weight.
Sum the weighted deductions of all constituent entities, then divide by the total weight.
Subtract the above weighted average deduction from 100 to get the final system score.

Status Determination:

Score Range	Status
80–100	Healthy
60–79	Attention
0–59	Critical

Custom Function¶

Customize Health Function via Func

Manage Associated Views¶

Click the icon on the right side of an entity row to enter the "Manage Associated Views" page. The page is divided into two areas: Built-in Associated Views and Custom Associated Views.

Built-in Associated Views¶

Associated views provided by the system by default, which can be enabled or disabled as needed.

If the current entity type has official built-in views, the page will list them automatically, defaulting to Enabled status.
Enable/Disable: Supports custom enabling or disabling the display of the current view.

Once disabled, the view will no longer be displayed on the Entity Details Page.

Custom Associated Views¶

Supports custom configuration of associated views according to the specified format.

After configuration, all entities of this type will display the corresponding tab on the details page, facilitating quick drill-down analysis.

Click to view Configuration Details.