오류 스택 구문 분석¶
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자까지 허용합니다.
반드시 application/json 요청 본문으로 POST해야 하며, Query body 인코딩 파라미터는 허용되지 않고 실제 스택을 URL에 넣을 수 없습니다. 먼저 해당 빌드 산출물을 업로드하고 버전을 읽을 수 있는지 확인한 다음 원본 error_stack, env, version, error_type 및 os를 전송합니다. 이 API는 댓글을 작성하지 않고 오류 추적 상태를 업데이트하지 않습니다.
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이 예상 소스 파일과 일치하는지 확인해야 하며, HTTP 200 또는 비어 있지 않은 결과가 모든 프레임의 복원을 보장하지는 않습니다. 응답에는 소스 코드 일부가 포함될 수 있으며, 권한이 있는 호출자만 사용해야 합니다. 성공 응답에는 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 | 선택적 2요소 배열 [소스 행 번호, 해당 행 텍스트]이며, 컨텍스트가 없으면 생략됩니다. |
| 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 | 2요소 배열 [소스 행 번호, 텍스트]입니다. |
| content.stacktrace[].pre_context[][0] | integer | 소스 행 번호입니다. |
| content.stacktrace[].pre_context[][1] | string | 해당 행의 소스 텍스트입니다. |
| content.stacktrace[].post_context | array | 이후 행 배열이며 각 항목은 [1 기반 행 번호, 텍스트]이고 최대 약 5행이며 []일 수 있습니다. |
| content.stacktrace[].post_context[] | array | 2요소 배열 [소스 행 번호, 텍스트]입니다. |
| 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을 보관하고 먼저 버전 상태와 파일을 확인한 다음 실제 오류에 따라 처리합니다. 읽기는 백오프 재시도할 수 있습니다. |