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

williazz · limhjgrace · web-flow · commit c8bc3bed54e0 · 2025-04-09T17:23:38.000-07:00
Co-authored-by: Grace Lim &lt;limhye@amazon.com&gt;
diff --git a/app/smoke.html b/app/smoke.html
@@ -34,7 +34,8 @@
                 telemetries: ['performance', 'errors', 'http', 'interaction'],
                 allowCookies: true,
                 enableXRay: true,
-                useBeacon: false
+                useBeacon: false,
+                releaseId: '2.1.7'
             });
         </script>
 
diff --git a/docs/configuration.md b/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. |
+| releaseId | String | `undefined` | The releaseId will be used to retrieve source map(s), if any, when RUM service unminifies JavaScript error stack traces. It should be unique to each application release and match regex ^[a-zA-Z0-9_\-:/\.]{1,200}$, including size limit of 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. |
diff --git a/smoke/smoke-test-application-CDN/smoke.html b/smoke/smoke-test-application-CDN/smoke.html
@@ -39,7 +39,8 @@
                     'x-api-key': 'a1b2c3d4e5f6',
                     'content-type': 'application/json'
                 },
-                useBeacon: false
+                useBeacon: false,
+                releaseId: '2.1.7'
             });
         </script>
 
diff --git a/smoke/smoke-test-application-NPM-ES/src/loader-npm-rum-2.ts b/smoke/smoke-test-application-NPM-ES/src/loader-npm-rum-2.ts
@@ -14,7 +14,8 @@ try {
         cookieAttributes: {
             unique: true
         },
-        useBeacon: false
+        useBeacon: false,
+        releaseId: '2.1.7'
     };
 
     const APPLICATION_ID: string = $MONITOR_ID_2;
diff --git a/smoke/smoke-test-application-NPM-ES/src/loader-npm-rum.ts b/smoke/smoke-test-application-NPM-ES/src/loader-npm-rum.ts
@@ -21,7 +21,8 @@ try {
             'x-api-key': 'a1b2c3d4e5f6',
             'content-type': 'application/json'
         },
-        useBeacon: false
+        useBeacon: false,
+        releaseId: '2.1.7'
     };
 
     const APPLICATION_ID: string = $MONITOR_ID;
diff --git a/src/__smoke-test__/ingestion-integ.spec.ts b/src/__smoke-test__/ingestion-integ.spec.ts
@@ -422,6 +422,19 @@ test('when event with custom attributes is sent then the event is ingested', asy
     const pageViews = getEventsByType(requestBody, PAGE_VIEW_EVENT_TYPE);
     const eventIds = getEventIds(pageViews);
 
+    const customAttributes = [
+        'customAttributeKeyAtRuntime1=customAttributeValueAtRuntime1',
+        'customAttributeKeyAtRuntime2=customAttributeValueAtRuntime2',
+        'custom_attribute_key_at_runtime=customAttributeValueAtRuntime',
+        'valid:customAttributeKeyAtRuntime=customAttributeValueAtRuntime'
+    ];
+
+    const additionalMetadataAttributes = ['aws:releaseId=2.1.7'];
+    const expectedMetadataAttributes = [
+        ...customAttributes,
+        ...additionalMetadataAttributes
+    ];
+
     // One initial load, one route change
     expect(eventIds.length).toEqual(2);
     const isIngestionCompleted = await verifyIngestionWithRetry(
@@ -430,12 +443,7 @@ test('when event with custom attributes is sent then the event is ingested', asy
         timestamp,
         MONITOR_NAME,
         5,
-        [
-            'customAttributeKeyAtRuntime1=customAttributeValueAtRuntime1',
-            'customAttributeKeyAtRuntime2=customAttributeValueAtRuntime2',
-            'custom_attribute_key_at_runtime=customAttributeValueAtRuntime',
-            'valid:customAttributeKeyAtRuntime=customAttributeValueAtRuntime'
-        ]
+        expectedMetadataAttributes
     );
     expect(isIngestionCompleted).toEqual(true);
 });
diff --git a/src/event-cache/__tests__/EventCache.integ.test.ts b/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
+            },
+            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 = {
diff --git a/src/event-schemas/meta-data.json b/src/event-schemas/meta-data.json
@@ -9,6 +9,9 @@
             "type": "string",
             "description": "Schema version."
         },
+        "aws:releaseId": {
+            "type": "string"
+        },
         "browserLanguage": {
             "type": "string"
         },
diff --git a/src/orchestration/Orchestration.ts b/src/orchestration/Orchestration.ts
@@ -110,6 +110,7 @@ export type PartialCookieAttributes = Partial<CookieAttributes>;
 
 export interface Config {
     allowCookies: boolean;
+    releaseId?: string;
     batchLimit: number;
     client: string;
     clientBuilder?: ClientBuilder;
diff --git a/src/sessions/SessionManager.ts b/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.releaseId
         };
     }
 
diff --git a/src/sessions/__integ__/SessionManager.test.ts b/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) => {
diff --git a/src/sessions/__tests__/SessionManager.test.ts b/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 releaseId = '2.1.7';
+        const sessionManager = defaultSessionManager({
+            ...DEFAULT_CONFIG,
+            releaseId
+        });
+
+        const actualSessionAttributes = sessionManager.getAttributes();
+        expect(actualSessionAttributes['aws:releaseId']).toBe(releaseId);
+    });
+
+    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();
+    });
 });
diff --git a/src/test-utils/smoke-test-utils.ts b/src/test-utils/smoke-test-utils.ts
@@ -177,7 +177,7 @@ export const expectEvents = async (
     return true;
 };
 
-/** Returns true when expected custom attributes are found */
+/** Returns true when expected metadata attributes are found */
 export const expectValidAttributes = async (
     ingestedEvents: Map<string, string[]>,
     eventIds: string[],
@@ -192,7 +192,7 @@ export const expectValidAttributes = async (
     return true;
 };
 
-/** Returns true when no invalid custom attributes are found */
+/** Returns true when no invalid metadata attributes are found */
 export const expectInvalidAttributes = async (
     ingestedEvents: Map<string, string[]>,
     eventIds: string[],
