telemetry(vscode): MetricBase.reasonDesc #764

Problem:
In the generated `telemetry.gen.ts` for vscode toolkit, `MetricBase`
does not have various common fields. This adds friction when setting
these fields.

Solution:
Update the generator to define `MetricBase.reasonDesc`.

Author: justinmk3

buildspec/nodeTests.yml

@@ -3,7 +3,7 @@ version: 0.2
 phases:
     install:
         runtime-versions:
-            nodejs: 14
+            nodejs: 22
 
     build:
         commands:

telemetry/vscode/README.md

@@ -6,11 +6,21 @@ This package contains scripts and files to generate telemetry calls for:
 
 ## Usage
 
-To generate telemetry for VSCode, install this package in your package.json, then run:
+To generate telemetry and see the result:
 
-`node node_modules/@aws-toolkits/telemetry/lib/generateTelemetry.js --output=<path/to/file>.ts`
+1. run `npm run build` to produce the `lib/` dir.
+2. run:
+   ```
+   node ./lib/generateTelemetry.js --output=telemetry.gen.ts
+   ```
+    - The script has two arguments:
+        1. `--extraInput` list of paths to telemetry JSON files, seperated by commas. For example, "--extraInput=abc.json,/abc/bcd.json"
+        2. `--output` path where the final output will go. For example, "--output=abc.ts"
 
-The script has two arguments:
+To generate telemetry for VSCode from a downstream project,
 
-1. `--extraInput` accepts lists of paths to telemetry JSON files, seperated by commas. For example, "--extraInput=abc.json,/abc/bcd.json"
-2. `--output` accepts one path which represents where the final output will go. For example, "--output=abc.ts"
+1. install this package in your package.json
+2. run:
+   ```
+   node node_modules/@aws-toolkits/telemetry/lib/generateTelemetry.js --output=<path/to/file>.ts
+   ```

telemetry/vscode/src/generate.ts

@@ -114,7 +114,7 @@ function getTypeOrThrow(types: MetadataType[] = [], name: string) {
 }
 
 const baseName = 'MetricBase'
-const commonMetadata = ['result', 'reason', 'duration']
+const commonMetadata = ['result', 'reason', 'reasonDesc', 'duration']
 const passive: PropertySignatureStructure = {
     isReadonly: true,
     hasQuestionToken: true,

telemetry/vscode/test/generator.test.ts

@@ -13,15 +13,15 @@ describe('Generator', () => {
         tempDir = tmpdir()
     })
 
-    test('Generate fails when validation fails', async () => {
+    test('validation', async () => {
         await expect(testGenerator(['resources/invalidInput.json'], '/invalid/file/path')).rejects.toBeDefined()
     })
 
-    test('Generates with normal input', async () => {
+    test('with normal input', async () => {
         await testGenerator([`resources/generatorInput.json`], `resources/generatorOutput.ts`)
     })
 
-    test('Generate overrides', async () => {
+    test('overrides', async () => {
         await testGenerator(
             ['resources/testOverrideInput.json', 'resources/testResultInput.json'],
             'resources/generatorOverrideOutput.ts'

telemetry/vscode/test/resources/generatorInput.json

@@ -14,7 +14,12 @@
         {
             "name": "reason",
             "type": "string",
-            "description": "The reason for a metric or exception depending on context"
+            "description": "Reason code or name for an event (when result=Succeeded) or error (when result=Failed). Unlike the `reasonDesc` field, this should be a stable/predictable name for a class of events or errors (typically the exception name, e.g. FileIOException)."
+        },
+        {
+            "name": "reasonDesc",
+            "type": "string",
+            "description": "Error message detail. May contain arbitrary message details (unlike the `reason` field), but should be truncated (recommendation: 200 chars)."
         },
         {
             "name": "duration",

telemetry/vscode/test/resources/generatorOutput.ts

@@ -5,8 +5,10 @@
 export interface MetricBase {
     /** The result of the operation */
     readonly result?: Result
-    /** The reason for a metric or exception depending on context */
+    /** Reason code or name for an event (when result=Succeeded) or error (when result=Failed). Unlike the `reasonDesc` field, this should be a stable/predictable name for a class of events or errors (typically the exception name, e.g. FileIOException). */
     readonly reason?: string
+    /** Error message detail. May contain arbitrary message details (unlike the `reason` field), but should be truncated (recommendation: 200 chars). */
+    readonly reasonDesc?: string
     /** The duration of the operation in miliseconds */
     readonly duration?: number
     /** A flag indicating that the metric was not caused by the user. */

telemetry/vscode/test/resources/generatorOverrideOutput.ts

@@ -5,8 +5,10 @@
 export interface MetricBase {
     /** The result of the operation */
     readonly result?: Result
-    /** The reason for a metric or exception depending on context */
+    /** Reason code or name for an event (when result=Succeeded) or error (when result=Failed). Unlike the `reasonDesc` field, this should be a stable/predictable name for a class of events or errors (typically the exception name, e.g. FileIOException). */
     readonly reason?: string
+    /** Error message detail. May contain arbitrary message details (unlike the `reason` field), but should be truncated (recommendation: 200 chars). */
+    readonly reasonDesc?: string
     /** The duration of the operation in miliseconds */
     readonly duration?: number
     /** A flag indicating that the metric was not caused by the user. */

telemetry/vscode/test/resources/testOverrideInput.json

@@ -8,7 +8,12 @@
         {
             "name": "reason",
             "type": "string",
-            "description": "The reason for a metric or exception depending on context"
+            "description": "Reason code or name for an event (when result=Succeeded) or error (when result=Failed). Unlike the `reasonDesc` field, this should be a stable/predictable name for a class of events or errors (typically the exception name, e.g. FileIOException)."
+        },
+        {
+            "name": "reasonDesc",
+            "type": "string",
+            "description": "Error message detail. May contain arbitrary message details (unlike the `reason` field), but should be truncated (recommendation: 200 chars)."
         },
         {
             "name": "duration",