JavaScript 오류 스택 트레이스의 축소 해제 활성화

웹 애플리케이션 JavaScript 소스 코드가 축소되면 오류 스택 트레이스를 읽기 어려울 수 있습니다. 소스 맵을 Amazon S3에 업로드하여 스택 트레이스에 대한 축소 해제를 활성화할 수 있습니다. CloudWatch RUM은 소스 맵을 검색하여 축소된 소스 코드의 라인 및 열 번호를 축소되지 않은 원래 소스 코드에 다시 매핑합니다. 이를 통해 오류 스택 트레이스의 가독성이 향상되고 원래 소스 코드에서 오류 위치를 식별할 수 있습니다.

요구 사항 및 구문

소스 맵은 다양한 릴리스에서 웹 애플리케이션의 문제를 디버깅하고 추적하는 데 매우 중요합니다. 각 웹 애플리케이션 릴리스에 고유한 소스 맵이 있는지 확인합니다. 각 릴리스에는 고유한 releaseId가 있어야 합니다. releaseId는 1~200자의 문자열이어야 하며 문자, 숫자, 밑줄, 하이픈, 콜론, 슬래시 및 마침표만 포함할 수 있습니다. releaseId를 RUM 이벤트에 메타데이터로 추가하려면 CloudWatch RUM 웹 클라이언트를 구성합니다.

소스 맵은 소스 맵 V3 사양에 정의된 구조를 따르는 일반 JSON 파일이어야 합니다. version, file, sources, names, mappings 필드는 필수입니다.

각 소스 맵의 크기가 50MB 제한을 초과하지 않는지 확인합니다. 또한 RUM 서비스는 스택 트레이스당 최대 50MB의 소스 맵만 검색합니다. 필요한 경우 소스 코드를 여러 개의 작은 청크로 분할합니다. 자세한 내용은 WebpackJS를 사용한 코드 분할을 참조하세요.

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 키를 사용하여 데이터를 암호화하는 경우 키를 사용하여 소스 맵 파일을 검색할 수 있는 액세스 권한을 RUM 서비스에 부여하기 위해 aws:SourceArn 및 aws:SourceAccount 전역 조건 컨텍스트 키를 포함하도록 키의 리소스 정책이 유사하게 구성되어 있는지 확인합니다.

{
    "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 스크립트 또는 유사한 스크립트를 사용한 경우 스크립트에 구성된 releaseId는 CloudWatch RUM 웹 클라이언트에 구성된 것과 동일해야 합니다. 버전 1.21.0 이상의 CloudWatch RUM 웹 클라이언트를 사용해야 합니다.

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은 다음을 포함하되 이에 국한되지 않는 다양한 이유로 스택 트레이스의 라인을 축소 해제하지 못할 수 있습니다.