feat: add metadata field "aws:releaseId" (#592)

Author: williazz

docs/configuration.md

@@ -19,6 +19,7 @@ For example, the config object may look similar to the following:
 | Field Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | allowCookies | Boolean | `false` | Enable the web client to set and read two cookies: a session cookie named `cwr_s` and a user cookie named `cwr_u`.<br/><br/>`cwr_s` stores session data including an anonymous session ID (uuid v4) created by the web client. This allows CloudWatch RUM to compute sessionized metrics like errors per session.<br/><br/>`cwr_u` stores an anonymous user ID (uuid v4) created by the web client. This allows CloudWatch RUM to count return visitors.<br/><br/>`true`: the web client will use cookies<br/>`false`: the web client will not use cookies. |
+| aws:releaseId | string | `undefined` | The application release id used to find a matching source map, if any. Must match regex `^[a-zA-Z0-9_\-:/\.]{1,200}$`, including size limit 200 |
 | cookieAttributes | [CookieAttributes](#cookieattributes) | `{ domain: window.location.hostname, path: '/', sameSite: 'Strict', secure: true, unique: false } ` | Cookie attributes are applied to all cookies stored by the web client, including `cwr_s` and `cwr_u`. |
 | sessionAttributes | [MetadataAttributes](#metadataattributes) | `{}` | Session attributes will be added the metadata of all events in the session. |
 | disableAutoPageView | Boolean | `false` | When this field is `false`, the web client will automatically record page views.<br/><br/>By default, the web client records page views when (1) the page first loads and (2) the browser's [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) is called. The page ID is `window.location.pathname`.<br/><br/>In some cases, the web client's instrumentation will not record the desired page ID. In this case, the web client's page view automation must be disabled using the `disableAutoPageView` configuration, and the application must be instrumented to record page views using the `recordPageView` command. |

src/event-cache/__tests__/EventCache.integ.test.ts

@@ -118,6 +118,49 @@ describe('EventCache tests', () => {
         });
     });
 
+    test('when aws:releaseId exists then it is added to event metadata', async () => {
+        // Init
+        const EVENT1_SCHEMA = 'com.amazon.rum.event1';
+        const config = {
+            ...DEFAULT_CONFIG,
+            ...{
+                allowCookies: false,
+                sessionLengthSeconds: 0
+            },
+            'aws:releaseId': '5.2.1'
+        };
+
+        const eventCache: EventCache = Utils.createEventCache(config);
+
+        // Run
+        eventCache.recordPageView('/console/home');
+        eventCache.recordEvent(EVENT1_SCHEMA, {});
+
+        // Assert
+        const events = eventCache.getEventBatch();
+        events.forEach((event) => {
+            expect(JSON.parse(event.metadata)).toMatchObject({
+                'aws:releaseId': '5.2.1'
+            });
+        });
+    });
+
+    test('when aws:releaseId does NOT exist then it is NOT added to event metadata', async () => {
+        // Init
+        const EVENT1_SCHEMA = 'com.amazon.rum.event1';
+        const eventCache: EventCache = Utils.createEventCache(DEFAULT_CONFIG);
+
+        // Run
+        eventCache.recordPageView('/console/home');
+        eventCache.recordEvent(EVENT1_SCHEMA, {});
+
+        // Assert
+        const events = eventCache.getEventBatch();
+        events.forEach((event) => {
+            expect(JSON.parse(event.metadata)['aws:releaseId']).toBeUndefined();
+        });
+    });
+
     test('when a session is not sampled then return false', async () => {
         // Init
         const config = {

src/event-schemas/meta-data.json

@@ -9,6 +9,9 @@
             "type": "string",
             "description": "Schema version."
         },
+        "aws:releaseId": {
+            "type": "string"
+        },
         "browserLanguage": {
             "type": "string"
         },

src/orchestration/Orchestration.ts

@@ -109,6 +109,7 @@ export type PartialCookieAttributes = Partial<CookieAttributes>;
 
 export interface Config {
     allowCookies: boolean;
+    'aws:releaseId'?: string;
     batchLimit: number;
     client: string;
     clientBuilder?: ClientBuilder;

src/sessions/SessionManager.ts

@@ -32,6 +32,8 @@ export type Session = {
 };
 
 export type Attributes = {
+    // The custom release id, to match a source map
+    'aws:releaseId'?: string;
     browserLanguage: string;
     browserName: string;
     browserVersion: string;
@@ -45,8 +47,8 @@ export type Attributes = {
     platformType: string;
     // The fully qualified domain name (i.e., host name + domain name)
     domain: string;
-    // Custom attribute value types are restricted to the types: string | number | boolean
-    [k: string]: string | number | boolean;
+    // Custom attribute value types are restricted to the types: string | number | boolean | undefined
+    [k: string]: string | number | boolean | undefined;
 };
 
 /**
@@ -273,7 +275,8 @@ export class SessionManager {
             deviceType: ua.device.type ? ua.device.type : DESKTOP_DEVICE_TYPE,
             // This client is used exclusively in web applications.
             platformType: WEB_PLATFORM_TYPE,
-            domain: window.location.hostname
+            domain: window.location.hostname,
+            'aws:releaseId': this.config['aws:releaseId']
         };
     }
 

src/sessions/__integ__/SessionManager.test.ts

@@ -26,6 +26,7 @@ const OS_NAME = 'osName';
 const OS_VERSION = 'osVersion';
 const DEVICE_TYPE = 'deviceType';
 const PLATFORM_TYPE = 'platformType';
+const AWS_RELEASE_ID = 'aws:releaseId';
 
 const button1: Selector = Selector(`#${BUTTON_ID_1}`);
 
@@ -106,7 +107,9 @@ test('UserAgentMetaDataPlugin records user agent metadata', async (t: TestContro
         .expect(REQUEST_BODY.textContent)
         .contains(PLATFORM_TYPE)
         .expect(RESPONSE_STATUS.textContent)
-        .eql(STATUS_202.toString());
+        .eql(STATUS_202.toString())
+        .expect(REQUEST_BODY.textContent)
+        .notContains(AWS_RELEASE_ID);
 });
 
 test('When custom attribute set at init, custom attribute recorded in event metadata', async (t: TestController) => {

src/sessions/__tests__/SessionManager.test.ts

@@ -846,4 +846,22 @@ describe('SessionManager tests', () => {
         // Assert
         expect(actualSessionAttributes.title).toEqual(sessionAttributes.title);
     });
+
+    test('when initiated with aws:releaseId then it is in the attributes', async () => {
+        const awsReleaseId = '2.1.7';
+        const sessionManager = defaultSessionManager({
+            ...DEFAULT_CONFIG,
+            'aws:releaseId': awsReleaseId
+        });
+
+        const actualSessionAttributes = sessionManager.getAttributes();
+        expect(actualSessionAttributes['aws:releaseId']).toBe(awsReleaseId);
+    });
+
+    test('when initiated without aws:releaseId then it is NOT in the attributes', async () => {
+        const sessionManager = defaultSessionManager(DEFAULT_CONFIG);
+
+        const actualSessionAttributes = sessionManager.getAttributes();
+        expect(actualSessionAttributes['aws:releaseId']).toBeUndefined();
+    });
 });