エラースタックの解析¶
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 する必要があり、クエリの 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 が期待するソースファイルと一致するか確認してください。HTTP 200 や空でない結果であっても、すべてのフレームが復元済みであることを保証するものではありません。レスポンスにはソースコードの断片が含まれることがあり、権限を持つ呼び出し元のみが使用できます。成功時は Cache-Control:no-store が付与されますが、エラーレスポンスにも同様のヘッダーが付くことは保証されません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得・入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
ボディリクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 から取得し、ビルド成果物に対応させます。 |
パラメータ補足説明¶
「RUM データクエリ」権限を持つワークスペース 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 でこれら 2 つのフィールドが欠けている、または組み合わせがサポートされていない場合は、コンソールと同じ空の結果 {"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には空白以外の内容を含める必要があります。 - 1 回につき 1 つの元のスタックを送信します。
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 を保持し、まずバージョンの状態とファイルを確認してから、実際のエラーに応じて対処します。読み取りはバックオフして再試行できます。 |