解析错误堆栈¶
POST /api/v1/rum_sourcemap/parse_stack
概述¶
使用对应SourceMap还原RUM错误堆栈。
调用前和使用步骤¶
当前Key需rum.Query,管理权限rum.rumCfgManage不能替代该查询权限。仅当前Key所属空间。appId取RUM应用简表content[].appId,与SDK/错误记录app_id一致,不能用数据库内部UUID替代。SourceMap按应用、环境env和版本version精确定位;大小写/空白属于标识本身,应与采集记录完全一致。env/version省略或空字符串表示空环境/空版本,并非通配全部。当前托管生命周期要求各最多256字符。
必须POST application/json请求体,不允许Query body编码参数,不能把真实堆栈放URL。先上传对应构建产物并确认版本可读,再传原始error_stack、env、version、error_type及os;此接口不写评论、不更新错误追踪状态。
Web当前解析SDK标准化“at 函数 @ URL:行:列”形式,按URL路径匹配同目录.js.map,示例匹配static/js/app.js.map;建议map含sourcesContent以返回源码上下文,源JS可辅助函数名推断。RN在os为Android/iOS且error_type=reactnative/reactnative_crash时走js/子目录,支持Hermes/Metro常见地址;RN原生ios_crash/anr_error走ios/,Android java_crash/anr_error走android/的mapping.txt,native_crash/anr_crash走android/的ABI符号目录。
iOS应用原生只处理ios_crash/anr_error,需匹配构建dSYM;Android java_crash/anr_error/network_error用mapping.txt,native_crash/anr_crash按ABI/ABI list匹配符号目录。应用miniapp/custom/harmonyos或未知error_type/os当前没有同等分支,可能返回js与空stacktrace,不能把该200当作支持此平台。
js为帧数组,native为文本。某帧未匹配map/源码/映射时可能保留原始行列而不报错;原生也可能部分符号化或原文本回退。检查filename/function/context_line与预期源文件是否吻合,HTTP200或非空结果都不保证每帧已经还原。返回可能含源码片段,仅供有权限调用方使用。成功带Cache-Control:no-store,不承诺错误响应同样有该头。
请求头¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| DF-API-KEY | string | Y | 工作空间的 OpenAPI 鉴权凭据。 例子: <DF-API-KEY>获取或填写方式: 从目标工作空间的 API Key 管理获取有该操作权限的 OpenAPI Key。 |
Body 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| appId | string | Y | 必填当前空间活动应用标识;不是内部RumCfg UUID,不能跨空间使用。 允许 null: False 例子: payment_web获取或填写方式: 从RUM应用简表content[].appId或错误记录app_id获取。 |
| env | string | 可选字符串,默认空环境,最多256字符;不代表所有环境,null不允许。 允许空字符串: True 允许 null: False 例子: production获取或填写方式: 从客户端发布环境/错误记录env取得,与上传时逐字一致。 |
|
| error_type | string | Web通常可省略。iOS支持ios_crash/anr_error;Android支持java_crash/anr_error、native_crash/anr_crash、network_error;RN结合os决定js或原生分支。当前不是声明枚举,未知值不保证拒绝,也可能返回空JS结果。 允许空字符串: True 允许 null: False 例子: reactnative获取或填写方式: 从错误记录error_type取得。 |
|
| os | string | 可选字符串;RN需要Android或iOS,内部忽略大小写。其他类型通常由应用jsonContent.type决定,不通过此字段修改应用平台。 允许空字符串: True 允许 null: False 例子: Android获取或填写方式: 从错误记录操作系统字段获取,RN尤其需要。 |
|
| stack | string | Y | 必填非空白字符串,最多131072字符且最多2000行;JSON内换行正确转义。Web当前识别SDK标准化的at 函数 @ URL:行:列形式,未规范化的普通V8/Chrome文本可能406,不能假定任意文本均可解析。 允许 null: False 例子: "Error: example\n at say @ https://cdn.example.com/static/js/app.js:1:1"获取或填写方式: 优先从实际RUM错误记录error_stack原样取得,不自行改写行列。 |
| version | string | 可选字符串,默认空版本,最多256字符;不代表最新/所有版本,null不允许。 允许空字符串: True 允许 null: False 例子: 1.2.3获取或填写方式: 从客户端实际发布版本/错误记录version取得,与构建产物对应。 |
参数补充说明¶
使用具有「用户访问数据查询」权限的工作空间 API Key。目标 RUM 应用必须属于该工作空间。
从 RUM 错误记录取 app_id 作为 appId、error_stack 作为 stack,并传入记录的 env 和 version。
环境或版本省略时按未指定值匹配,系统按请求对应的环境和版本查找映射。
React Native 调用请同时传入记录中的 os 与 error_type。Android 和 iOS 的 reactnative、reactnative_crash 走 JavaScript 分支,原生崩溃使用对应平台的原生解析分支。
对应 SourceMap 可读时,React Native 缺少这两个字段或组合不受支持会沿用控制台的空结果 {"stackType":"js","stacktrace":[]}。
content.stackType为js时,content.stacktrace是堆栈帧数组。成功响应可能保留未映射的原始帧,源码上下文字段在对应映射提供源码时返回。content.stackType为native时,content.stacktrace为非空的原生堆栈文本,可以保留未还原的帧。例如{"stackType":"native","stacktrace":"java.lang.IllegalStateException\n at com.example.Checkout.submit(Checkout.java:42)"}。- 参数通过 JSON 请求体传入,禁止 URL 查询参数
body。appId和stack必须包含非空白内容。 - 每次提交一条原始堆栈。
stack最多 131072 个字符、2000 行,超出限制返回 HTTP 400ft.SourceMapStackTooLong。调用还受工作空间 OpenAPI 限流及现有 SourceMap 读取限制约束。 - 常见鉴权错误包括
ft.APIAkKeyFailed(缺少 API Key)、ft.InvalidAPIKey(API Key 无效)、ft.APIKeyDisabled(API Key 已停用)和ft.Forbidden(权限不足)。 - 缺少必填字段或参数类型错误返回 HTTP 406
ft.ParameterValidationFailed。必填值为空白返回 HTTP 400ft.SourceMapRequiredFieldBlank。非 JSON 请求或传入 URL 查询参数body返回 HTTP 400ft.SourceMapJsonBodyRequired。JSON 语法错误返回 HTTP 400ft.RequestJsonFormatError,JSON 顶层不是对象时返回 HTTP 400ft.JsonFormatError。使用Accept-Language选择错误文案语言。 - 解析错误包括
ft.NotFoundRumSet(空间内未找到应用)、ft.SourceMapPackageNotFound(未找到对应包)、ft.SourceMapFileInvalid(映射文件无效)、ft.SourceMapStackFormatInvalid(堆栈格式无法识别)、ft.SourceMapNativeSymbolFileNotFound(缺少 Android Java 映射文件)和ft.SourceMapNativeParseFailed(原生解析未产生可用文本)。
请求例子¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/parse_stack' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","stack":"Error: example\n at say @ https://cdn.example.com/static/js/app.js:1:1"}'
响应¶
HTTP 200,application/json。下方示例展示可直接读取的主要字段。
| 字段 | 类型 | 说明 |
|---|---|---|
| content.stackType | string | js或native,用于确定stacktrace的JSON类型。 |
| content.stacktrace | array<object> 或 string |
js时为帧对象数组,native时为符号化文本;JS未匹配帧可能仍返回原位置,空数组不等于解析成功。 |
| content.stacktrace[] | object | JS单帧;未取得值的字段可省略。 |
| content.stacktrace[].name | string | SourceMap token名称,可省略,不必等同函数名。 |
| content.stacktrace[].function | string | 函数名,可能为输入或推断值。 |
| content.stacktrace[].source_url | string | 匹配map的相对URL路径,通常去掉URL前导/并加.map,无值可省略。 |
| content.stacktrace[].filename | string | 还原源码文件名或未还原位置,不是服务器物理路径。 |
| content.stacktrace[].path | string | 原堆栈路径。 |
| content.stacktrace[].platform | string | 可选平台标记。 |
| content.stacktrace[].stack_line | string | 输入原始堆栈行。 |
| content.stacktrace[].lineno | integer | 成功还原时源码1基行号,未映射时可能保留原位置。 |
| content.stacktrace[].colno | integer | 成功还原时源码1基列号。 |
| content.stacktrace[].context_line | array | 可选二元素数组[源码行号,该行文本],无上下文时省略。 |
| content.stacktrace[].context_line[0] | integer | 源码1基行号。 |
| content.stacktrace[].context_line[1] | string | 源码行文本。 |
| content.stacktrace[].pre_context | array | 前文行数组,每项[1基行号,文本],最多约5行,可[]。 |
| content.stacktrace[].pre_context[] | array | 二元素数组[源码行号,文本]。 |
| content.stacktrace[].pre_context[][0] | integer | 源码行号。 |
| content.stacktrace[].pre_context[][1] | string | 该行源码文本。 |
| content.stacktrace[].post_context | array | 后文行数组,每项[1基行号,文本],最多约5行,可[]。 |
| content.stacktrace[].post_context[] | array | 二元素数组[源码行号,文本]。 |
| content.stacktrace[].post_context[][0] | integer | 源码行号。 |
| content.stacktrace[].post_context[][1] | string | 该行源码文本。 |
| content.declaration | object | 当前空间公共声明,不递归插入帧。 |
| content.reasonCode | string | 仅错误响应:机器可判读原因,例如active_operation/invalid_scope/registry_missing。 |
| content.action | string | 仅错误响应:建议动作,例如retry_after_operation/verify_ownership/check_scope_and_upload。 |
| content.retryable | boolean | 仅错误响应:服务端建议可重试标记,不能单独据此重放已发布写入。 |
| content.uploadCommitted | boolean | 仅部分单文件错误诊断:true表示该写入已确认发布;省略不等于false或确认未写入。 |
| content.actualBytes | integer | 仅部分容量错误:已统计字节数。 |
| content.maxBytes | integer | 容量/读取限制字节数。 |
| content.workspaceUUID | string | 部分错误受限诊断:当前空间UUID。 |
| content.appId | string | 部分错误受限诊断:公开应用标识。 |
| content.rumCfgUUID | string | 部分错误受限诊断:内部应用标识,仅用于支持排查,不替换请求appId。 |
| content.env | string | 部分错误诊断:环境。 |
| content.version | string | 部分错误诊断:版本。 |
| content.bundleUUID | string | 部分错误诊断:本次代际记录ID,不是uploadId。 |
| content.state | string | 部分错误诊断:代际状态。 |
| content.resource | string | 部分占用诊断:资源类型,如application/bundle。 |
| content.shared | boolean | 部分占用诊断:是否共享访问。 |
| content.waitedSeconds | number | 部分占用诊断:已等待秒数。 |
| content.waitSeconds | number | 部分占用诊断:允许等待秒数。 |
| content.waitExhausted | boolean | 部分占用诊断:本次等待耗尽。 |
| content.elapsedSeconds | number | 部分单文件错误诊断:操作耗时秒。 |
| content.phase | string | 部分错误诊断:失败阶段。 |
| content.phaseElapsedSeconds | number | 部分错误诊断:阶段耗时秒。 |
{
"code": 200,
"content": {
"stackType": "js",
"stacktrace": [
{
"function": "say",
"source_url": "static/js/app.js.map",
"filename": "app.ts",
"path": "/static/js/app.js",
"stack_line": " at say @ https://cdn.example.com/static/js/app.js:1:1",
"lineno": 1,
"colno": 1,
"context_line": [
1,
"console.log(1);"
],
"pre_context": [],
"post_context": []
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
{
"code": 200,
"content": {
"stackType": "native",
"stacktrace": "java.lang.RuntimeException: example\n at com.example.Payment.run(Payment.java:10)",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
错误响应¶
鉴权、限流和公共请求错误参见公共错误定义。
存储生命周期保留兼容错误码:409通常仍为ft.InvalidAction,本地化message与content.reasonCode进一步区分原因,不把message名SourceMapOperationBusy等当作必然errorCode。读取缺包/处理中/不可用常为404 ft.SourceMapPackageNotFound,具体原因看reasonCode。只有明确返回retryable=true且现态允许时退避重试;uploadCommitted=true时不能重放已确认发布的写入。 SourceMapNativeParseFailed明确透传500;其他未透传解析内部异常统一500 ft.InternalServerError。不是每个缺map帧都触发404。
| HTTP 状态 | errorCode | 触发条件 | 消息或响应说明 | 处理方式 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 请求字段缺失,或字段值违反声明的校验条件 | 参数解析失败 | 核对参数位置、字段名、类型和取值。 |
| 400 | ft.RequestJsonFormatError | 请求 JSON 语法无效 | 请求 JSON 格式错误 | 按 content.reason、line、column 修正 JSON。 |
| 400 | ft.JsonFormatError | JSON顶层不是对象 | 部分 json 文件格式错误 | 提交JSON对象。 |
| 400 | ft.SourceMapJsonBodyRequired | 不是application/json请求体,或URL存在body参数 | 请通过 JSON 请求体传入参数,勿使用 URL 查询参数 body。 | 改为POST JSON,移除URL body参数。 |
| 400 | ft.SourceMapRequiredFieldBlank | appId或stack只含空白 | stack 必须包含非空白内容。 | 填写非空实际值。 |
| 400 | ft.SourceMapStackTooLong | stack字符超过131072或splitlines超过2000行 | stack 最多可包含 131072 个字符、2000 行。 | 减少本次堆栈,保留需解析片段。 |
| 404 | ft.NotFoundRumSet | 应用不在当前空间、已删除或不存在 | 未找到指定RUM设置 | 刷新RUM应用简表,使用当前空间真实appId。 |
| 404 | ft.SourceMapPackageNotFound | 所选环境/版本无记录、处理中、不可用或所需文件缺失 | 按reasonCode返回未找到记录/仍在处理/不可读取/源文件不存在等本地化提示 | 核对appId/env/version和版本状态;bundle_processing等待,source_files_missing请管理员检查文件或重新上传。 |
| 409 | ft.InvalidAction | 上传/读取/清理冲突、旧目录接管未完成、归属/恢复待核验或环境版本超出生命周期允许范围 | 按reasonCode返回具体本地化提示,例如SourceMap正被其他上传、读取或清理操作使用 | 读取content.reasonCode/action/retryable:active_operation/active_upload等按指引退避;owner_recovery_required/ownership_verification_required/legacy_invalid等先请管理员核验,勿自行删除占用记录或强行覆盖。invalid_scope核对env/version最多256字符。 |
| 406 | ft.InvalidFileName | 文件相对路径、软链接或历史发布路径不安全 | SourceMap 文件路径不符合要求,或包含不支持的链接。请检查上传文件的相对路径与目录结构。 | 使用包内合法相对路径,不含..、反斜线、绝对路径/软链接;检查reasonCode=invalid_path。 |
| 413 | ft.SourceMapSnapshotTooLarge | 读取所需文件快照超过站点限制,默认2GiB | 本次 SourceMap 读取所需文件总大小超过限制 | 减少版本文件量或请管理员核对限制。 |
| 406 | ft.SourceMapStackFormatInvalid | Web/RN文本无法识别为可用堆栈帧 | 无法识别 SourceMap 堆栈格式 | 使用RUM标准化error_stack,核对应用平台和语言分支。 |
| 406 | ft.SourceMapFileInvalid | 实际匹配到的map或辅助源码无法读取/解析 | SourceMap 文件内容无效或无法解析 | 核对构建版本、map格式与编码,不上传任意JSON改名.map。 |
| 404 | ft.SourceMapNativeSymbolFileNotFound | 严格Android Java分支缺少mapping.txt | 未找到原生堆栈解析所需的符号文件 | 上传对应构建mapping.txt,RN放android/。 |
| 500 | ft.SourceMapNativeParseFailed | 严格Android符号工具失败/无有效输出,或native分支最终无非空文本 | 原生堆栈解析失败 | 保留traceId请管理员检查符号工具和构建文件;此500明确透传。 |
| 500 | ft.InternalServerError | 数据库、文件读取/快照、历史配置或未处理解析异常 | 内部错误 | 保留traceId与应用/env/version,先确认版本状态和文件,再按实际错误处理;读取可退避重试。 |