MetricStore HTTP API返回值详解及状态码错误码处理方法-日志服务-阿里云

日志服务提供多个用于查询时序指标或写入指标数据到MetricStore的API，这些API兼容Prometheus开源协议。本文介绍这些API的返回值说明。

响应结构

MetricStore Prometheus写入和查询 API 的响应结构遵循 Prometheus 官方定义，SLS在此之上增加 slsStatus字段以提供更详细的错误信息和处理策略。

Prometheus API 的响应结构如下：

HTTP Header :
x-sls-request-id : <string>  // 此次请求的 RequestId

HTTP Response Body :
{
  "status": "success" | "error",
  "data": <data>,

  // SLS 返回的内部错误信息，仅当查询出现警告/错误时，该字段存在
  "slsStatus" : {
     // 重试策略
     "retryPolicy" : "None" | "Once" | "Continuous",
     // 错误码
     "errorCode" : "<string>",
     // 错误信息
     "errorMessages" : ["<string>"]
  }

  // 执行查询分析出现错误时，返回以下两项内容。
  "errorType": "<string>",
  "error": "<string>",
  
  // 返回警告信息，一般为查询不完整问题。
  "warnings": ["<string>"],
  // 返回普通信息，一般不需要额外处理
  "infos": ["<string>"]
}

重试策略

重试策略用于指导客户端在遇到相应的错误时的重试行为，避免无效重试造成体验下降。

重试策略	含义	重试建议
Once	错误可能由限流等原因引起，重试一次后有可能出现相同错误，也有小概率恢复。	等待一段时间后（建议 300ms 以上），重试一次，如果出现相同的返回码（Once）则停止重试。
Continuous	服务端存在问题，需要每隔一段时间持续不断重试，可能会恢复。	使用退火策略进行重试，建议的退火方式：初次等待 300ms 后重试。若再次出现 Continuous，则等待时间翻倍。若等待时间超过 10s ，则限制为 10s。若再次出现不为 Continuous，则进入相应策略的处理逻辑。
None	相同请求再次发送的话，此错误确定会仍然出现。	不做任何重试。

状态码与处理建议

请求类型	HTTP 状态码	ErrorCode	说明	重试策略	处理建议
查询&写入	200	无	请求成功。	无	无
查询	200	ShardPartialSuccess	部分Shard执行不成功，一般由队列满或宕机引起。	Continuous	退火重试，参考 Continuous 重试策略。
查询	200	ShardResourceExceed	请求的数据超过 Shard 读取数据量限制。参考 MetricStore。	Once	重试一次，再次请求大概率仍然会出现。建议分裂 Shard 或使用并行计算模式。
查询	200	EngineResourceExceed	一般由于计算引擎执行前已经检测出数据量远超限制而返回的报错。参考 MetricStore。	None	建议缩小时间范围或优化 Query 减少数据扫描量，或使用并行计算模式。
查询	200	BadDataWarning	由于数据问题而引起的计算报错，一般常见于 PromQL 的多元算子场景下数据不匹配，此种情况仅保留部分计算结果。	None	建议检查数据和 Query 是否符合业务需求，优化数据或 Query。
查询&写入	400	BadParameterError	查询参数/语法错误。	None	查看报错信息并修正错误语句或参数。
查询&写入	422	BadDataError	由于数据问题而引起的计算/写入报错。	None	建议检查数据和 Query 是否符合业务需求，优化数据或 Query。
查询	422	EngineExecutionExceed	计算引擎中参与计算的数据量超限。参考 MetricStore。	None	建议缩小时间范围或优化 Query 减少数据扫描量，或使用并行计算模式。
查询&写入	401	Unauthorized	无权限进行操作。	None	参考概览，赋予账号权限。
查询&写入	404	ProjectNotExist	Project 不存在。	None	若 Project 未被删除，请检查 Project 名称以及接入域名是否正确。
查询&写入	404	MetricStoreNotExist	MetricStore 不存在。	None	若 MetricStore 未被删除，请检查 MetricStore 名称是否正确。
查询	502	EngineQueueTimeout	引擎排队超时，一般由于引擎负载较高引起。	Continuous	退火重试，若长时间持续出现请工单联系技术支持。
查询	500	EngineExecutionError	引擎执行出现未知错误，一般由于数据格式非法引起。	Once	重试一次，若长时间持续出现请提工单。
查询	502	EngineExecutionTimeout	引擎执行 Query 时间超限，一般由于引擎负载较高或 Query 复杂度过高引起。	Once	重试一次，若长时间持续出现请提工单。
写入	500	WriteQuotaExceed	由于 Project 或 Shard 配额超限引起的写入错误。参考数据读写。注意：由于 Quota 超限对于 SLS OpenAPI 的返回状态码为 403，但由于官方 Prometheus 中未定义 Quota 超限的返回类型，为保证开源 Agent 正常重试，因此定义为 500。	Continuous	写入侧退火重试。此外请检查错误信息，若 Project Quota 超限，请工单联系技术支持调整；若 Store Quota 超限，建议为 Store 开启 Shard 自动分裂，或手动分裂 Shard。
查询&写入	500	InternalServerError	其他系统内部异常。	Continuous	退火重试，若长时间持续出现请提工单。

