本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定 Web 應用程式以使用 CloudWatch RUM
<a name="CloudWatch-RUM-get-started"></a>

使用這些區段中的步驟來設定 Web 應用程式，以開始使用 CloudWatch RUM 從實際使用者工作階段收集效能資料。

**Topics**
+ [授權您的 Web 應用程式將資料傳送至 AWS](CloudWatch-RUM-get-started-authorization.md)
+ [為 Web 應用程式建立 CloudWatch RUM 應用程式監視器](CloudWatch-RUM-get-started-create-app-monitor.md)
+ [修改程式碼片段以設定 CloudWatch RUM Web 用戶端 (選用)](CloudWatch-RUM-modify-snippet.md)
+ [將 CloudWatch 應用程式監視器程式碼片段插入您的應用程式](CloudWatch-RUM-get-started-insert-code-snippet.md)
+ [透過產生使用者事件測試 CloudWatch 應用程式監視器設定](CloudWatch-RUM-get-started-generate-data.md)

# 授權您的 Web 應用程式將資料傳送至 AWS
<a name="CloudWatch-RUM-get-started-authorization"></a>

有四個設定資料身分驗證的選項：
+ 使用 Amazon Cognito，讓 CloudWatch RUM 為應用程式建立新的 Amazon Cognito 身分池。這個方法需要最少的設定工作。

  身分集區將包含未進行身分驗證的身分。這可讓 CloudWatch RUM Web 用戶端將資料傳送至 CloudWatch RUM，而無需對應用程式的使用者進行身分驗證。

  Amazon Cognito 身分集區具有連接的 IAM 角色。Amazon Cognito 未進行身分驗證的身分可讓 Web 用戶端擔任授權將資料傳送到 CloudWatch RUM 的 IAM 角色。
+ 使用 Amazon Cognito 進行身分驗證。如果您使用此功能，則可以使用現有的 Amazon Cognito 身分池，或建立新的身分集區以搭配此應用程式監視器使用。如果您使用現有的身分池，還必須修改連結至身分集區的 IAM 角色。針對支援未驗證使用者的身分池使用此選項。您只能從相同的區域使用身分池。
+ 使用您已經設定的現有身分提供者所提供的身分驗證。在此情況下，您必須從身分提供者取得憑證，且您的應用程式必須將這些憑證轉寄至 RUM Web 用戶端。

  對於僅支援已驗證使用者的身分池，請使用此選項。
+ 使用資源型政策來管理應用程式監視器的存取權。這包括在沒有 AWS 憑證的情況下，將未經驗證的請求傳送至 CloudWatch RUM 的功能。如需了解資源型政策和 RUM 的詳細資訊，請參閱 [搭配資源型政策使用 CloudWatch RUM](CloudWatch-RUM-resource-policies.md)。

以下章節更會詳細探討這些選項。

## 使用現有 Amazon Cognito 身分集區
<a name="CloudWatch-RUM-get-started-authorization-existingcognito"></a>

如果您選擇使用 Amazon Cognito 身分池，則請在將應用程式新增至 CloudWatch RUM 時指定身分集區。集區必須支援啟用對未經身分驗證之身分的存取權。您只能從相同的區域使用身分池。

