跳转至

解析错误堆栈



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 400 ft.SourceMapStackTooLong。调用还受工作空间 OpenAPI 限流及现有 SourceMap 读取限制约束。
  • 常见鉴权错误包括 ft.APIAkKeyFailed(缺少 API Key)、ft.InvalidAPIKey(API Key 无效)、ft.APIKeyDisabled(API Key 已停用)和 ft.Forbidden(权限不足)。
  • 缺少必填字段或参数类型错误返回 HTTP 406 ft.ParameterValidationFailed。必填值为空白返回 HTTP 400 ft.SourceMapRequiredFieldBlank。非 JSON 请求或传入 URL 查询参数 body 返回 HTTP 400 ft.SourceMapJsonBodyRequired。JSON 语法错误返回 HTTP 400 ft.RequestJsonFormatError,JSON 顶层不是对象时返回 HTTP 400 ft.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,先确认版本状态和文件,再按实际错误处理;读取可退避重试。

文档评价

文档内容是否对您有帮助?