指定自訂中繼資料 - Amazon CloudWatch
要求與語法新增工作階段屬性新增頁面屬性在主控台中依中繼資料屬性進行篩選

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

指定自訂中繼資料

CloudWatch RUM 附加額外的數據作為元數據的每個事件。事件中繼資料是由鍵-值對形式的屬性組成。您可以使用這些屬性來搜尋或篩選 CloudWatch RUM 主控台中的事件。根據預設， CloudWatch RUM 會為您建立一些中繼資料。如需有關預設中繼資料的詳細資訊，請參閱 RUM 事件中繼資料。

您也可以使用 CloudWatch RUM 網頁用戶端，將自訂中繼資料新增至 CloudWatch RUM 事件。自訂中繼資料可以包含工作階段屬性和頁面屬性。

若要新增自訂中繼資料，您必須使用 CloudWatch RUM 網頁用戶端的 1.10.0 版或更新版本。

要求與語法

每個事件可以在中繼資料中包含多達 10 個自訂屬性。自訂屬性的語法要求如下：

  • 鍵

    • 最多 128 個字元。

    • 可以包含英數字元、冒號 (:) 和底線 (_)。

    • 開頭不能是 aws:。

    • 不能完全由下一節中列出的任何保留關鍵字組成。可以將這些關鍵字用作鍵名稱的一部分。

  • Values (數值)

    • 最多 256 個字元。

    • 必須是字串、數字或布林值

保留的關鍵字

您不能使用下列保留關鍵字作為完整鍵名稱。您可以使用下列關鍵字作為鍵名稱的一部分，例如 applicationVersion。

  • browserLanguage

  • browserName

  • browserVersion

  • countryCode

  • deviceType

  • domain

  • interaction

  • osName

  • osVersion

  • pageId

  • pageTags

  • pageTitle

  • pageUrl

  • parentPageId

  • platformType

  • referrerUrl

  • subdivisionCode

  • title

  • url

  • version

注意

CloudWatch 如果屬性包含無效的索引鍵或值，或者已達到每個事件 10 個自訂屬性的限制，則 RUM 會從 RUM 事件移除自訂屬性。

新增工作階段屬性

如果您設定自訂工作階段屬性，屬性會新增至工作階段中的所有事件。您可以在 CloudWatch RUM Web 用戶端初始化期間或執行階段使用addSessionAttributes命令來設定工作階段屬性。

例如，您可以將應用程式的版本新增為工作階段屬性。然後，在 CloudWatch RUM 主控台中，您可以依版本篩選錯誤，以找出提高的錯誤率是否與應用程式的特定版本相關聯。

在初始化期間新增工作階段屬性 (NPM 範例)

粗體的程式碼區段會新增工作階段屬性。

import { AwsRum, AwsRumConfig } from 'aws-rum-web';

try {
  const config: AwsRumConfig = {
    allowCookies: true,
    endpoint: "https://dataplane.rum.us-west-2.amazonaws.com",
    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
    identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
    sessionSampleRate: 1,
    telemetries: ['errors', 'performance'],
    sessionAttributes: {
        applicationVersion: "1.3.8"
    }
  };

  const APPLICATION_ID: string = '00000000-0000-0000-0000-000000000000';
  const APPLICATION_VERSION: string = '1.0.0';
  const APPLICATION_REGION: string = 'us-west-2';

  const awsRum: AwsRum = new AwsRum(
    APPLICATION_ID,
    APPLICATION_VERSION,
    APPLICATION_REGION,
    config
  );
} catch (error) {
  // Ignore errors thrown during CloudWatch RUM web client initialization
}

在執行階段期間新增工作階段屬性 (NPM 範例)

awsRum.addSessionAttributes({ 
    applicationVersion: "1.3.8"    
})

在初始化期間新增工作階段屬性 (內嵌指令碼範例)

粗體的程式碼區段會新增工作階段屬性。

<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',
        {
            sessionSampleRate:1,
            guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth',
            identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',
            endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',
            telemetries:['errors','http','performance'],
            allowCookies:true,
            sessionAttributes: {
                applicationVersion: "1.3.8"
            }
        }
    );
</script>

在執行階段期間新增工作階段屬性 (內嵌指令碼範例)

<script>
    function addSessionAttribute() {
        cwr('addSessionAttributes', {
            applicationVersion: "1.3.8"
        })
    }
            
</script>

新增頁面屬性

如果您設定自訂頁面屬性，這些屬性會新增至目前頁面上的所有事件。您可以在 CloudWatch RUM Web 用戶端初始化期間或在執行階段使用recordPageView命令來設定頁面屬性。

例如，您可以新增頁面範本作為頁面屬性。然後，在 CloudWatch RUM 主控台中，您可以依頁面範本篩選錯誤，以找出增加的錯誤率是否與應用程式的特定頁面範本相關聯。

在初始化期間新增頁面屬性 (NPM 範例)

粗體的程式碼區段會新增頁面屬性。

const awsRum: AwsRum = new AwsRum(
    APPLICATION_ID,
    APPLICATION_VERSION,
    APPLICATION_REGION,
    { disableAutoPageView:  true // optional }
);
awsRum.recordPageView({  
    pageId:'/home',  
    pageAttributes: {
      template: 'artStudio'
    }
});
const credentialProvider = new CustomCredentialProvider();
if(awsCreds) awsRum.setAwsCredentials(credentialProvider);

在執行階段期間新增頁面屬性 (NPM 範例)

awsRum.recordPageView({ 
    pageId: '/home', 
    pageAttributes: {
        template: 'artStudio'
    } 
});

在初始化期間新增頁面屬性 (內嵌指令碼範例)

粗體的程式碼區段會新增頁面屬性。

<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',
        {
            disableAutoPageView: true //optional
        }
    );
    cwr('recordPageView', { 
       pageId: '/home',  
       pageAttributes: {
           template: 'artStudio'
       }
    });
    const awsCreds = localStorage.getItem('customAwsCreds');
    if(awsCreds) cwr('setAwsCredentials', awsCreds)
</script>

在執行階段期間新增頁面屬性 (內嵌指令碼範例)

<script>
    function recordPageView() {
        cwr('recordPageView', { 
            pageId: '/home', 
            pageAttributes: {
                template: 'artStudio'
            }
        });
    }        
</script>

在主控台中依中繼資料屬性進行篩選

若要使用任何內建或自訂中繼資料屬性篩選 CloudWatch RUM 主控台中的視覺效果，請使用搜尋列。在搜尋列中，您可以 key=value 的形式指定多達 20 個篩選條件，以套用至視覺化效果。例如，若僅要篩選 Chrome 瀏覽器的資料，您可以新增篩選條件用語 browserName=Chrome。

根據預設， CloudWatch RUM 主控台會擷取 100 個最常用的屬性索引鍵和值，以顯示在搜尋列的下拉式清單中。若要將更多中繼資料屬性新增為篩選條件用語，請在搜尋列中輸入完整的屬性鍵值。

一個篩選條件最多可包含 20 個篩選條件用語，每個應用程式監視器最多可儲存 20 個篩選條件。儲存篩選條件時，篩選條件會儲存在 Saved filters (已儲存的篩選條件) 下拉式清單中。您也可以刪除儲存的篩選條件。