UModel modeling principles

1.1 Domain design principle

Principle: A domain is the highest-level organizational unit in UModel. It represents a distinct business area or technology stack.

Core requirements:

• Judicious creation: Create domains only after thorough team discussion and evaluation to prevent creating arbitrary or duplicate domains.

• Align with business: Each domain must correspond to a clear business boundary or technical area.

• Assign governance responsibility: Assign a specific team to each domain to own the quality and consistency of all UModel resources within that domain.

Best practices:

# Example of recommended domain partitioning
domains:
  - name: apm           # Application performance monitoring
    owner: apm-team
    description: Entities and data related to applications, services, and instances
  
  - name: infra         # Infrastructure monitoring  
    owner: infra-team
    description: Infrastructure entities such as hosts, containers, and networks
  
  - name: acs           # Alibaba Cloud services
    owner: cloud-team
    description: Entities related to cloud products and resources

1.2 Generality principle

Principle: Define entities that are sufficiently generic and extensible to avoid over-specialization.

Core requirements:

• Use a moderate level of abstraction: Avoid definitions that are too abstract to be practical or too specific to be reusable.

• Build reusable patterns: Identify common characteristics among similar entities to establish reusable entity patterns.

• Design for use cases: Design entities based on actual use cases rather than the structure of the data source.

Design example:

# Well-designed for generality
entity_set:
  name: service
  description: Generic service entity suitable for various service types
  fields:
    - name: service_name        # General field.
    - name: service_type        # Supports different types: web, rpc, db, etc.
    - name: language           # Programing language.
    - name: framework          # Technology framework.

# Avoid over-specialization
# entity_set:
#   name: spring_boot_web_service  # Too specific

1.3 Single ingestion principle

Principle: Ingest each entity or dataset only once to prevent data redundancy and inconsistency caused by duplicate definitions.

Core requirements:

• Use a single data source: Each entity type must correspond to a single, authoritative data source.

• Avoid duplication: Do not define the same entity type in different domains.

• Establish a coordination mechanism: Create a cross-domain coordination mechanism to ensure the consistency of entity definitions.

2.1 Evaluate entity importance

Evaluation dimensions:

Decision matrix:

2.2 Evaluate entity quality

Quantity control standards:

• Total lifecycle volume: The total number of instances for a single entity type cannot exceed 10,000 over its lifecycle.

• Single instance scale: A single entity instance must contain no more than 100,000 records.

• Controllable growth: The growth in the number of entities must be predictable and controllable.

Schema quality requirements:

• Clear structure: Field definitions are clear with consistent types.

• Stable changes: The schema is changed infrequently and remains backward-compatible.

• Complete semantics: Provide complete field descriptions and usage examples.

2.3 Entity extraction cost

Cost evaluation dimensions:

Optimization recommendations:

• Prioritize entity definition schemes with low ETL costs.

• Establish automated entity discovery and maintenance mechanisms.

• Use batch processing and stream processing to optimize entity generation performance.

2.4 Semantic integrity

Naming conventions:

• Consistency: Use a unified naming pattern for similar concepts.

• Understandability: Use industry-standard terminology whenever possible.

• Precision: Use precise and unambiguous names to ensure semantic accuracy.

Semantic quality:

• Completeness: Every entity and field has a complete and clear bilingual description.

• Accuracy: Descriptions accurately reflect the actual functionality and data, with no ambiguity.

• Timeliness: Documentation is kept in sync with system implementations.

3.1 Standardize relationship types

Standard relationship types:

Relationship selection guide:

1. Prioritize standard relationships: Avoid creating custom relationship types whenever possible.

2. Ensure clear semantics: Choose the relationship type that most accurately expresses the business semantics.

3. Maintain consistent direction: Define a consistent direction for similar relationships.

4. Ensure cross-domain consistency: Keep relationship directions between different domains consistent, for example, by following a bottom-up or top-down principle.

3.2 Relationship direction principles

One-to-many principle:

• Hosting relationship: Host hosts Process (One host hosts multiple processes).

• Containment relationship: Cluster contains Node (One cluster contains multiple nodes).

• Calling relationship: Service A calls Service B (One service can call multiple services).

Directional uniformity:

• Maintain a consistent direction for the same type of relationship throughout the system.

• Establish a standard mapping table for relationship directions.

• Clearly document the directional semantics of relationships.

3.3 Describe EntitySetLinks accurately

Description requirements:

• Clarify primary and secondary roles: Clearly express the subject and object in the relationship.

• Define temporal order: For relationships with a time-based sequence, specify the order.

• Use the is_same relationship with caution: This relationship indicates entity equivalence and requires special care.

# Example of a good relationship description
kind: entity_set_link
schema:
  url: "umodel.aliyun.com"
  version: "v0.1.0"
metadata:
  name: "infra.host_hosts_apm.service"
  display_name:
    en_us: "Host hosts Service"
    zh_cn: 
  description:
    en_us: "Indicates that a host provides the runtime environment for services"
    zh_cn:
  domain: infra
spec:
  src:
    domain: infra
    kind: entity_set
    name: infra.host
  dest:
    domain: apm
    kind: entity_set
    name: apm.service
  entity_link_type: hosts

3.4 Cross-domain association principles

Cross-domain relationships are typically established through computational logic, such as matching fields like IP addresses, domain names, or hostnames. Cloud Monitor 2.0 built-in relationships provide automatic computation capabilities. If you manually configure cross-domain relationships, follow these principles:

• Requirement-driven responsibility: The business team with the primary requirement for the association is responsible for implementing its configuration logic.

