Generate and write entity relationships-Cloud Monitor(CMS)-阿里云帮助中心

Overview

In UModel, an entity relationship describes the connections and dependencies between different entities, such as service invocations and host containment. This topic covers the data format, write methods, and best practices for entity relationships.

Note

For more information about UModel, EntitySetLink, and EntityRelations, see Introduction to EntityStore.

Relationship data format

Entity relationship data is written to the ${workspace}__topo Logstore in EntityStore using the SLS Log protocol. Each relationship record describes a directed connection between two entities.

System fields

Field name	Type	Required	Example	Description
`__src_domain__`	string	Yes	apm, k8s	The domain of the source entity.
`__src_entity_type__`	string	Yes	apm.service	The type of the source entity.
`__src_entity_id__`	string	Yes	391274C9A1D369FB5222E273D02B81B8	The unique identifier of the source entity.
`__dest_domain__`	string	Yes	apm, k8s	The domain of the destination entity.
`__dest_entity_type__`	string	Yes	apm.host	The type of the destination entity.
`__dest_entity_id__`	string	Yes	D91192729ED1688E9096E98801A5D7CA	The unique identifier of the destination entity.
`__relation_type__`	string	Yes	runs_on, calls, contains	The relationship type, which defines the business meaning of the connection.
`__method__`	string	No (Default: Update)	Update, Expire	The operation type, which controls the lifecycle of the relationship.
`__first_observed_time__`	int	No	1700000000	The UNIX timestamp (in seconds) of the first observation.
`__last_observed_time__`	int	No (Default: LogTime)	1700000001	The UNIX timestamp (in seconds) of the last observation.
`__keep_alive_seconds__`	int	No (Default: 3600)	3600	The time to live (TTL), in seconds.

Note

Currently, entity relationship data does not support storing information on edges. To store edge data, use DataLink to connect to a DataSet.

Field descriptions

Entity identifiers

Source entity: Uniquely identified by __src_domain__, __src_entity_type__, and __src_entity_id__.
Destination entity: Uniquely identified by __dest_domain__, __dest_entity_type__, and __dest_entity_id__.
Entity ID format: Same as for entity writes. Supports 128-bit hex values or automatic conversion.

Relationship directionality

Relationships are directional, pointing from a source entity to a destination entity.

A --calls--> B: A calls B.
A --runs_on--> B: A runs on B.
A --contains--> B: A contains B.

Time fields

For more information, see Generate and write entities.

Relationship write method

For more information, see Generate and write entities.

Relationship time ranges and query overwrite mechanism

For more information, see Generate and write entities.

Common relationship types

Note

UModel does not enforce limits on relationship types. You can define them as needed.

Relationship type	Meaning	Application scenario
`calls`	Call	Service invocation
`runs_on`	Running	Process running relationship
`contains`	Contains	Parent-child containment
`manages`	Manages	Administrative control
`serves`	Service	Service provisioning
`hosted_by`	Hosted by	Deployment relationship
`related_to`	Related to	General association

Note

Relationship types must be consistent with the relationship types in EntitySetLink.

Best practices for writing relationships

1. Relationship discovery policies

Discovery based on monitoring data

APM trace data: Extract service-to-service invocation relationships from call chains.
Network traffic data: Discover communication relationships from network monitoring.
Resource monitoring data: Discover running relationships from host and container monitoring.

Discovery based on configuration data

K8s configurations: Extract relationships from pod, service, and deployment configurations.
Cloud resource configurations: Discover relationships from VPC, security group, and Server Load Balancer configurations.
Application configurations: Discover dependencies from application configuration files.

2. Time window management

Note

Adjust the KeepAlive time based on the reporting interval. Set the KeepAlive time to at least one reporting interval, and set the reporting interval to at least 5 minutes to prevent frequent updates from affecting query performance.

Short-term relationships (invocation relationships)

KeepAlive time: 10 to 30 minutes.
Applicable to: Dynamic relationships, such as service invocations and API requests.
Update frequency: 1 to 5 minutes.

Medium-term relationships (deployment relationships)

KeepAlive time: 1 to 4 hours.
Applicable to: Semi-static relationships, such as application deployments and container operations.
Update frequency: 10 to 30 minutes.

Long-term relationships (infrastructure relationships)

KeepAlive time: 4 to 24 hours.
Applicable to: Static relationships, such as network connectivity and storage mounts.
Update frequency: 1 to 6 hours.

3. Relationship lifecycle management

Use an incremental and full synchronization policy:

Incremental updates: Update active relationships in real time or near real time.
Full synchronization: Perform full synchronizations periodically to ensure data integrity.
Expiration cleanup: Automatically clean up expired relationships using the KeepAlive mechanism.

4. Cross-domain relationship design principles

Define clear boundaries: Clearly define the scope of responsibility for different domains.
Standardize types: Unify the naming conventions for cross-domain relationship types.
Avoid loops: Prevent cross-domain relationships from forming circular dependencies.
Consider performance: Cross-domain queries can affect performance. Design query paths carefully.

Considerations

1. Relationship consistency

Ensure that the entities at both ends of a relationship actually exist.
Periodically check for and clean up dangling relationships, which are relationships that persist after their associated entities have been deleted.

2. Performance optimization

Limit the number of relationships to maintain query performance. A single relationship type should not exceed 100,000 relationships, and the total should not exceed 1,000,000.
Set a reasonable KeepAlive time to avoid accumulating invalid relationships.
Control the write frequency for relationship data to avoid excessive updates.

3. Data quality

Verify that relationship types are logical. For example, a `Pod calls Service` relationship should not exist.
Ensure that the direction of relationships is correct.
Periodically review the accuracy of relationship data.