您也必須將下列許可新增到連接至與此身分集區相關聯之 IAM 角色的 IAM 政策。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        { 
            "Effect": "Allow",
            "Action": [
                "rum:PutRumEvents"
            ],
            "Resource": "arn:aws:rum:us-east-1:123456789012:appmonitor/app monitor name" 
        }
    ]
}
```

------

之後，Amazon Cognito 會傳送必要的安全字符，讓您的應用程式能夠存取 CloudWatch RUM。

## 第三方供應商
<a name="CloudWatch-RUM-get-started-authorization-thirdparty"></a>

如果您選擇使用第三方供應商的私有身分驗證，則必須從身分提供者取得憑證，並將其轉寄至 AWS。最好的方法是使用*安全字符廠商*。您可以使用任何安全字符廠商，包括 Amazon Cognito AWS Security Token Service。如需 的詳細資訊 AWS STS，請參閱[歡迎使用 AWS Security Token Service API 參考](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)。

如果您想要在此案例中使用 Amazon Cognito 作為字符廠商，則可以將 Amazon Cognito 設定為與身分驗證供應商一起使用。如需詳細資訊，請參閱 [Amazon Cognito 身分集區 (聯合身分) 入門](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-identity-pools.html)。

將 Amazon Cognito 設定為與身分提供者一起使用後，您還需要執行下列動作：
+ 建立具備下列許可的 IAM 角色。您的應用程式將使用此角色來存取 AWS。

------
#### [ JSON ]

****  

  ```
  { 
   "Version":"2012-10-17",		 	 	 
   "Statement": [ 
     { 
       "Effect": "Allow",
       "Action": "rum:PutRumEvents",
       "Resource": "arn:aws:rum:us-east-2:123456789012:appmonitor/AppMonitorName"
     }
   ]
  }
  ```

------
+ 將以下內容新增至您的應用程式，讓其將憑證從您的供應商傳遞至 CloudWatch RUM。插入該行，以便在使用者登入您的應用程式，並且應用程式已收到用於存取 AWS的憑證後執行。

  ```
  cwr('setAwsCredentials', {/* Credentials or CredentialProvider */});
  ```

如需 AWS JavaScript SDK 中登入資料提供者的詳細資訊，請參閱適用於 JavaScript 的 v3 開發人員指南中的在 [Web 瀏覽器中設定登入](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-browser.html)資料、適用於 JavaScript 的 SDK 的 v2 開發人員指南中的在 [Web 瀏覽器中設定登入資料](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-browser.html)、 和 [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers)。

您也可以使用適用於 CloudWatch RUM Web 用戶端的 SDK 來設定 Web 用戶端身分驗證方法。如需有關 Web 用戶端 SDK 的詳細資訊，請參閱 [CloudWatch RUM Web 用戶端 SDK](https://github.com/aws-observability/aws-rum-web)。

# 為 Web 應用程式建立 CloudWatch RUM 應用程式監視器
<a name="CloudWatch-RUM-get-started-create-app-monitor"></a>

若要開始搭配應用程式使用 CloudWatch RUM，您可以建立*應用程式監控*。建立應用程式監視器時，RUM 會產生程式碼片段，供您貼入應用程式。程式碼片段會提取 RUM 用戶端程式碼。RUM 用戶端會從應用程式的使用者工作階段擷取資料，並將其傳送至 RUM。

## 為 Web 平台建立應用程式監控
<a name="web-platform-app-monitor"></a>

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在導覽窗格中，依次選擇 **Application Signals**、**RUM**。

1. 選擇 **Add app monitor** (新增應用程式監控)。

1. 對於 **App monitor name** (應用程式監控名稱)，輸入用於在 CloudWatch RUM 主控台內識別此應用程式監控的名稱。

1. 選取 **Web** 做為平台。

1. 對於**應用程式網域**，輸入您應用程式擁有管理授權的註冊網域名稱。也可以使用萬用字元 `*` 來允許任何子網域或頂層網域 (例如 \$1.amazon.com、amazon.\$1、\$1.amazon.\$1)。

1. 對於 **Configure RUM data collection** (設定 RUM 資料收集)，指定是否要應用程式監控來收集下列各項：
   + **Performance telemetry** (效能遙測) – 收集頁面載入和資源載入時間的相關資訊
   + **JavaScript errors** (JavaScript 錯誤) – 收集您應用程式所引發之未處理 JavaScript 錯誤的相關資訊

     您可以選取**取消壓縮 JavaScript 錯誤堆疊追蹤**，以偵錯未壓縮的 JavaScript 錯誤。若要使用此功能，請將來源映射檔案上傳至 Amazon S3 儲存貯體或資料夾，並提供 Amazon S3 URI。啟用後，RUM 將使用這些來源映射，並透過新增未壓縮堆疊追蹤來豐富 JavaScript 錯誤事件。請注意，啟用後，此功能只會處理新的 JavaScript 錯誤事件，無法用於先前收集的資料。如需詳細資訊，請參閱[啟用 JavaScript 錯誤堆疊追蹤的反壓縮功能](CloudWatch-RUM-JavaScriptStackTraceSourceMaps.md)。
   + **HTTP errors** (HTTP 錯誤) – 收集應用程式所擲回之 HTTP 錯誤的相關資訊

   選取這些選項可提供有關應用程式的更多資訊，但也會產生更多 CloudWatch RUM 事件，並因此會產生更多費用。

   如果您沒有選取任何這些項目，則應用程式監控仍會收集工作階段啟動事件和頁面 ID，以便查看有多少使用者正在使用您的應用程式，包括依作業系統類型和版本、瀏覽器類型和版本、裝置類型和位置劃分的明細內容。

1. 如果您希望能夠從取樣的使用者工作階段中收集使用者 ID 和工作階段 ID，則選擇 **Check this option to allow the CloudWatch RUM Web Client to set cookies** (核取此選項以允許 CloudWatch RUM Web 用戶端設定 Cookie)。使用者 ID 是由 RUM 隨機產生。如需詳細資訊，請參閱[CloudWatch RUM Web 用戶端 Cookie (或類似技術)](CloudWatch-RUM-privacy.md#CloudWatch-RUM-cookies)。

1. 對於 **Session samples** (工作階段範例)，輸入會用於收集 RUM 資料的使用者工作階段百分比。預設為 100%。減少此數量會讓您減少資料，但也會降低費用。如需有關 RUM 定價的詳細資訊，請參閱 [RUM 定價](CloudWatch-RUM.md#RUMpricing)。

1. 您為 CloudWatch RUM 收集的最終使用者資料會保留 30 天，然後刪除。如果您想要在 CloudWatch Logs 中保留 RUM 事件的複本，並設定保留這些複本的時間，則請選擇 **Data storage** (資料儲存) 下的 **Check this option to store your application telemetry data in your CloudWatch Logs account** (核取此選項將應用程式遙測資料存放在 CloudWatch Logs 帳戶中)。根據預設，CloudWatch Logs 日誌群組會保留資料 30 天。您可以在 CloudWatch Logs 主控台中調整保留期間。

1. (選用) 選擇將資源型政策新增至應用程式監視器，以控制誰可以將 `PutRumEvents` 請求傳送至應用程式監視器。如果您選擇**建立公有政策**，資源政策會連結到您的應用程式監視器，讓任何人都能將 `PutRumEvents` 請求傳送到應用程式監視器。如需有關此方法的詳細資訊，請參閱 [搭配資源型政策使用 CloudWatch RUM](CloudWatch-RUM-resource-policies.md)。

1. 如果您在上一個步驟中連接以資源為基礎的政策，則不需要使用 AWS 登入資料簽署對 CloudWatch RUM 的請求，而且您可以略過設定授權。否則，對於**授權**，請指定要使用新的或現有的 Amazon Cognito 身分池，還是使用不同的身分提供者。建立新的身分集區是不需要其他設定步驟的最簡單選項。如需詳細資訊，請參閱[授權您的 Web 應用程式將資料傳送至 AWS](CloudWatch-RUM-get-started-authorization.md)。

   建立新的 Amazon Cognito 身分集區需要管理許可。如需詳細資訊，請參閱[使用 CloudWatch RUM 的 IAM 政策](CloudWatch-RUM-permissions.md)。

1. (選用) 根據預設，當您將 RUM 程式碼片段新增至應用程式時，Web 用戶端會將 JavaScript 標籤插入以監控應用程式所有頁面之 HTML 程式碼中的使用情況。若要變更此選項，請選擇 **Configure pages** (設定頁面)，然後選擇 **Include only these pages** (僅包含這些頁面) 或 **Exclude these pages** (排除這些頁面)。然後，指定要包含或排除的頁面。若要指定要包含或排除的頁面，請輸入其完整 URL。若要指定其他頁面，請選擇 **Add URL** (新增網址)。

1. 若要啟用應用程式監視器取樣之使用者工作階段的 AWS X-Ray 追蹤，請選擇**主動追蹤**，然後選取**使用 追蹤我的服務 AWS X-Ray。**

   如果您選取此選項，則會追蹤由應用程式監控取樣的使用者工作階段期間所發出的 `XMLHttpRequest` 和 `fetch` 請求。然後，您可以在 RUM 儀表板、X-Ray 追蹤地圖以及追蹤詳細資訊頁面中查看這些使用者工作階段的追蹤和區段。在為應用程式啟用它之後，這些使用者工作階段也會在 [Application Signals](CloudWatch-Application-Monitoring-Sections.md) 中顯示為用戶端頁面。

   透過對 CloudWatch RUM Web 用戶端進行其他組態變更，您可以將 X-Ray 追蹤標頭新增至 HTTP 請求，以啟用end-to-end追蹤。 AWS 如需詳細資訊，請參閱[啟用 X-Ray 端對端追蹤](CloudWatch-RUM-modify-snippet.md#CloudWatch-RUM-xraytraceheader)。

1. (選用) 若要新增標籤至應用程式監控，請選擇 **Tags** (標籤)、**Add new tag** (新增標籤)。

   之後，在 **Key** (索引鍵) 中，輸入標籤的名稱。您可以在 **Value (值)** 中為標籤新增選用值。

   若要新增另一個標籤，請再次選擇 **Add new tag** (新增標籤)。

   如需詳細資訊，請參閱[標記 AWS 資源](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html)。

1. 選擇 **Add app monitor** (新增應用程式監控)。

1. 在 **Sample code** (範本程式碼) 區段中，您可以複製程式碼片段，以便新增至應用程式中。建議您選擇 **JavaScript** 或 **TypeScript**，並使用 NPM 安裝 CloudWatch RUM Web 用戶端，作為 JavaScript 模組。

   或者，您可以選擇 **HTML** 以使用內容交付網路 (CDN) 安裝 CloudWatch RUM Web 用戶端。使用 CDN 的缺點是 Web 用戶端通常會遭廣告封鎖程式封鎖。

1. 選擇 **Copy** (複製) 或 **Download** (下載)，然後選擇 **Done** (完成)。

# 修改程式碼片段以設定 CloudWatch RUM Web 用戶端 (選用)
<a name="CloudWatch-RUM-modify-snippet"></a>

您可以在將程式碼片段插入應用程式之前修改程式碼片段，以啟用或停用數個選項。如需詳細資訊，請參閱 [CloudWatch RUM Web 用戶端文件](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md)。

有四個您應該務必注意到的組態選項，如這些章節所述。

## 防止收集可能包含個人資訊的資源 URL
<a name="CloudWatch-RUM-resourceURL"></a>

根據預設，CloudWatch RUM Web 用戶端會設定為記錄應用程式所下載的資源 URL。這些資源包括 HTML 檔案、映像、CSS 檔案、JavaScript 檔案等。對於某些應用程式，URL 可能包含個人身分識別資訊 (PII)。

如果您的應用程式發生這種情況，強烈建議您透過在程式碼片段組態中設定 `recordResourceUrl: false` 來停用資源 URL 收集，之後再將其插入到您的應用程式中。

## 手動記錄頁面檢視
<a name="CloudWatch-RUM-pageload"></a>

預設情況下，Web 用戶端會記錄頁面第一次載入時，以及呼叫瀏覽器歷史記錄 API 時的頁面檢視次數。預設頁面 ID 為 `window.location.pathname`。但在某些情況下，您可以覆寫此行為並檢測應用程式，進而以程式設計方式記錄頁面檢視。這樣做可讓您控制頁面 ID 以及其記錄時間。舉例來說，假設 Web 應用程式的 URI 具有變數識別符，例如 `/entity/123` 或 `/entity/456`。依預設，CloudWatch RUM 會為每個 URI 產生頁面檢視事件，其中包含與路徑名稱相符的不同頁面 ID，但您可以依相同的頁面 ID 將其進行分組。若要完成此操作，請使用 `disableAutoPageView` 組態停用 Web 客戶端的頁面檢視自動化，然後使用 `recordPageView` 命令設定所需的頁面 ID。如需詳細資訊，請參閱 GitHub 上的[應用程式特定組態](https://github.com/aws-observability/aws-rum-web/blob/main/docs/configuration.md)。

**內嵌指令碼範例：**

```
cwr('recordPageView', { pageId: 'entityPageId' });
```

**JavaScript 模組範例：**

```
awsRum.recordPageView({ pageId: 'entityPageId' });
```

## 啟用 X-Ray 端對端追蹤
<a name="CloudWatch-RUM-xraytraceheader"></a>

當您建立應用程式監控時，選取 **Trace my service with AWS X-Ray** (使用 追蹤我的服務) 會啟用對應用程式監控取樣之使用者工作階段期間所提出 `XMLHttpRequest` 和 `fetch` 請求的追蹤。然後，您可以在 CloudWatch RUM 儀表板、X-Ray 追蹤地圖以及追蹤詳細資訊頁面中查看這些 HTTP 請求的追蹤。

根據預設，這些用戶端追蹤不會連線到下游伺服器端追蹤。若要將用戶端追蹤連線至伺服器端追蹤並啟用端對端追蹤，請在 Web 用戶端中將 `addXRayTraceIdHeader` 選項設定為 `true`。這會導致 CloudWatch RUM Web 用戶端將 X-Ray 追蹤標頭新增至 HTTP 請求。

下列程式碼區塊會顯示新增用戶端追蹤的範例。為了便於閱讀，此範例會省略某些組態選項。

```
<script>
    (function(n,i,v,r,s,c,u,x,z){...})(
        'cwr',
        '00000000-0000-0000-0000-000000000000',
        '1.0.0',
        'us-west-2',
        'https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',
        {
            enableXRay: true,
            telemetries: [ 
                'errors', 
                'performance',
                [ 'http', { addXRayTraceIdHeader: true } ]
            ]
        }
    );
