JavaScript エラースタックトレースの最小化解除を有効にする

ウェブアプリケーションの JavaScript ソースコードが最小化されると、エラースタックトレースの読み取りが困難になる可能性があります。ソースマップを Amazon S3 にアップロードすることで、スタックトレースの最小化解除を有効にすることができます。CloudWatch RUM はソースマップを取得して、最小化されたソースコードの行と列の番号を最小化されていない元のソースコードにマッピングします。これにより、エラースタックトレースの読みやすさが向上し、元のソースコード内のエラーの場所を特定できます。

要件と構文

ソースマップは、複数のさまざまなリリースにわたるウェブアプリケーションの問題をデバッグおよび追跡するために不可欠です。各ウェブアプリケーションリリースに一意のソースマップがあることを確認します。各リリースには一意の releaseId が必要です。releaseId は 1～200 文字の文字列である必要があります。含めることができるのは、文字、数字、アンダースコア、ハイフン、コロン、スラッシュ、ピリオドのみです。releaseId を RUM イベントにメタデータとして追加するには、CloudWatch RUM ウェブクライアントを設定します。

ソースマップは、ソースマップ V3 仕様で定義された構造に従ったプレーン JSON ファイルであることが想定されます。version、file、sources、names、mappings の各フィールドは必須です。

各ソースマップのサイズが 50 MB の制限を超えないようにしてください。さらに、RUM サービスで取得できるのは、スタックトレースごとに最大 50 MB のソースマップです。必要に応じて、ソースコードを複数の小さなチャンクに分割します。詳細については、WebpackJS の「Code Splitting」を参照してください。

RUM サービスアクセスを許可するように Amazon S3 バケットリソースポリシーを設定する

Amazon S3 バケットが RUM appMonitor と同じリージョンにあることを確認します。ソースマップファイルを取得するための RUM サービスアクセスを許可するように Amazon S3 バケットを設定します。aws:SourceArn と aws:SourceAccount のグローバル条件コンテキストキーを含めて、サービスのアクセス許可をリソースに制限します。これは、混乱した使節の問題に対する最も効果的な保護方法です。

次の例では、Amazon S3で aws:SourceArn と aws:SourceAccount のグローバル条件コンテキストキーを使用して、「混乱した代理」問題を回避する方法を示します。

{
    "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 サービスに付与します。

{
    "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:REGION:ACCOUNT_ID:key/KEY_ID",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "ACCOUNT_ID",
                    "aws:SourceArn": "arn:aws:rum:REGION:ACCOUNT_ID/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 です。

CloudWatch RUM は、以下を始めとするさまざまな理由でスタックトレース行の最小化に失敗することがあります。