# 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` 필드는 필수입니다.
각 소스 맵의 크기가 50MB 제한을 초과하지 않는지 확인합니다. 또한 RUM 서비스는 스택 트레이스당 최대 50MB의 소스 맵만 검색합니다. 필요한 경우 소스 코드를 여러 개의 작은 청크로 분할합니다. 자세한 내용은 [WebpackJS를 사용한 코드 분할](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 키를 사용하여 데이터를 암호화하는 경우 키를 사용하여 소스 맵 파일을 검색할 수 있는 액세스 권한을 RUM 서비스에 부여하기 위해 `aws:SourceArn` 및 `aws:SourceAccount` 전역 조건 컨텍스트 키를 포함하도록 키의 리소스 정책이 유사하게 구성되어 있는지 확인합니다.
------
#### [ 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 스크립트 또는 유사한 스크립트를 사용한 경우 스크립트에 구성된 `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`입니다.
| MetricName | 단위 | 설명 |
| --- | --- | --- |
| UnminifyLineFailureCount | 개수 | 축소 해제에 실패한 JS 오류 이벤트의 스택 트레이스 라인 수입니다. 실패에 대한 추가 세부 정보는 event\_details.unminifiedStack 필드에서 실패한 특정 라인에 추가됩니다. |
| UnminifyLineSuccessCount | 개수 | 축소 해제된 JS 오류 이벤트의 스택 트레이스 라인 수입니다. |
| UnminifyEventFailureCount | 개수 | 라인 축소 해제에 실패한 JS 오류 이벤트 수입니다. 실패에 대한 추가 세부 정보는 event\_details.unminifiedStack 필드에 추가됩니다. |
| UnminifyEventSuccessCount | 개수 | 하나 이상의 스택 트레이스 라인이 축소되지 않은 상태로 성공한 JS 오류 이벤트 수입니다. |
CloudWatch RUM은 다음을 포함하되 이에 국한되지 않는 다양한 이유로 스택 트레이스의 라인을 축소 해제하지 못할 수 있습니다.
+ 권한 문제로 인해 해당 소스 맵 파일을 검색하지 못했습니다. 버킷 리소스 정책이 올바르게 구성되었는지 확인합니다.
+ 해당 소스 맵 파일이 존재하지 않습니다. 소스 맵 파일이 CloudWatch RUM 웹 클라이언트에 구성된 releaseId와 동일한 이름의 올바른 버킷 또는 폴더에 업로드되었는지 확인합니다.
+ 해당 소스 맵 파일이 너무 큽니다. 소스 코드를 더 작은 청크로 분할합니다.
+ 스택 트레이스에 대해 이미 50MB의 소스 맵 파일이 검색되었습니다. 서비스 측 제한으로 인해 스택 트레이스 길이를 50MB로 줄입니다.
+ 소스 맵이 유효하지 않아 인덱싱할 수 없습니다. 소스 맵이 소스 맵 V3 사양에 정의된 구조를 따르는 일반 JSON이고 버전, 파일, 소스, 이름, 매핑 필드가 포함되어 있는지 확인합니다.
+ 소스 맵이 축소된 소스 코드를 축소되지 않은 스택 트레이스에 다시 매핑할 수 없습니다. 소스 맵이 지정된 releaseId에 대해 올바른 소스 맵인지 확인합니다.