Phase 2 Object mode - Service discovery - Cloud Monitor - Alibaba Cloud Documentation Center

1. Overview of Object mode

Object Mode provides an abstract way to access entities (EntitySet). It lets you use a unified Structured Process Language (SPL) interface to call entity methods and retrieve various observability data and metadata related to the entities. Compared to directly accessing datasets in Phase 1 (Table Mode), Object Mode has the following features:

Object-oriented: Organizes capabilities around an EntitySet. This approach provides clear semantics that align with business objects.
Dynamic capabilities: Discovers and calls methods supported by an entity at runtime, which is similar to reflection.
Automatic mapping: Automatically applies DataLink and StorageLink field mappings and filter conditions.
Relational semantics: Natively supports accessing relational data between entities.

Basic syntax:

.entity_set with(domain='domain_name', name='entity_name', [ids|query|other_parameters])
| entity-call method_name(parameters...)

General parameters:

Parameter	Type	Required	Description	Example
domain	string	Yes	The domain to which the EntitySet belongs.	‘apm’
name	string	Yes	The name of the EntitySet.	‘apm.service’
ids	array	No	A list of entity IDs.	[‘id1’,‘id2’]
query	string	No	A filter condition. For more information, see SPL syntax.	‘service_id = “xxx”’

Scenarios:

Observe and analyze data based on business entities, such as services, interfaces, and hosts.
Automatically handle field mappings and filter conditions to reduce the complexity of calls.
Reuse unified method semantics across different entities and relationships.

Comparison with Table Mode:

Table Mode: Directly access MetricSet/LogSet/.... This mode offers finer control but requires knowledge of the underlying details.
Object Mode: Centers on entities where methods represent capabilities. This mode provides a higher level of abstraction and composability.

2. Dynamic capability discovery (runtime method reflection)

The core of Object Mode is dynamic capability discovery. You can use the built-in __list_method__ method to enumerate all methods that the current EntitySet supports at runtime, along with descriptions of their parameter and return value structures. You can then call these methods adaptively as needed.

2.1 List available methods

.entity_set with(domain='apm', name='apm.service')
| entity-call __list_method__()

Returned fields:

Field	Description	Example
name	The internal name of the method used for calls.	`get_entity_set`
display_name	The display name of the method.	`Get Current EntitySet`
description	A description of the method's function.	`Return the current EntitySet definition`
params	The parameter schema in a JSON array.	`[{"key":"dest_entity_set_domain","type":"varchar","display_name":"Destination Entity Domain (empty for all domains)","description":"","required":false}, {...}]`
returns	The return value schema in a JSON array.	`[{"key":"entity_set_id","type":"varchar","display_name":"EntitySet id, the format is domain@entity_set@name","description":""},{...}]`

Example method list (excerpt):

name	display_name	description
`__list_method__`	List Available Methods	Gets the available methods for the current EntitySet.
`__inspect__`	Configuration Inspector	Checks the integrity and validity of the UModel configuration.
list_data_set	List DataSets	Lists the datasets associated with the current entity.
list_related_entity_set	List Related EntitySets	Lists other entities related to the current entity.
get_golden_metrics	Get Golden Metrics	Gets the golden metrics data for the entity.
get_metric	Get Metric	Gets the metric data from the associated MetricSet.
get_label_values	Get Label Values	Gets the tag values from the associated MetricSet.
get_log	Get Log	Gets the log data from the associated LogSet.
get_profile	Get Profile	Gets the performance profiling data from the associated ProfileSet.

Note: The return value of __list_method__ changes based on the datasets and relationships that are associated with the entity. This dynamic behavior enables its adaptive discovery capability.

2.2 Read method metadata and call adaptively

Typical flow:

Discover capabilities.

.entity_set with(domain='apm', name='apm.service')
| entity-call __list_method__()

Filter and select the target method, such as get_golden_metrics.
Adaptively assemble parameters and call the method.

.entity_set with(domain='apm', name='apm.service', query='service_id = "order-service"')
| entity-call get_golden_metrics('range', '1m')

Another example is to adaptively access the list of datasets associated with an entity and select a method:

.entity_set with(domain='apm', name='apm.service')
| entity-call list_data_set(['metric_set'], true)

Based on the returned data_set_id and fields_mapping, the upper layer can automatically assemble the parameters and query filter conditions for get_metric.

3. Standard flow for capability discovery and calls

Specify the entity context: domain and name, with optional ids or query.
Enumerate available methods: __list_method__().
Read the method signature, which includes params and returns (JSON description).
Select a method and prepare parameters. If necessary, use list_data_set and list_related_entity_set.
Execute the entity-call to retrieve data or an SPL statement. In DryRun mode, the call returns an SPL statement.

Note:

If an entity is not associated with any dataset or relationship, only basic methods are returned, such as __list_method__ and __inspect__.
The availability and parameter requirements of methods change based on the DataSet or Link associated with the entity.

4. Typical usage examples

4.1 Discover available methods for an entity

.entity_set with(domain='apm', name='apm.service')
| entity-call __list_method__()

4.2 Get golden metrics (based on discovery results)

.entity_set with(domain='apm', name='apm.service', query='service_id = "order-service"')
| entity-call get_golden_metrics('range', '1m')

4.3 Query associated datasets and continue calls

.entity_set with(domain='apm', name='apm.service')
| entity-call list_data_set(['metric_set'], true)

Based on the return value:

Field	Description
data_set_id	The unique identifier of the associated dataset, such as `apm@metric_set@apm.metric.apm.service`.
type	The type of dataset, such as `metric_set`.
fields_mapping	The field mapping, which guides the automatic assembly of parameters and filter conditions.

You can then proceed as follows:

.entity_set with(domain='apm', name='apm.service', query='service_id = "order-service"')
| entity-call get_metric('apm', 'apm.metric.apm.service', 'request_count', 'range', '1m')

5. Best practices

Discover first, then call: First, use __list_method__() to determine the capabilities that an entity supports in the current context. Then, call the methods as needed.
Combine list_data_set and list_related_entity_set to automate the construction of parameters and filter conditions.
Use DryRun for debugging:

.set "umodel_paas_mode"='dry_run';

.entity_set with(domain='apm', name='apm.service')
| entity-call get_metric('apm', 'apm.metric.apm.service', 'request_count')

DryRun returns an executable SPL statement. This makes it easy to review whether the field mapping and query generation meet your expectations.

Cache the method list: The method list is relatively stable. You can cache it on the application side for a short period to improve performance.