日志服务提供多个用于查询时序指标或写入指标数据到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 | 服务端存在问题,需要每隔一段时间持续不断重试,可能会恢复。 | 使用退火策略进行重试,建议的退火方式:
|
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 配额超限引起的写入错误。参考数据读写。
| 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,则图表正常渲染
若
slsStatus
字段存在,建议在图表上显示 Warning 信息,并按照RetryPolicy
提示用户解决策略
如 HTTP 状态码为非 200,建议图表直接显示错误信息,并按照
RetryPolicy
提示用户解决策略
数据二次计算场景
MetricStore 支持使用 定时SQL 定期计算聚合数据,若需基于 MetricStore 的 Prometheus API 构建自定义的二次计算场景,建议可按照下述策略处理异常:
若状态码为 200
若不存在
slsStatus
字段,则正常将数据存储,并进入到下一次调度。若存在
slsStatus
字段,建议按照RetryPolicy
进行如下处理:None
:重试一次,若继续是None
,则标记此任务失败并进入到下一次调度。Once
:重试一次,若继续是Once
,则标记此任务失败并进入到下一次调度。Continuous
:退火重试,若重试超过一定时间(建议 10-30 分钟),则标记此任务失败并进入到下一次调度。
若状态码非 200
若不存在
slsStatus
字段,一般由网络原因造成,建议持续重试。若存在
slsStatus
字段,建议按照RetryPolicy
进行如下处理:None
:重试一次,若继续是None
,则标记此任务失败并进入到下一次调度。Once
:重试一次,若继续是Once
,则标记此任务失败并进入到下一次调度。Continuous
:退火重试,若重试超过一定时间(建议 10-30 分钟),则标记此任务失败并进入到下一次调度。
建议:任务失败数据建议写入到另一个单独的 LogStore,按需配置是否告警。参考:为定时SQL任务设置告警
实时告警场景
SLS 支持在 MetricStore 上直接创建告警,若需基于 MetricStore 的 Prometheus API 构建自定义的实时告警系统,建议可按照下述策略处理异常:
若状态码为 200
若不存在
slsStatus
字段,则正常执行告警条件监测。若存在
slsStatus
字段,建议按照RetryPolicy
进行如下处理:None
:标记此次告警执行失败并进入到下一次调度。Once
:重试一次,若继续是Once
,则标记此次告警执行失败并进入到下一次调度。Continuous
:退火重试,若重试超过一定时间(建议 1 分钟以内),则标记此次告警执行失败并进入到下一次调度。
若状态码非 200
若不存在
slsStatus
字段,一般由网络原因造成,建议持续重试。若存在
slsStatus
字段,建议按照RetryPolicy
进行如下处理:None
:标记此次告警执行失败并进入到下一次调度。Once
:重试一次,若继续是Once
,则标记此次告警执行失败并进入到下一次调度。Continuous
:退火重试,若重试超过一定时间(建议 1 分钟以内),则此次告警执行失败并进入到下一次调度。
建议:
整体重试时间不要超过下一次告警调度时间,例如告警间隔 1 分钟,若超过整体重试时间超过 1 分钟,则直接跳过执行下一次告警,否则会导致相对更重要的新数据无法告警。
告警执行失败数据建议写入到另一个单独的 LogStore,按需配置是否告警。参考自定义分析告警日志。