</script>
```

**警告**  
將 CloudWatch RUM Web 用戶端設定為將 X-Ray 追蹤標頭新增至 HTTP 請求，可能會導致跨來源資源共用 (CORS) 失敗或導致使用 SigV4 簽署的請求簽章無效。如需詳細資訊，請參閱 [CloudWatch RUM Web 用戶端文件](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md)。強烈建議您在生產環境中新增用戶端 X-Ray 追蹤標頭之前，先測試您的應用程式。

如需詳細資訊，請參閱 [CloudWatch RUM Web 用戶端文件](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md#http)

## 將未簽署的請求傳送至 CloudWatch RUM
<a name="CloudWatch-RUM-unsigned"></a>

根據預設，RUM Web 用戶端會簽署傳送至 RUM 的所有請求。如果您在用戶端組態中設定 `signing:false`，請求會在傳送至 CloudWatch RUM 時取消簽署。只有在應用程式監視器上連結以公有資源為基礎的政策時，資料才會擷取至 RUM。如需詳細資訊，請參閱[搭配資源型政策使用 CloudWatch RUM](CloudWatch-RUM-resource-policies.md)。

# 將 CloudWatch 應用程式監視器程式碼片段插入您的應用程式
<a name="CloudWatch-RUM-get-started-insert-code-snippet"></a>

接下來，您會將上一節所建立的程式碼片段插入您的應用程式。

**警告**  
由程式碼片段下載和設定的 Web 用戶端會使用 Cookie (或類似技術) 來協助您收集最終使用者資料。插入程式碼片段之前，請參閱 [在主控台中依中繼資料屬性進行篩選使用 CloudWatch RUM 的資料保護和資料隱私權](CloudWatch-RUM-privacy.md)。

如果您沒有先前產生的程式碼片段，則可以透過 [如何找到我已經產生的程式碼片段？](CloudWatch-RUM-find-code-snippet.md) 中的以下指示找到。

**將 CloudWatch RUM 程式碼片段插入您的應用程式**

1. 將您在上一節中複製或下載的程式碼片段插入應用程式的 `<head>` 元素。將程式碼片段插入 `<body>` 元素或任何其他 `<script>` 標籤。

   以下是所產生程式碼片段的範例。

   ```
   <script>
   (function (n, i, v, r, s, c, x, z) {
       x = window.AwsRumClient = {q: [], n: n, i: i, v: v, r: r, c: c};
       window[n] = function (c, p) {
           x.q.push({c: c, p: p});
       };
       z = document.createElement('script');
       z.async = true;
       z.src = s;
       document.head.insertBefore(z, document.getElementsByTagName('script')[0]);
   })('cwr',
       '194a1c89-87d8-41a3-9d1b-5c5cd3dafbd0',
       '1.0.0',
       'us-east-2',
       'https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',
       {
           sessionSampleRate: 1,
           identityPoolId: "us-east-2:c90ef0ac-e3b8-4d1a-b313-7e73cfd21443",
           endpoint: "https://dataplane.rum.us-east-2.amazonaws.com",
           telemetries: ["performance", "errors", "http"],
           allowCookies: true,
           enableXRay: false
       });
   </script>
   ```

1. 如果您的應用程式是多頁面 Web 應用程式，則您必須針對要包含在資料收集中的每個 HTML 頁面重複步驟 1。

# 透過產生使用者事件測試 CloudWatch 應用程式監視器設定
<a name="CloudWatch-RUM-get-started-generate-data"></a>

插入程式碼片段且已更新的應用程式正在執行之後，您可以手動產生使用者事件來對其進行測試。為了對此進行測試，建議您進行下列動作。這項測試會產生標準 CloudWatch RUM 費用。
+ 在 Web 應用程式中的頁面之間導航。
+ 使用不同的瀏覽器和裝置建立多個使用者工作階段。
+ 提出請求。
+ 導致 JavaScript 錯誤。

產生某些事件之後，請在 CloudWatch RUM 儀表板中檢視這些事件。如需詳細資訊，請參閱[檢視 CloudWatch RUM 儀表板](CloudWatch-RUM-view-data.md)。

來自使用者工作階段的資料最多可能需要 15 分鐘才會顯示在儀表板中。

如果您在應用程式中產生事件 15 分鐘後看不到資料，則請參閱 [對 CloudWatch RUM 進行疑難排解](CloudWatch-RUM-troubleshooting.md)。