# カスタムメタデータを指定する
<a name="CloudWatch-RUM-custom-metadata"></a>

CloudWatch RUM は、メタデータとして各イベントに追加データをアタッチします。イベントメタデータはキーと値のペアの形式の属性で構成されます。これらの属性を使用して、CloudWatch RUM コンソールでイベントを検索またはフィルタリングできます。デフォルトでは、CloudWatch RUM はいくつかのメタデータを自動的に作成します。デフォルトメタデータの詳細については、「[RUM イベントのメタデータ](CloudWatch-RUM-datacollected.md#CloudWatch-RUM-datacollected-metadata)」を参照してください。

また、CloudWatch RUM ウェブクライアントを使用して、CloudWatch RUM イベントにカスタムメタデータを追加することもできます。カスタムメタデータには、セッション属性とページ属性を含めることができます。

カスタムメタデータを追加するには、CloudWatch RUM ウェブクライアントのバージョン 1.10.0 以降を使用する必要があります。

## 要件と構文
<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`

**注記**  
CloudWatch RUM は、属性に無効なキーまたは値が含まれている場合、またはイベントあたりのカスタム属性の上限 10 個に既に達している場合、RUM イベントからカスタム属性を削除します。

## セッション属性を追加する
<a name="CloudWatch-RUM-session-attributes"></a>

カスタムセッション属性を設定すると、セッション内のすべてのイベントに追加されます。セッション属性は、CloudWatch RUM ウェブクライアントの初期化中または実行時に `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 ウェブクライアントの初期化中または実行時に `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]** (保存済みのフィルター) ドロップダウンに保存されます。保存したフィルターを削除することもできます。