# 사용자 지정 메타데이터 지정
<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 이벤트에 사용자 지정 메타데이터를 추가할 수도 있습니다. 사용자 지정 메타데이터는 세션 속성과 페이지 속성을 포함할 수 있습니다.

사용자 지정 메타데이터를 추가하려면 버전 1.10.0 이상의 CloudWatch RUM 웹 클라이언트를 사용해야 합니다.

## 요구 사항 및 구문
<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**(저장된 필터) 드롭다운에 저장됩니다. 저장된 필터를 삭제할 수도 있습니다.