# JavaScript エラースタックトレースの最小化解除を有効にする
ウェブアプリケーションの JavaScript ソースコードが最小化されると、エラースタックトレースの読み取りが困難になる可能性があります。ソースマップを Amazon S3 にアップロードすることで、スタックトレースの最小化解除を有効にすることができます。CloudWatch RUM はソースマップを取得して、最小化されたソースコードの行と列の番号を最小化されていない元のソースコードにマッピングします。これにより、エラースタックトレースの読みやすさが向上し、元のソースコード内のエラーの場所を特定できます。
## 要件と構文
ソースマップは、複数のさまざまなリリースにわたるウェブアプリケーションの問題をデバッグおよび追跡するために不可欠です。各ウェブアプリケーションリリースに一意のソースマップがあることを確認します。各リリースには一意の releaseId が必要です。releaseId は 1～200 文字の文字列である必要があります。含めることができるのは、文字、数字、アンダースコア、ハイフン、コロン、スラッシュ、ピリオドのみです。`releaseId` を RUM イベントにメタデータとして追加するには、CloudWatch RUM ウェブクライアントを設定します。
ソースマップは、[ソースマップ V3 仕様](https://sourcemaps.info/spec.html)で定義された構造に従ったプレーン JSON ファイルであることが想定されます。`version`、`file`、`sources`、`names`、`mappings` の各フィールドは必須です。
各ソースマップのサイズが 50 MB の制限を超えないようにしてください。さらに、RUM サービスで取得できるのは、スタックトレースごとに最大 50 MB のソースマップです。必要に応じて、ソースコードを複数の小さなチャンクに分割します。詳細については、WebpackJS の「[Code Splitting](https://webpack.js.org/guides/code-splitting/)」を参照してください。
**Topics**
+ [要件と構文](#CloudWatch-RUM-RequirementsJavaScriptStackTraceSourceMaps)
+ [RUM サービスアクセスを許可するように Amazon S3 バケットリソースポリシーを設定する](#CloudWatch-RUM-ConfigureS3)
+ [ソースマップをアップロードする](#CloudWatch-RUM-UploadSourceMaps)
+ [CloudWatch RUM ウェブクライアントで releaseId を設定する](#CloudWatch-RUM-ConfigureRumID)
+ [CloudWatch RUM アプリケーションモニターを有効にして JavaScript スタックトレースの最小化を解除する](#CloudWatch-RUM-unminifyjavascript)
+ [RUM コンソールでの最小化が解除されたスタックトレースを表示する](#CloudWatch-RUM-viewunminifiedstacktraces)
+ [最小化が解除されたスタックトレースを CloudWatch Logs で表示する](#CloudWatch-RUM-viewunminifiedstacktracesCWL)
+ [ソースマップのトラブルシューティング](#CloudWatch-RUM-troubleshootsourcemaps)
## RUM サービスアクセスを許可するように Amazon S3 バケットリソースポリシーを設定する
Amazon S3 バケットが RUM appMonitor と同じリージョンにあることを確認します。ソースマップファイルを取得するための RUM サービスアクセスを許可するように Amazon S3 バケットを設定します。`aws:SourceArn` と `aws:SourceAccount` のグローバル条件コンテキストキーを含めて、サービスのアクセス許可をリソースに制限します。これは、[混乱した使節の問題](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)に対する最も効果的な保護方法です。
次の例では、Amazon S3で `aws:SourceArn` と `aws:SourceAccount` のグローバル条件コンテキストキーを使用して、「混乱した代理」問題を回避する方法を示します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RUM Service S3 Read Permissions",
"Effect": "Allow",
"Principal": {
"Service": "rum.amazonaws.com"
},
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::{{BUCKET_NAME}}",
"arn:aws:s3:::{{BUCKET_NAME}}/*"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{ACCOUNT_ID}}",
"aws:SourceArn": "arn:aws:rum:{{REGION}}:{{ACCOUNT_ID}}:appmonitor/{{APP_MONITOR_NAME}}"
}
}
}
]
}
```
------
AWS KMS キーを使用してデータを暗号化する場合は、キーのリソースポリシーを同様に設定して `aws:SourceArn` と `aws:SourceAccount` のグローバル条件コンテキストキーを含めて、キーを使用してソースマップファイルを取得するためのアクセスを RUM サービスに付与します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RUM Service KMS Read Permissions",
"Effect": "Allow",
"Principal": {
"Service": "rum.amazonaws.com"
},
"Action": "kms:Decrypt",
"Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{KEY_ID}}",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{123456789012}}",
"aws:SourceArn": "arn:aws:rum:{{us-east-1}}:{{123456789012}}/{{APP_MONITOR_NAME}}"
}
}
}
]
}
```
------
## ソースマップをアップロードする
最小化中にソースマップを生成するように JavaScript バンドルを設定します。アプリケーションを構築すると、バンドルは、最小化された JavaScript ファイルとそれに対応するソースマップを含むディレクトリ (dist など) を作成します。例については、以下を参照してください。
```
./dist
|-index.d5a07c87.js
|-index.d5a07c87.js.map
```
ソースマップファイルを Amazon S3 のバケットにアップロードします。ファイルは、`releaseId` を名前とするフォルダに配置する必要があります。例えば、バケット名が `my-application-source-maps` で、`releaseId` が 2.0.0 の場合、ソースマップファイルは次の場所に配置されます。
```
my-application-source-maps
|-2.0.0
|-index.d5a07c87.js.map
```
ソースマップのアップロードを自動化するには、次の bash スクリプトを作成し、ビルドプロセスの一部として実行できます。
```
#!/bin/bash
# Ensure the script is called with required arguments
if [ "$#" -ne 2 ]; then
echo "Usage: $0 {{S3_BUCKET_NAME}} {{RELEASE_ID}}"
exit 1
fi
# Read arguments
S3_BUCKET="$1"
RELEASE_ID="$2"
# Set the path to your build directory
BUILD_DIR="./dist"
# Upload all .map files recursively
if aws s3 cp "$BUILD_DIR" "s3://$S3_BUCKET/$RELEASE_ID/" --recursive --exclude "*" --include "*.map"; then
echo "Successfully uploaded all source map files"
else
echo "Failed to upload source map files"
fi
```
## CloudWatch RUM ウェブクライアントで releaseId を設定する
CloudWatch RUM は、設定済みの `releaseId` を使用して、ソースマップファイルを取得するフォルダを決定します。`releaseId` にソースマップファイルフォルダと同じ名前を付けます。上記 bash スクリプトまたは同様の bash スクリプトを使用した場合、スクリプトで設定された `releaseId` は、CloudWatch RUM ウェブクライアントで設定されたものと同じである必要があります。CloudWatch RUM ウェブクライアントのバージョン 1.21.0 以降を使用する必要があります。
```
import { AwsRum, AwsRumConfig } from "{{aws-rum-web}}";
try {
const config: AwsRumConfig = {
sessionSampleRate: 1,
endpoint: "https://dataplane.rum.us-west-2.amazonaws.com",
telemetries: ["performance", "errors", "http"],
allowCookies: true,
releaseId: "{{RELEASE_ID}}", //Add this
};
const APPLICATION_ID: string = "{{APP_MONITOR_ID}}";
const APPLICATION_VERSION: string = "1.0.0";
const APPLICATION_REGION: string = "us-west-2";
new AwsRum(APPLICATION_ID, APPLICATION_VERSION, APPLICATION_REGION, config);
} catch (error: any) {
// Ignore errors thrown during CloudWatch RUM web client initialization
}
```
## CloudWatch RUM アプリケーションモニターを有効にして JavaScript スタックトレースの最小化を解除する
JavaScript スタックトレースの最小化を解除するには、アプリケーションモニターの SourceMap ステータスを `ENABLED` に設定します。アプリケーションモニターのすべてのソースマップを含むバケットまたはフォルダの Amazon S3 URI を指定します。
ソースマップを (サブフォルダではなく) メインバケットに直接保存する場合、Amazon S3 URI は `Amazon S3://{{BUCKET_NAME}}` の形式である必要があります。この場合、ソースマップファイルは次の場所に配置する必要があります。
```
{{BUCKET_NAME}}
|- {{RELEASE_ID}}
|-index.d5a07c87.js.map
```
子ディレクトリがルートの場合、Amazon S3 URI は `Amazon S3://{{BUCKET_NAME}}/{{DIRECTORY}}` の形式である必要があります。この場合、ソースマップファイルは次の場所に配置する必要があります。
```
{{BUCKET_NAME}}
|- {{DIRECTORY}}
|-{{RELEASE_ID}}
|-index.d5a07c87.js.map
```
## RUM コンソールでの最小化が解除されたスタックトレースを表示する
ソースマップを Amazon S3 にアップロードし、RUM アプリモニターでソースマップを有効にして、CloudWatch RUM ウェブクライアントで設定された `releaseId` を使用してウェブアプリケーションをデプロイした後、RUM コンソールで **[イベント]** を選択します。このタブには、生の RUM イベントデータが表示されます。JS エラーイベントタイプでフィルタリングして最新の JS エラーイベントを表示します。機能を有効にした後に取り込まれたイベントの新しい `event_details.unminifiedStack` フィールドに最小化が解除あれたスタックトレースが表示されます。
## 最小化が解除されたスタックトレースを CloudWatch Logs で表示する
**[データストレージ]** をオンにして、CloudWatch Logs で RUM イベントストレージを有効にします。有効にすると、新しい **event\_details.unminifiedStack** フィールドを検索できます。これにより、CloudWatch Logs クエリを使用して傾向を分析し、複数のセッションにわたる問題を関連付けることができます。
## ソースマップのトラブルシューティング
CloudWatch RUM には、ソースマップのセットアップのトラブルシューティングにすぐに使えるメトリクスが用意されています。これらのメトリクスは、`AWS/RUM` という名前の名前空間で発行されます。次のメトリクスは、application\_name ディメンションとともに発行されます。このディメンションの値は、アプリケーションモニターの名前です。メトリクスは、`aws:releaseId` ディメンションとともに発行されます。このディメンションの値は、JavaScript エラーイベントに関連付けられた `releaseId` です。
| MetricName | Unit | 説明 |
| --- | --- | --- |
| UnminifyLineFailureCount | カウント | JS エラーイベントのスタックトレースラインのうち、最小化されなかったものの数。障害に関する追加の詳細は、event\_details.unminifiedStack フィールドの失敗した特定の行に追加されます。 |
| UnminifyLineSuccessCount | カウント | JS エラーイベントのスタックトレースラインのうち、正常に最小化されたものの数。 |
| UnminifyEventFailureCount | カウント | いずれの行も最小化されなかった JS エラーイベントの数。最小化の失敗に関する詳細は、event\_details.unminifiedStack フィールドに追加されます。 |
| UnminifyEventSuccessCount | カウント | 少なくとも 1 つのスタックトレース行が最小化された JS エラーイベントの数。 |
CloudWatch RUM は、以下を始めとするさまざまな理由でスタックトレース行の最小化に失敗することがあります。
+ アクセス許可の問題が原因で対応するソースマップファイルが取得できない。バケットリソースポリシーが正しく設定されていることを確認してください。
+ 対応するソースマップファイルが存在しない。ソースマップファイルが CloudWatch RUM ウェブクライアントで設定された releaseId と同じ名前の正しいバケットまたはフォルダにアップロードされていることを確認してください。
+ 対応するソースマップファイルが大きすぎる。ソースコードを小さなチャンクに分割してください。
+ スタックトレース用に既に取得されている 50 MB 分のソースマップファイル。スタックトレースの長さを 50 MB に減らします。これはサービス側の制限です。
+ ソースマップが無効で、インデックスを作成できなかった。ソースマップがソースマップ V3 仕様で定義された構造に従ったプレーン JSON であること、およびバージョン、ファイル、ソース、名前、マッピングのフィールドが含まれていることを確認してください。
+ ソースマップが、最小化されたソースコードを最小化されていないスタックトレースにマッピングできなかった。ソースマップが、指定された releaseId の正しいソースマップであることを確認してください。