前文回顾：
《基于 UModel 高效构建可观测场景统一实体搜索引擎》
《构建数据资产“导航地图”：详解 UModel 数据发现与全链路分析能力》
《打通可观测性的“任督二脉”：实体与关系的终极融合》
背景
基于 UModel 构建的可观测系统，访问可观测数据需要上层应用感知 EntitySet、DataSet、Storage、Filter 等多个概念，给 UI、算法、客户等使用方带来了较高的开发和维护成本。
典型场景：查询 APM 服务的请求量指标
假设上层应用需要实现查询某个 APM 服务的请求量指标，开发者需要经历以下步骤：
开发者需要了解的知识
- 实体关联：服务实体关联哪个 MetricSet？
- 存储路由：MetricSet 使用哪个 MetricStore？Region/Project/存储名称是什么？
- 字段映射：Entity 的 service_id 对应存储的哪个字段（如 acs_arms_service_id）？
- 查询语法：如何编写 PromQL 表达式 rate(arms_app_requests_count_raw{...}[1m])？
- SPL 拼接：如何组装成完整的查询语句？
完整的开发步骤
Step 1: 查询 UModel 元数据
Step 2: 解析 MetricSet 配置↓ 找到 service EntitySet 关联的 MetricSet ↓ 如果 DataLink 中包含 FilterByEntity，还需根据实体数据过滤
Step 3: 查看字段映射↓ 根据 StorageLink 获取底层 MetricStore 连接信息 ↓ 获取 Region/Project/MetricStore 名称
Step 4: 构造 PromQL 表达式↓ 从 DataLink 中获取字段映射表 ↓ 确认 service_id → acs_arms_service_id
Step 5: 拼接并执行查询↓ 根据指标定义拼接查询表达式 ↓ 处理聚合规则、时间窗口
最终查询语句示例：↓ 使用正确的 label 和 MetricStore ↓ 拼接完整的 SPL 语句并执行
.metricstore with(region='cn-hangzhou', project='cms-xxx', metricstore='metricstore-apm')
|prom-call promql_query_range('sum by (acs_arms_service_id) (rate(arms_app_requests_count_raw{acs_arms_service_id="xxx"}[1m]))','1m')
痛点
痛点 1：概念复杂，学习门槛高
问题描述：
• 开发者必须深入理解 UModel 架构：EntitySet、DataSet、DataLink、StorageLink、Filter 等多个概念
• 需要了解 DataSet 与 Storage 的关联关系、Filter 路由逻辑、字段映射规则
• 新人上手困难，老手也容易遗漏细节
影响：开发效率低，维护成本高
痛点 2：复杂场景实现困难
问题描述：
• 存储路由查找：需要理解多个 MetricSet 之间的选择逻辑
• 字段映射处理：Entity 字段 → 存储字段的映射规则复杂
• 过滤条件筛选：FilterByEntity 规则匹配逻辑难以掌握
• 多次查询拼接：需要多次查询元数据，再构建数据查询
影响：增加代码复杂度，出错概率高
痛点 3：底层存储语法逃不掉
问题描述：
• MetricSet 可能由 MetricStore 或 LogStore 实现，查询方式完全不同（PromQL vs SPL）
• 不同存储提供商（ARMS MetricStore、Aliyun Prometheus）语法有差异
• 开发者仍需精通底层查询语言
影响：同样的需求需要编写不同的代码，无法统一
痛点 4：多次查询交互，效率低
问题描述：
• 先查询 UModel Meta 获取配置 → 再根据 Meta 查询数据
• 需要自己处理数据拼接和关联
• 每个使用方都要实现类似逻辑，代码重复度高
影响：集成成本高，查询延迟大，出错概率增加
目标与架构
设计目标
针对上述四大痛点，UModel PaaS API 的设计目标是屏蔽底层复杂性，统一访问接口，使上层应用更加专注业务逻辑实现：
核心设计原则
• 自动化处理：自动路由、字段映射、查询转换
• 统一 SPL 语法：所有数据类型使用一致接口
• 面向对象编程：实体方法调用、关系导航
• AI 友好：反射能力，支持 AI Agent 自主探索
设计理念：两层抽象
访问 UModel 数据时，需要单独通过 SPL 去访问指标、日志、链路等各种数据，每种数据都有不同的访问方式，没有统一的抽象。
UModel PaaS API 采用两层抽象的设计思路：
第一层抽象：Table 模式（表格化抽象）
将所有数据——指标、日志、链路、性能剖析——统一抽象成表格结构，所有查询都是针对表格数据进行操作。
价值：统一了查询语言，开发者不需要关心底层是 PromQL 还是 SLS SPL，都用同一套 SPL 语法。
第二层抽象：Object 模式（对象级抽象）
表格模式解决了数据访问的统一性，但还不够。我们还需要以实体为中心的抽象。
传统方式：查询一个服务的指标，需要知道这个服务关联哪个 MetricSet、字段如何映射、过滤条件怎么写…
Object 模式：只需要说“这个服务，给我它的指标”，系统自动处理字段映射、过滤条件、存储路由。
价值：面向对象的思想，把实体当成对象，把查询当成方法调用：service.get_metric()。
第三层能力：元数据查询（反射能力）
提供动态能力发现、配置验证等高级功能，让 AI Agent 可以自主探索、自主决策。
价值：AI Agent 能够通过反射能力动态发现实体的能力边界，实现真正的智能运维。
架构分层 - 存储层统一：EntityStore/LogStore/MetricStore → SPL
自动完成存储路由、字段映射（service_id → acs_arms_service_id）、过滤、查询语法的转换。上层应用对存储切换无感知。 - 数据层统一：Table 模式
直接访问 DataSet，声明式查询，支持完整 SPL Pipeline。
.metric_set with(domain='apm', name='service.request', query=service_id='xxxx') | stats avg(latency)
.log_set with(domain='apm', name='service.error_log' query=service_id='xxx') | where level="ERROR" - 对象层统一：Object 模式
以实体为中心，自动处理底层细节，支持动态能力发现和配置检查。数据访问
.entity_set with(domain='apm', name='apm.service', ids=['404e5d6be468f6dfaeef37a014322423'])
| entity-call get_metric('apm', 'apm.metric.apm.service', 'avg_request_latency_seconds', 'range', '', false)能力发现（Agent 自主决策的关键）
.entity_set with(domain='apm', name='service') | entity-call list_method()配置检查
.entity_set with(domain='apm', name='service') | entity-call inspect()
API 说明
UModel PaaS API 提供三大核心能力，满足不同场景的查询需求： - Table 模式 - 直接访问数据集，适合批量数据分析
- Object 模式 - 以实体为中心，适合实体详情查询和关系分析
- 元数据查询 - 反射能力和配置验证，支持 AI Agent 和开发调试
Table 模式
Table 模式（Phase 1）提供直接访问 DataSet（MetricSet、LogSet、TraceSet 等）的能力，返回表格化的可观测数据，适用于不依赖实体关系的数据查询场景。
如：直接查询某个 MetricSet 中的指标数据，或查询某个 LogSet 中的日志，无需关联实体信息。读取 apm.metric.apm.service MetricSet对应的avg_request_latency_seconds的指标，
并对该指标进行异常检测
.metric_set with(domain='apm', name='apm.metric.apm.service', metric='avg_request_latency_seconds', source='metrics')
| extend r = series_decompose_anomalies(value)
| extend anomaly_b =r.anomalies_score_series , anomaly_type = r.anomalies_type_series , anomaly_msg = r.error_msg
| extend x = zip(anomaly_b, ts, anomaly_type, value)
| extend anomaly_rst = filter(x, x-> x.field0 > 0)
| project entity_id, labels, anomaly_rst, anomaly_msg
核心特点：
• 直接访问：直达 DataSet，无需查询实体元数据
• 语法简洁：类似 SQL 的 SPL 语法，易于理解
• 全量数据：返回 DataSet 中符合条件的所有数据
语法：. with(domain, name, ...) | ，更多参数说明请参考文档：Phase 1 Table 模式[1]。
Object 模式
Object 模式（Phase 2）提供以实体为中心的面向对象查询能力，自动处理实体与数据的关联关系、字段映射、关系查询等复杂逻辑，适用于需要实体上下文的业务场景。
如：查询某个具体服务的指标、日志、链路数据，或查询与该服务有调用关系的其他服务，系统自动完成字段映射和数据过滤。查询特定服务的请求延迟指标，自动处理字段映射和 FilterByEntity
.entity_set with(domain='apm', name='apm.service', ids=['21d5ed421ae93973d67a04af551b48b8'])
| entity-call get_metric('apm', 'apm.metric.apm.service', 'avg_request_latency_seconds', 'range', '30s', false)
| project entity_id, ts, value, labels
核心优势：
• 零配置过滤：自动处理 FilterByEntity，无需手动拼接过滤条件
• 字段映射透明：自动转换 service_id → acs_arms_service_id 等映射
• 面向对象语义：entity.get_metric()，符合开发者思维习惯
语法：.entity_set with(domain, name, id, query) | entity-call <方法>(<参数>) | ，更多参数说明请参考文档：Phase 2 Object 模式[2]。
元数据查询方法
元数据查询方法提供动态发现和反射能力，用于查询实体的关联关系、数据集配置、支持的方法等元数据信息，既可以帮助开发者理解实体能力，也是实现 AI Agent 自主决策和配置验证的关键基础。
如：查询某个服务实体支持哪些方法（list_method()）、关联了哪些数据集（list_data_set()）、与哪些其他服务有调用关系（list_related_entity_set()）、配置是否正确（inspect()）。动态发现实体支持的所有方法（反射能力）
.entity_set with(domain='apm', name='apm.service')
| entity-call list_method()返回：方法列表及参数定义
[
{"name": "get_metric", "params": [...], "description": "获取指标数据"},
{"name": "list_related_entity_set", "params": [...], "description": "查询关联实体"},
...
]
核心价值：
• 反射能力：list_method() 让 AI Agent 能自主探索实体的能力边界
• 配置验证：inspect() 一键检查 DataSet、Link、字段映射等配置完整性
• 关系查询：list_related_entity_set() 快速获取拓扑关系，无需查询图数据库
• 能力发现：list_data_set() 了解实体关联的所有观测数据类型
语法：.entity_set with(domain, name, id, query) | entity-call <方法>(<参数>)，更多参数说明请参考文档：Phase 2 Object 模式。
查询方式
UI 方式
登录云监控 2.0 控制台，点击实体探索 -> SPL，输入 SPL，如下图所示：
.entity_set with(domain='apm', name='apm.service', ids=['21d5ed421ae93973d67a04af551b48b8']) | entity-call get_metric('apm', 'apm.metric.apm.service', 'avg_request_latency_seconds', 'range', '', false)
DryRun 模式
DryRun 模式返回对应的 Query，不执行当前 Query，也支持手动设置运行模式。开启dry_run模式
.set umodel_paas_mode='dry_run';
.entity_set with(domain='apm', name='apm.service')
| entity-call get_metric('apm', 'apm.metric.apm.service', 'avg_request_latency_seconds', 'range', '', false)
UI 开启 DryRun 模式：
SDK 方式
通过阿里云 OpenAPI[3]下载 SDK，代码如下：
package main
import (
"fmt"
cms20240330 "github.com/alibabacloud-go/cms-20240330/v3/client"
openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
"github.com/alibabacloud-go/tea/tea"
credential "github.com/aliyun/credentials-go/credentials"
"os"
)
func CreateClient() (_result *cms20240330.Client, _err error) {
credential, _err := credential.NewCredential(nil)
if _err != nil {
return _result, _err
}
config := &openapi.Config{
}Credential: credential,
config.Endpoint = tea.String("cms.cn-hangzhou.aliyuncs.com")
_result = &cms20240330.Client{}
_result, _err = cms20240330.NewClient(config)
return _result, _err
}
func _main(args [ ]*string) (_err error) {
client, _err := CreateClient()
if _err != nil {
return _err
}
getEntityStoreDataRequest := &cms20240330.GetEntityStoreDataRequest{
}Query: tea.String(".entity_set with(domain='apm', name='apm.service', ids=['21d5ed421ae93973d67a04af551b48b8']) | entity-call get_metric('apm', 'apm.metric.apm.service', 'avg_request_latency_seconds', 'range') "), From: tea.Int32(1762244123), To: tea.Int32(1762244724),
if result, err := client.GetEntityStoreData(tea.String("o11y-demo-cn-hangzhou"), getEntityStoreDataRequest); err != nil {
return err
} else {
return nilfmt.Printf("length: %d", len(result.Body.Data))
}
}
func main() {
err := _main(tea.StringSlice(os.Args[1:]))
if err != nil {
panic(err)
}
}
参数说明：
程序运行
go build -o demo .
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=
export ALIBABA_CLOUD_ACCESS_KEY_ID=
./demo
示例
集成算子实现高阶能力：UModel 高阶查询 + 时序异常检测算子
通过 UModel 高阶 API 集成 SLS 时序异常检测算子 series_decompose_anomalies，一行查询实现智能异常检测。
如：监控某个 APM 服务的请求延迟，当出现异常（突刺、趋势变化、平台变化）时触发告警。
.entity_set with(domain='apm', name='apm.service', ids=['21d5ed421ae93973d67a04af551b48b8'])
| entity-call get_metric('apm', 'apm.metric.apm.service', 'avg_request_latency_seconds', 'range', '30s', false)
| extend r = series_decompose_anomalies(value)
| extend anomaly_b =r.anomalies_score_series , anomaly_type = r.anomalies_type_series , anomaly_msg = r.error_msg
| extend x = zip(anomaly_b, ts, anomaly_type, value)
| extend anomaly_rst = filter(x, x-> x.field0 > 0)
| project entity_id, labels, anomaly_rst, anomaly_msg
返回结果
支持的异常类型：
• SPIKE_UP / SPIKE_DOWN - 向上/向下突刺
• TREND_SHIFT_UP / TREND_SHIFT_DOWN - 趋势上升/下降
• LEVEL_SHIFT_UP / LEVEL_SHIFT_DOWN - 平台上升/下降
如下图：
数据互联互通：关联自定义 LogStore
在实际生产环境中，业务数据往往分散在多个存储中。例如：
• UModel 中存储了 APM 服务的拓扑关系、指标、链路、日志
• 业务系统的自定义日志存储在独立的 LogStore 中（如订单日志、支付日志、用户行为日志）
通过 UModel 高阶 API + SPL join 能力，可以打通 UModel 实体数据与自定义业务数据，实现： - 统一视角分析：将应用性能问题与业务日志关联分析
- 快速定位问题：从服务异常快速定位到具体业务操作
- 端到端追踪：从业务请求到技术指标的全链路分析
典型场景：
• 某个 APM 服务出现延迟异常 → 关联业务订单日志 → 定位到具体慢查询的订单 ID
• 某个服务的错误日志激增 → 关联用户行为日志 → 分析是哪些用户操作触发了异常
• 分析服务调用链路 → 关联业务流程日志 → 追踪完整的业务流转路径
示例：场景：关联自定义的logstore日志信息
SPL:
1. 从业务LogStore中找到失败的traceId以及msg
.let failed_log = .logstore with(project=‘xxx’, logstore=‘xxxx’, query=‘*')| project trace_id, msg;2. 查询服务的Trace数据
.let service_traces = .entity_set with(domain='apm', name='apm.service', ids=['xxxx'])
$failed_log | join $service_traces on trace_id = $service_traces.traceId | project msg| entity-call get_trace(‘apm‘, ’apm.trace.common’);
集成 AI Agent：通过反射能力实现自主决策
将 UModel PaaS API 封装为 MCP Tools[4]，通过反射能力（list_method()）让 AI Agent 具备自主探索和决策能力，实现智能运维分析。
如：用户问“为什么服务响应慢？”，Agent 通过动态发现可用方法，自主完成根因分析。Agent 首先调用 list_method() 动态发现实体支持的方法
.entity_set with(domain='apm', name='apm.service')
| entity-call list_method()返回示例（Agent 根据返回的方法列表自主决策下一步操作）:
{
"methods": [
{"name": "get_metric", "params": [...], "description": "获取指标数据"},
{"name": "get_log", "params": [...], "description": "获取日志数据"},
{"name": "get_trace", "params": [...], "description": "获取链路数据"},
{"name": "list_related_entity_set", "params": [...], "description": "查询关联实体"}
]
}
相关链接：
[1] Phase 1 Table 模式
https://help.aliyun.com/zh/cms/cloudmonitor-2-0/phase-1-table-mode
[2] Phase 2 Object 模式
https://help.aliyun.com/zh/cms/cloudmonitor-2-0/phase-2-object-mode-service-discovery
[3] 阿里云 OpenAPI
https://api.aliyun.com/api/Cms/2024-03-30/GetEntityStoreData
[4] MCP Tools
https://modelcontextprotocol.io/docs/getting-started/intro
