错误码系统_云监控(CMS)-阿里云帮助中心

概述

UModel 高阶接口采用分层结构化错误处理系统，支持响应状态管理、重试策略和用户友好的错误消息。

应用案例

当前应用案例相关素材，请参考：umodel.zip

错误处理系统架构

响应状态层级

执行结果状态

状态	说明	优先级
`Success`	执行成功	0
`PartialSuccess`	部分成功	1
`Error`	执行失败	2

错误级别

级别	说明	优先级
`Info`	信息提示	0
`Warn`	警告信息	1
`Error`	错误信息	2

重试策略

策略	说明
`None`	不建议重试
`Once`	建议重试一次
`Continuous`	可持续重试

错误码分类

错误码按处理阶段分为三个类别：

Common - 通用错误（请求处理、UModel 相关等）。
Phase1 - 第一阶段错误（数据源、存储、PromQL 等）。
Phase2 - 第二阶段错误（实体处理、方法调用等）。

通用错误码 (Common)

基础请求处理错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`InvalidRequestData`	400	None	Error	Request data format error	检查请求数据结构，确保提供所有必需字段
`ConvertFailed`	400	None	Error	Conversion failed: xxxx	检查 SPL 语法，确保与目标系统兼容
`MissingParams`	400	None	Error	Missing required parameters: xxxx	按 API 文档提供所有必需参数
`InvalidParams`	400	None	Error	Invalid parameters: xxxx	检查参数和 API 文档，确保参数有效
`UnsupportedOperation`	400	None	Error	Unsupported operation: xxxx	使用支持的操作或查看 API 文档

UModel 相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`InvalidUModelData`	400	None	Error	Invalid UModel data	检查 UModel 数据格式，确保是有效的 JSON
`PartialInvalidUModelData`	200	None	Warn	Partial invalid UModel data, error: xxxx	检查 UModel 数据格式，确保是有效的 JSON
`UModelNotFound`	404	Continuous	Error	UModel data is empty, need to re-obtain	重新加载 UModel 配置或检查 UModel 服务是否可用
`ExpectedUModelNotFound`	400	Once	Error	UModel information not found: xxxx	确保 UModel 配置存在并正确加载

验证和处理错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`ValidateFailed`	400	None	Error	Validation failed: xxxx	根据验证规则检查数据并修复问题
`ExtractParamsFailed`	400	Once	Error	Failed to extract parameters: xxxx	确保参数格式正确且可访问
`InternalError`	500	None	Error	Internal error occurred in umode paas	联系系统管理员

Phase1 错误码

数据源相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`InvalidSourceType`	400	None	Error	Unsupported data source type	使用支持的数据源类型 (.metric_set, .log_set, .trace_set, .event_set)
`UnsupportedSourceType`	400	None	Error	Unsupported source type: xxxx	使用支持的 source 类型 (labels, metrics)
`UnsupportedQueryType`	400	None	Error	Unsupported query type: xxxx in MetricSet	检查 UModel 文档，确保在 MetricSet 中支持，有效查询类型：prom, spl
`UnsupportedDataSetType`	400	None	Error	Unsupported dataset type: xxxx	使用支持的数据集类型 (metric_set, log_set, trace_set, event_set)

存储相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`NotFoundStorageInfo`	400	Once	Error	Storage information not found	确保存储正确设置并链接到请求的实体或数据集
`InvalidStorageInfo`	400	None	Error	Invalid storage information	检查 UModel 文档并提供完整的存储配置
`MustUseSlsLogstore`	400	None	Error	xxxx requires SlsLogstore storage type	为此操作配置 SlsLogstore 作为存储类型
`MetricSetOnlySupportStorageType`	400	None	Error	xxxx only supports storage type: xxxx	为 metric set 操作配置正确的存储类型
`ListDataSetOnlySupportedStorageType`	400	None	Error	list_data_set only supports xxxx storage	为 list_data_set 操作使用支持的存储类型

数据集相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`DataSetUmodelNotFound`	400	Once	Error	DataSet UModel definition not found	确保 DataSet 在 UModel 配置中正确定义
`TargetDataSetNotFound`	400	Once	Error	Target DataSet not found	确保目标 DataSet 存在并正确配置
`NotFoundMetricDefinition`	400	Once	Error	Metric definition not found: xxxx	确保指标在 UModel 配置中定义

PromQL 相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`RewritePromQLFailed`	400	Once	Error	Failed to rewrite PromQL: xxxx, error: xxxx	检查 PromQL 语法，确保与目标系统兼容
`StaticLabelQueryNotSupported`	400	None	Error	Static label query not supported	使用动态标签查询
`WhereExprToPromQLFailed`	400	Once	Error	Failed to convert Where expression to PromQL: xxxx, error: xxxx	检查 Where 表达式语法，确保与 PromQL 兼容

表达式相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`ExprParseFailed`	400	Once	Error	Failed to parse expression: xxxx, error: xxxx	检查表达式语法(类 SQL)，重新查看 UModel 文档
`ExprExecFailed`	400	Once	Error	Failed to execute expression: xxxx, error: xxxx	检查表达式格式是否正确，重新查看 UModel 文档

