本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 啟用 JavaScript 錯誤堆疊追蹤的反壓縮功能
當您的 Web 應用程式 JavaScript 原始程式碼被壓縮時，錯誤堆疊追蹤可能難以讀取。您可以透過將來源映射上傳至 Amazon S3，來啟用堆疊追蹤的反壓縮功能。CloudWatch RUM 將擷取來源映射，以將壓縮的來源程式碼中的行號和欄號映射回原始未被壓縮的來源程式碼。這將提高錯誤堆疊追蹤的可讀性，並有助於識別原始來源程式碼中錯誤的位置。
## 要求與語法
來源映射對於跨不同版本偵錯和追蹤 Web 應用程式的問題至關重要。請確定每個 Web 應用程式版本都有唯一的來源映射。每個版本都應有自己的唯一 releaseId。releaseId 必須是長度介於 1 到 200 個字元之間的字串，而且只能包含字母、數字、底線、連字號、冒號、斜線和句點。若要將 `releaseId` 作為中繼資料新增至 RUM 事件，請設定 CloudWatch RUM Web 用戶端。
根據[來源映射 V3 規格](https://sourcemaps.info/spec.html)所定義的結構，來源映射應該是純 JSON 檔案。必要欄位包括：`version`、`file`、`sources`、`names` 和 `mappings`。
請確定每個來源映射的大小不超過 50 MB 的限制。此外，RUM 服務只會擷取每個堆疊追蹤最多 50 MB 的來源映射。如有需要，請將原始程式碼分割成多個較小的區塊。如需詳細資訊，請參閱[使用 WebpackJS 分解程式碼](https://webpack.js.org/guides/code-splitting/)。
**Topics**
+ [要求與語法](#CloudWatch-RUM-RequirementsJavaScriptStackTraceSourceMaps)
+ [設定 Amazon S3 儲存貯體資源政策以允許 RUM 服務存取](#CloudWatch-RUM-ConfigureS3)
+ [上傳來源映射](#CloudWatch-RUM-UploadSourceMaps)
+ [在 CloudWatch RUM Web 用戶端中設定 releaseId](#CloudWatch-RUM-ConfigureRumID)
+ [啟用 CloudWatch RUM 應用程式監視器以反壓縮 JavaScript 堆疊追蹤](#CloudWatch-RUM-unminifyjavascript)
+ [在 RUM 主控台中檢視未壓縮的堆疊追蹤](#CloudWatch-RUM-viewunminifiedstacktraces)
+ [在 CloudWatch Logs 中檢視未壓縮的堆疊追蹤](#CloudWatch-RUM-viewunminifiedstacktracesCWL)
+ [對來源映射進行疑難排解](#CloudWatch-RUM-troubleshootsourcemaps)
## 設定 Amazon S3 儲存貯體資源政策以允許 RUM 服務存取
請確定您的 Amazon S3 儲存貯體與 RUM appMonitor 位於相同的區域。設定 Amazon S3 儲存貯體以允許 RUM 服務存取，從而擷取來源映射檔案。包含 `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 套件，以在壓縮期間產生來源映射。當您建置應用程式時，套件會建立目錄 (例如 dist)，其中包含已壓縮的 JavaScript 檔案及其對應的來源映射。如需範例，請參閱下列內容。
```
./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 Web 用戶端中設定 releaseId
CloudWatch RUM 使用設定的 `releaseId` 來判斷資料夾，以擷取來源映射檔案。將 `releaseId` 的名稱設定為與您的來源映射檔案資料夾相同。如果您使用上述或類似的 bash 指令碼，則指令碼中設定的 `releaseId` 應與 CloudWatch RUM Web 用戶端中設定的相同。若要新增自訂中繼資料，必須使用 1.21.0 或更高版本的 CloudWatch RUM Web 用戶端。
```
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 Web 用戶端中設定的 `releaseId` 來部署 Web 應用程式後，請選取 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 | 單位 | Description |
| --- | --- | --- |
| UnminifyLineFailureCount | 計數 | JS 錯誤事件中無法取消壓縮的堆疊追蹤行計數。有關失敗的其他詳細資訊將新增到 event\_details.unminifiedStack 欄位中失敗的特定行。 |
| UnminifyLineSuccessCount | 計數 | JS 錯誤事件中已成功取消壓縮的堆疊追蹤行計數。 |
| UnminifyEventFailureCount | 計數 | 未壓縮任何行的 JS 錯誤事件計數。有關失敗的其他詳細資訊將新增到 event\_details.unminifiedStack 欄位。 |
| UnminifyEventSuccessCount | 計數 | 至少有一個堆疊追蹤行取消壓縮成功的 JS 錯誤事件計數。 |
CloudWatch RUM 可能會因各種原因而無法反壓縮堆疊追蹤中的一行，包括但不限於：
+ 由於許可問題，無法擷取對應的來源映射檔案。請確定儲存貯體資源政策已正確設定。
+ 對應的來源映射檔案不存在。請確定來源映射檔案已上傳至與 CloudWatch RUM Web 用戶端中設定的 releaseId 同名的正確儲存貯體或資料夾。
+ 對應的來源映射檔案太大。將您的來源程式碼分割成較小的區塊。
+ 已針對堆疊追蹤擷取的 50 MB 來源映射檔案。將堆疊追蹤長度縮短為 50 MB 是服務端限制。
+ 來源映射無效，無法編製索引。確定來源映射是遵循來源映射 V3 規格所定義結構的純 JSON，並包含下列欄位：版本、檔案、來源、名稱、映射。
+ 來源映射無法將已壓縮的來源程式碼映射回未壓縮的堆疊追蹤。確定來源映射是指定 releaseId 的正確來源映射。