• Optimize performance: Evaluate the impact of association computations on underlying storage and computing resources, and configure periodic computation frequencies accordingly.

• Ensure data quality: Verify the accuracy and timeliness of association data to prevent errors from inaccurate or outdated information.

• Maintain association flexibility: Choose a computing engine that supports both scheduled and real-time computation. The scheduled SQL functionality of SLS is recommended.

3.5 Control the number of associations

Quantity limit principles:

• Avoid Cartesian products: Prevent data explosion caused by relationship associations.

• Use a layered design: Control association complexity through a layered architecture.

• Build associations progressively: Establish core associations first, then gradually expand them.

3.6 Collaboration principles for association rules

Responsibility assignment principles:

• Business responsibility: The team that best understands the business logic is responsible for defining association rules.

• Technical responsibility: The platform team provides technical support for association computations.

• Quality responsibility: Establish a monitoring and feedback mechanism for association quality.

Collaboration mechanisms:

• Cross-domain associations require a joint review by the teams of the relevant domains.

• Establish an impact assessment mechanism for changes to associations.

• Periodically evaluate the validity and accuracy of associations.

4.1 Basic naming conventions

Field name format: [a-z][a-z0-9_]*

Naming principles:

• Start with a lowercase letter: All field names must start with a lowercase letter.

• Use snake_case: Use underscores to separate multiple words.

• Use clear semantics: Field names should clearly express their meaning.

• Use a moderate length: Avoid field names that are too long or too short.

Example:

# Correct field naming
fields:
  - name: service_name
  - name: cpu_usage
  - name: last_update_time 

# Incorrect field naming
# - name: ServiceName     # Camel case.
# - name: cpu-usage       # Use a hyphen.
# - name: 1st_metric      # Start with a number.

4.2 EntitySet naming conventions

Format: {domain}.{name}

Naming principles:

• Require a domain prefix: All names must start with a domain prefix to ensure global uniqueness.

• Keep the name concise: The name part should be concise, clear, and avoid redundancy.

• Use clear semantics: The name should accurately reflect the business meaning of the entity.

Example:

# Correct EntitySet naming
entity_sets:
  - name: apm.service          # Service entity in the application performance monitoring domain.
  - name: infra.host          # Host entity in the infrastructure domain.
  - name: acs.ecs.instance    # Alibaba Cloud Elastic Compute Service (ECS) instance.

# Incorrect EntitySet naming  
# - name: service            # Missing domain prefix.
# - name: apm_service_entity # Redundant entity suffix.

4.3 DataSet naming conventions

Format: {domain}.{DataSetShortType}.{name}

DataSetShortType values:

• metric - Metric dataset.

• trace - Tracing analysis dataset.

• log - Log dataset.

• event - Event dataset.

• profile - Performance profiling dataset.

Example:

# Correct DataSet naming
data_sets:
  - name: apm.metric.jvm           # JVM metrics in the application performance monitoring domain.
  - name: apm.trace.http_request   # HTTP request traces in the application performance monitoring domain.
  - name: infra.metric.system      # Infrastructure system metrics.
  - name: acs.log.access          # Alibaba Cloud access logs.

# Incorrect DataSet naming
# - name: apm.jvm_metric         # Missing DataSetShortType.
# - name: metric.apm.jvm         # Incorrect order.

4.4 Link naming conventions

Format: {src_object_name}_{LinkType}_{dest_object_name}

Naming principles:

• Clarify the relationship: The link name should clearly express the relationship type.

• Maintain a consistent direction: Source entity first, destination entity second.

• Use standard types: Use standard relationship type names.

Example:

# Correct Link naming
entity_set_links:
  - name: apm.service_calls_apm.service          # Service call relationship.
  - name: apm.service_contains_apm.operation     # The service contains operations.
  - name: infra.server_host_apm.instance         # The server hosts application performance monitoring instances.

# Incorrect Link naming
# - name: service_link                          # Unclear relationship.
# - name: calls_service_service                 # Missing domain prefix.

4.5 Required fields conventions

Internationalization requirement: All user-facing text fields must be provided bilingually, for example, Chinese and English.

Required metadata:

# Example of required internationalization fields
display_name:
  en_us: "Service Name"
  zh_cn: 
  
description:
  en_us: "The unique identifier of the service"
  zh_cn: 
  
short_description:
  en_us: "Service ID"  
  zh_cn: 

Quality requirements:

• Accurate translation: The English and Chinese descriptions must correspond accurately.

• Consistent terminology: Use a unified glossary of terms.

• Correct grammar: Ensure correct grammar and spelling.

• Clear spacing: Ensure proper spacing between characters of different languages (for example, Chinese and English) for readability.

4.6 Handle special cases

Exemption mechanism: For special formats already defined in existing systems, an exemption can be requested using the @exempt annotation.

• This exemption mechanism applies only to the CommonSchema specification review within the Cloud Monitor team. For your enterprise modeling, adapt it to your specific governance standards.

Use cases:

• The native field format of a cloud product does not conform to the specification.

• Field names from a third-party system integration.

• Compatibility requirements for legacy systems.

Exemption example:

fields:
  - name: StatusCode  # @exempt The field in the cloud product is defined in this format.
    description:
      en_us: "HTTP status code from cloud product API"
      zh_cn: 
    exempt_reason: "Native field format from the Alibaba Cloud ECS API"

Approval requirements:

• Provide a detailed reason for the exemption.

• Evaluate the impact on system consistency.

• Periodically review the necessity of the exemption.