# 指定自定义元数据
<a name="CloudWatch-RUM-custom-metadata"></a>

CloudWatch RUM 将额外的数据作为元数据附加到每个事件。事件元数据由键值对形式的属性组成。您可以使用这些属性在 CloudWatch RUM 控制台中搜索或筛选事件。默认情况下，CloudWatch RUM 会为您创建一些元数据。有关默认元数据的更多信息，请参阅 [RUM 事件元数据](CloudWatch-RUM-datacollected.md#CloudWatch-RUM-datacollected-metadata)。

您还可以使用 CloudWatch RUM Web 客户端将自定义元数据添加到 CloudWatch RUM 事件中。自定义元数据可以包括会话属性和页面属性。

要添加自定义元数据，必须使用 1.10.0 或更高版本的 CloudWatch RUM Web 客户端。

## 要求和语法
<a name="CloudWatch-RUM-custom-metadata-syntax"></a>

每个事件可以在元数据中包含多达 10 个自定义属性。自定义属性的语法要求如下：
+ **键**
  + 最多 128 个字符
  + 可以包含字母数字字符、冒号（:）和下划线（\_）
  + 不能以 `aws:` 开头。
  + 不能完全由以下列出的任何保留关键字组成。可以将这些关键字用作较长键名的一部分。
+ **值**
  + 最多 256 个字符
  + 必须是字符串、数字或布尔值

**保留关键字**

您不能将以下保留关键字用作完整的键名。您可以使用以下关键字作为较长键名的一部分，例如 `applicationVersion`。
+ `browserLanguage`
+ `browserName`
+ `browserVersion`
+ `countryCode`
+ `deviceType`
+ `domain`
+ `interaction`
+ `osName`
+ `osVersion`
+ `pageId`
+ `pageTags`
+ `pageTitle`
+ `pageUrl`
+ `parentPageId`
+ `platformType`
+ `referrerUrl`
+ `subdivisionCode`
+ `title`
+ `url`
+ `version`

**注意**  
如果属性包含无效的键或值，或者已经达到每个事件 10 个自定义属性的限制，则 CloudWatch RUM 会从 RUM 事件中删除自定义属性。

## 添加会话属性
<a name="CloudWatch-RUM-session-attributes"></a>

如果您配置自定义会话属性，这些属性会添加到会话的所有事件中。您可以在 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>
```

## 添加页面属性
<a name="CloudWatch-RUM-page-attributes"></a>

如果您配置自定义页面属性，这些属性会添加到当前页面上的所有事件中。您可以在 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>
```

## 在控制台中按元数据属性筛选
<a name="CloudWatch-RUM-custom-attiributes-console"></a>

要使用任何内置或自定义元数据属性在 CloudWatch RUM 控制台中筛选可视化内容，请使用搜索栏。在搜索栏中，您可以通过 **key=value** 的形式指定多达 20 个筛选词用于可视化内容。例如，如果要仅筛选 Chrome 浏览器的数据，可以添加筛选词 **browserName=Chrome**。

默认情况下，CloudWatch RUM 控制台会检索 100 个最常见的属性键和值，并将它们显示在搜索栏的下拉列表中。要添加更多元数据属性作为筛选词，请在搜索栏中输入完整的属性键和值。

一个筛选条件可以包含多达 20 个筛选词，每个应用程序监视器最多可以保存 20 个筛选条件。当您保存筛选条件时，筛选条件会保存在 **Saved filters**（保存的筛选条件）下拉列表中。您还可以删除保存的筛选条件。