スクリプトを使用した SourceMap のアップロード¶

RUM アプリケーションがパブリック DataWay 接続方式を使用している場合、アプリケーションの実行データは直接パブリック DataWay に報告されます。対応する SourceMap ファイルは、該当サイトの OpenAPI インターフェースを使用してスクリプトでアップロードできます。

つまり：

RUM データの報告時には、アプリケーション接続ページの datawayUrl と clientToken を使用します；
SourceMap ファイルのアップロード時には、サイトの OpenAPI アドレスと OPEN_API_KEY を使用します。

本書では、パブリック DataWay 環境でのスクリプトによる SourceMap のアップロード方法を説明します。

準備¶

現在のアプリケーションが該当する端末の接続ドキュメントに従って、パブリック DataWay の初期化を完了していることを確認してください；
現在のサイトに対応する OpenAPI アドレスを取得してください；
現在のサイトに対応する OPEN_API_KEY を取得してください；
- Guance ワークスペースに移動し、管理 > API Key 管理 > 新しいキーを作成 をクリックします；
- 作成が成功したら、API Key の詳細ページで Key を取得し、それをスクリプト内の DF_API_KEY として使用します；
- 環境やバージョンを区別しない場合は、app_id のみを渡すこともできますが、ヒット範囲が広くなり、調査時には env と version を同時に渡す方が正確です；
対象の RUM アプリケーションの app_id、env、version を取得してください；
- app_id は現在の RUM アプリケーションの一意の識別子です；
- env と version は、SDK の初期化時または実際のエラーデータ内の対応するフィールドと一致している必要があります；
SourceMap 設定の要件に従って、事前に sourcemap.zip をパッケージ化してください。
Shell バージョンを使用する場合は、環境に bash、curl、jq、split、mktemp、wc がインストールされていることを確認してください；
Python バージョンを使用する場合は、環境に python3 がインストールされていることを確認してください。

スクリプトによるアップロード¶

スクリプトによるアップロードは OpenAPI を介して実行され、パブリック DataWay 接続環境での自動アップロードに適しています。

スクリプトの説明¶

アップロードスクリプトのリポジトリ：sourcemap-upload-scripts。

現在、2 種類のアップロードスクリプトを提供しています：

Shell バージョン：upload-sourcemap.sh
Python バージョン：upload_sourcemap.py

どちらのスクリプトも、既にパッケージ化された sourcemap.zip ファイルをアップロードするためのものであり、SourceMap の生成や圧縮は行いません。

サンプルコマンドを実行する前に、上記のリポジトリから該当するスクリプトを取得し、現在のコマンド実行ディレクトリに配置するか、コマンドにスクリプトの実際のパスを指定してください。

パラメータの説明¶

必須パラメータ¶

--endpoint：サイトに対応する OpenAPI アドレス；
--api-key：サイトに対応する OPEN_API_KEY。リクエスト時に DF-API-KEY リクエストヘッダーに書き込まれます；
--app-id：RUM アプリケーションの app_id；
--file：アップロードする sourcemap.zip ファイルのパス。ファイルサイズは 500 MB を超えてはいけません。

オプションパラメータ¶

--version：アプリケーションのバージョン番号；
--env：アプリケーションの環境識別子（例：daily、gray、prod）；
--need-cover：同名ファイルを上書きするかどうか。指定可能な値は true または false、デフォルトは false；
--chunk-size-mb：チャンクアップロードサイズ（単位：MB）。デフォルトは 10、最大 10；
--merge-path：カスタムマージインターフェースパス。現在のサイトのマージインターフェースパスがスクリプトのデフォルト値と異なる場合のみ使用します；
--cancel-path：カスタムアップロードキャンセルインターフェースパス。現在のサイトのキャンセルインターフェースパスがスクリプトのデフォルト値と異なる場合のみ使用します。

使用方法¶

ShellPython

sh ./upload-sourcemap.sh \
  --endpoint https://openapi.guance.com \
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

python3 ./upload_sourcemap.py \
  --endpoint https://openapi.guance.com\
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

期待される出力¶

実行が成功すると、次のようなログが表示されます：

Init succeeded, uploadId=...
Uploading part x/y
Merge succeeded via /api/v1/rum_sourcemap/part_merge
Upload complete

環境変数による方法¶

環境変数を使用して同じパラメータを渡すこともできます：

export DF_OPENAPI_ENDPOINT="https://openapi.guance.com"
export DF_API_KEY="your-api-key"
export DF_APP_ID="app_id_from_studio"
export DF_VERSION="1.0.2"
export DF_ENV="daily"
export DF_SOURCEMAP_FILE="./sourcemap.zip"
export DF_NEED_COVER="true"

環境変数とコマンドラインパラメータの対応関係は次のとおりです：

DF_OPENAPI_ENDPOINT は --endpoint に対応
DF_API_KEY は --api-key に対応
DF_APP_ID は --app-id に対応
DF_VERSION は --version に対応
DF_ENV は --env に対応
DF_SOURCEMAP_FILE は --file に対応
DF_NEED_COVER は --need-cover に対応

その後、次のコマンドを実行します：

sh ./upload-sourcemap.sh

または：

python3 ./upload_sourcemap.py

注意事項¶

スクリプトによるアップロードは、パブリック DataWay 接続環境に適しています；
アップロードスクリプトは、OpenAPI + DF-API-KEY 認証方式を使用しており、datawayUrl + clientToken ではありません；
sourcemap.zip を解凍したディレクトリ構造は、エラースタック内のファイルパスと一致している必要があります；
アップロードファイルは .zip 形式である必要があり、ファイルサイズは 500 MB を超えてはいけません；
version と env のいずれか一方のみを指定した場合、アップロード先が不正確になる可能性があるため、両方を指定することを推奨します；
チャンクアップロードの各チャンクの最大サイズは 10 MB です；
アップロードプロセスが初期化後に失敗した場合、スクリプトは自動的にこのチャンクアップロードタスクをキャンセルしようとします。
Python バージョンは Python 標準ライブラリのみを使用しており、追加の pip 依存関係のインストールは必要ありません。

よくある質問¶

`uploadId is empty`¶

これは通常、サーバー側に同じ名前の SourceMap が既に存在し、上書きが有効になっていないことを示します。

次のパラメータを追加して再試行してください：

--need-cover true

`Missing required command`¶

Shell バージョンに必要なコマンドが不足していることを示します。該当するツールをインストールしてから再試行してください。

`Merge endpoint ... returned HTTP 404`¶

これは通常、現在のサイトが異なるマージインターフェースパスを使用していることを示します。

該当サイトの管理者に問い合わせてインターフェースパスを確認し、次のように指定し直してください：

--merge-path <your-path>

アップロード成功したがエラースタックが解決されない¶

まず以下の内容を確認してください：

app_id、version、env が実際のエラーデータと一致しているか。
sourcemap.zip を解凍したディレクトリ構造が、error_stack 内のリソースパスと一致しているか。
現在のアプリケーションが、SourceMap をアップロードする必要のある対象アプリケーションであるか。