高阶接口请求相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`InvalidUModelPaasRequestData`	400	None	Error	Invalid UModel PaaS request data	检查 UModel PaaS 请求格式，确保提供所有必需字段
`InvalidUModelPaasRequestWhereExpr`	400	None	Error	Invalid Where expression	检查 Where 表达式语法，确保遵循正确格式
`InvalidUModelPaasRequestQuery`	400	None	Error	Invalid UModel PaaS request data Query	检查查询结构格式是否正确，重新查看 UModel 文档

Phase2 错误码

实体相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`EntitySetNotFound`	400	None	Error	EntitySet does not exist: xxxx@entity_set@xxxx	确保 EntitySet 在 UModel 配置中定义
`EntitySetUmodelNotFound`	400	None	Error	EntitySet[xxxx] UModel definition not found	确保 EntitySet 在 UModel 配置中正确定义
`EntityDataMismatch`	400	None	Error	Entity data rows do not match header	确保实体数据结构与定义的 header 一致
`DynamicEntityWithoutStorage`	400	None	Error	Dynamic Entity[xxxx] has no storage information	为动态实体配置存储信息
`InvalidEntityIds`	400	None	Error	Invalid entity IDs: xxxx	提供正确格式的有效实体 ID
`StorageQueryNotFound`	400	None	Error	Storage query not found	确保存储查询正确配置

方法调用相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`MissingFunctionCall`	400	None	Error	Phase 2 Object mode must contain function call	在 SPL 查询中添加函数调用 (例如: \| entity-call list_method())
`InvalidEntitySetFunctionArguments`	400	None	Error	EntitySet function arguments error. xxxx	检查函数参数，确保符合预期签名
`MethodNotSupported`	400	None	Error	Method xxxx not supported	使用支持的方法或查看 API 文档
`DataSetUnSupportEntityCallFunction`	400	None	Error	xxxx unsupported method: xxxx	为此 DataSet 类型使用支持的方法

黄金指标相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`NoGoldenMetricsFound`	400	None	Warn	No golden metrics found related to xxxx	确保实体有黄金指标
`TooManyGoldenMetrics`	200	None	Warn	Too many golden metrics found related to xxxx, now count is %d	只返回 8 个黄金指标，其他被忽略。为获得更好性能，确保实体少于 8 个黄金指标

邻居实体查询相关错误

错误码	HTTP状态码	重试策略	级别	错误消息	处理建议
`StorageLinkNotFound`	400	None	Error	Storage link [xxxx] not found	确保 UModel 中正确配置存储链接
`UnsupportedStorageType`	400	None	Error	Unsupported storage type: xxxx	使用支持的存储类型
`UnsupportedRelationDirection`	400	None	Error	Unsupported direction: xxxx, only ‘in’ or ‘out’ supported	使用 ‘in’ 或 ‘out’ 作为关系方向
`EntitySetLinkStorageMissing`	400	None	Error	Entity set link xxxx@entity_set@xxxx has no storage link configured	为实体集关系配置存储链接
`InvalidFieldMapping`	400	None	Error	Invalid field mapping: xxxx	检查字段映射配置，确保格式正确

错误处理最佳实践

1. 错误码理解

每个错误都包含以下信息：

Code: 唯一的错误标识符。
Level: 错误级别 (Info/Warn/Error)。
Message: 用户友好的错误描述。
Suggestion: 具体的修复建议。
RetryPolicy: 重试策略建议。

2. 重试策略

根据 RetryPolicy 决定是否重试：

None: 语法错误等，不应重试。
Once: 临时错误，可重试一次。
Continuous: 资源限制等，可持续重试。

3. 常见错误场景处理

EntitySet 不存在

-- 错误：EntitySet 不存在
.entity_set with(domain='apm', name='nonexistent.service')

-- 正确：使用存在的 EntitySet
.entity_set with(domain='apm', name='apm.service')

缺少函数调用

-- 错误：Phase 2 模式缺少函数调用
.entity_set with(domain='apm', name='apm.service')

-- 正确：添加函数调用
.entity_set with(domain='apm', name='apm.service') 
| entity-call __list_method__()

参数验证失败

-- 错误：缺少必需参数
.metric_set with(name='apm.metric.apm.service')

-- 正确：提供所有必需参数
.metric_set with(domain='apm', name='apm.metric.apm.service')

4. 调试技巧

使用检查方法

-- 检查可用方法
.entity_set with(domain='apm', name='apm.service') 
| entity-call __list_method__()

-- 检查配置
.entity_set with(domain='apm', name='apm.service') 
| entity-call __inspect__()

DryRun 模式

.set "umodel_paas_mode"='dry_run';
-- 执行查询查看生成的 SPL

概述

应用案例

错误处理系统架构

响应状态层级

执行结果状态

错误级别

重试策略

错误码分类

通用错误码 (Common)

基础请求处理错误

UModel 相关错误

验证和处理错误

Phase1 错误码

数据源相关错误

存储相关错误

数据集相关错误

PromQL 相关错误

表达式相关错误

高阶接口请求相关错误

Phase2 错误码

实体相关错误

方法调用相关错误

相关数据集错误

黄金指标相关错误

邻居实体查询相关错误

错误处理最佳实践

1. 错误码理解

2. 重试策略

3. 常见错误场景处理

EntitySet 不存在

缺少函数调用

参数验证失败

4. 调试技巧

使用检查方法

DryRun 模式