响应示例

正常请求

{
    "status": "success",
    "data": {
        "resultType": "matrix",
        "result": [
            {
                "metric": {},
                "values": [
                    [
                        1673798460,
                        "11111111"
                    ],
                    [
                        1673799060,
                        "22222222"
                    ],
                    [
                        1673799660,
                        "33333333"
                    ]
                ]
            }
        ]
    }
}

返回部分数据

当查询不完整时，会返回部分数据，此时会存在 slsStatus 字段中会附加详细的报错信息以及重试策略。

{
	"status": "success",
	"slsStatus": {
		"retryPolicy": "Once",
		"errorCode": "ShardResourceExceed",
		"errorMessages": ["sls response error 1 task data", "sls response drop 1 task data"]
	},
	"data": {
		"resultType": "vector",
		"result": [{
			"metric": {
				"__name__": "up",
			},
			value: [
				1747807789.37,
				"1"
			]
		}]
	},
	"warnings": ["sls response error 1 task data", "sls response drop 1 task data"]
}

返回错误

示例1

{
	"status": "error",
	"slsStatus": {
		"errRetryPolicy": "None",
		"errCode": "EngineResourceExceed",
		"errMessages": ["too many time Series or items"]
	},
	"data": {
	},
	"error": "too many time Series or items"
}

示例2

{
	"status": "error",
	"slsStatus": {
		"retryPolicy": "None",
		"errorCode": "BadDataError",
		"errorMessages": ["vector cannot contain metrics with the same labelset"]
	},
        "data": {
	},
	"error": "vector cannot contain metrics with the same labelset"
}

使用场景

前端展示

MetricStore 内置指标可视化并支持构建 Dashboard，同时支持对Grafana。若查询出现异常，内置可视化方案会自动将相关信息显示在可视化图表上。

Grafana 建议使用 10.0 即以上版本，可获取更好的 Warning 提示信息。

如需基于 MetricStore 的 Prometheus API 构建自定义的可视化方案，建议可按照下述策略处理异常：

如 HTTP 状态码为 200，则图表正常渲染
1. 若 slsStatus字段存在，建议在图表上显示 Warning 信息，并按照 RetryPolicy 提示用户解决策略
如 HTTP 状态码为非 200，建议图表直接显示错误信息，并按照 RetryPolicy 提示用户解决策略

数据二次计算场景

MetricStore 支持使用定时SQL 定期计算聚合数据，若需基于 MetricStore 的 Prometheus API 构建自定义的二次计算场景，建议可按照下述策略处理异常：

若状态码为 200
1. 若不存在slsStatus字段，则正常将数据存储，并进入到下一次调度。
2. 若存在slsStatus字段，建议按照 RetryPolicy进行如下处理：
  1. None：重试一次，若继续是None，则标记此任务失败并进入到下一次调度。
  2. Once：重试一次，若继续是Once，则标记此任务失败并进入到下一次调度。
  3. Continuous：退火重试，若重试超过一定时间（建议 10-30 分钟），则标记此任务失败并进入到下一次调度。
若状态码非 200
1. 若不存在slsStatus字段，一般由网络原因造成，建议持续重试。
2. 若存在slsStatus字段，建议按照 RetryPolicy进行如下处理：
  1. None：重试一次，若继续是None，则标记此任务失败并进入到下一次调度。
  2. Once：重试一次，若继续是Once，则标记此任务失败并进入到下一次调度。
  3. Continuous：退火重试，若重试超过一定时间（建议 10-30 分钟），则标记此任务失败并进入到下一次调度。

建议：任务失败数据建议写入到另一个单独的 LogStore，按需配置是否告警。参考：为定时SQL任务设置告警

实时告警场景

SLS 支持在 MetricStore 上直接创建告警，若需基于 MetricStore 的 Prometheus API 构建自定义的实时告警系统，建议可按照下述策略处理异常：

若状态码为 200
1. 若不存在slsStatus字段，则正常执行告警条件监测。
2. 若存在slsStatus字段，建议按照 RetryPolicy进行如下处理：
  1. None：标记此次告警执行失败并进入到下一次调度。
  2. Once：重试一次，若继续是Once，则标记此次告警执行失败并进入到下一次调度。
  3. Continuous：退火重试，若重试超过一定时间（建议 1 分钟以内），则标记此次告警执行失败并进入到下一次调度。
若状态码非 200
1. 若不存在slsStatus字段，一般由网络原因造成，建议持续重试。
2. 若存在slsStatus字段，建议按照 RetryPolicy进行如下处理：
  1. None：标记此次告警执行失败并进入到下一次调度。
  2. Once：重试一次，若继续是Once，则标记此次告警执行失败并进入到下一次调度。
  3. Continuous：退火重试，若重试超过一定时间（建议 1 分钟以内），则此次告警执行失败并进入到下一次调度。

建议：
- 整体重试时间不要超过下一次告警调度时间，例如告警间隔 1 分钟，若超过整体重试时间超过 1 分钟，则直接跳过执行下一次告警，否则会导致相对更重要的新数据无法告警。
- 告警执行失败数据建议写入到另一个单独的 LogStore，按需配置是否告警。参考自定义分析告警日志。