telemetry(lambda): Send meaningful telemetry error codes for SAM CLI invocation failures (#6042)

## Problem
With only Unknown errors, It's hard to differentiate errors or make
possible improvements

## Solution
- Parse SAM CLI output
- Add telemetry code based on the output error

---

<!--- REMINDER: Ensure that your PR meets the guidelines in
CONTRIBUTING.md -->

License: I confirm that my contribution is made under the terms of the
Apache 2.0 license.

Author: mbfreder

packages/core/src/shared/sam/build.ts

@@ -19,7 +19,7 @@ import globals from '../extensionGlobals'
 import { TreeNode } from '../treeview/resourceTreeDataProvider'
 import { telemetry } from '../telemetry/telemetry'
 import { getSpawnEnv } from '../env/resolveEnv'
-import { getProjectRoot, getSamCliPathAndVersion, isDotnetRuntime } from './utils'
+import { getErrorCode, getProjectRoot, getSamCliPathAndVersion, isDotnetRuntime } from './utils'
 import { getConfigFileUri, validateSamBuildConfig } from './config'
 import { runInTerminal } from './processTerminal'
 
@@ -236,6 +236,7 @@ export async function runBuild(arg?: TreeNode): Promise<SamBuildResult> {
     } catch (error) {
         throw ToolkitError.chain(error, 'Failed to build SAM template', {
             details: { ...resolveBuildArgConflict(buildFlags) },
+            code: getErrorCode(error),
         })
     }
 }

packages/core/src/shared/sam/deploy.ts

@@ -24,7 +24,7 @@ import { Wizard } from '../wizards/wizard'
 import { addTelemetryEnvVar } from './cli/samCliInvokerUtils'
 import { validateSamDeployConfig, SamConfig, writeSamconfigGlobal } from './config'
 import { TemplateItem, createStackPrompter, createBucketPrompter, createTemplatePrompter } from './sync'
-import { getProjectRoot, getSamCliPathAndVersion, getSource } from './utils'
+import { getErrorCode, getProjectRoot, getSamCliPathAndVersion, getSource } from './utils'
 import { runInTerminal } from './processTerminal'
 
 export interface DeployParams {
@@ -392,7 +392,10 @@ export async function runDeploy(arg: any, wizardParams?: DeployParams): Promise<
                 throw error
             }
         } catch (error) {
-            throw ToolkitError.chain(error, 'Failed to deploy SAM template', { details: { ...deployFlags } })
+            throw ToolkitError.chain(error, 'Failed to deploy SAM template', {
+                details: { ...deployFlags },
+                code: getErrorCode(error),
+            })
         }
         return {
             isSuccess: true,

packages/core/src/shared/sam/processTerminal.ts

@@ -12,18 +12,17 @@ import { CancellationError } from '../utilities/timeoutUtils'
 import { getLogger } from '../logger'
 import { removeAnsi } from '../utilities/textUtilities'
 import { isAutomation } from '../vscode/env'
+import { throwIfErrorMatches } from './utils'
 
 let oldTerminal: ProcessTerminal | undefined
 export async function runInTerminal(proc: ChildProcess, cmd: string) {
     const handleResult = (result?: ChildProcessResult) => {
         if (result && result.exitCode !== 0) {
-            const message = `sam ${cmd} exited with a non-zero exit code: ${result.exitCode}`
-            if (result.stderr.includes('is up to date')) {
-                throw ToolkitError.chain(result.error, message, {
-                    code: 'NoUpdateExitCode',
-                })
-            }
-            throw ToolkitError.chain(result.error, message, {
+            throwIfErrorMatches(result)
+
+            // If no specific error matched, throw the default non-zero exit code error.
+            const defaultMessage = `sam ${cmd} exited with a non-zero exit code: ${result.exitCode}`
+            throw ToolkitError.chain(result.error, defaultMessage, {
                 code: 'NonZeroExitCode',
             })
         }

packages/core/src/shared/sam/sync.ts

@@ -41,7 +41,7 @@ import { IamConnection } from '../../auth/connection'
 import { CloudFormationTemplateRegistry } from '../fs/templateRegistry'
 import { TreeNode } from '../treeview/resourceTreeDataProvider'
 import { getSpawnEnv } from '../env/resolveEnv'
-import { getProjectRoot, getProjectRootUri, getSamCliPathAndVersion, getSource } from './utils'
+import { getErrorCode, getProjectRoot, getProjectRootUri, getSamCliPathAndVersion, getSource } from './utils'
 import { runInTerminal } from './processTerminal'
 
 const localize = nls.loadMessageBundle()
@@ -661,7 +661,10 @@ export async function runSync(
                 isSuccess: true,
             }
         } catch (err) {
-            throw ToolkitError.chain(err, 'Failed to sync SAM application', { details: { ...params } })
+            throw ToolkitError.chain(err, 'Failed to sync SAM application', {
+                details: { ...params },
+                code: getErrorCode(err),
+            })
         }
     })
 }

packages/core/src/shared/sam/utils.ts

@@ -15,6 +15,7 @@ import { ToolkitError } from '../errors'
 import { SamCliSettings } from './cli/samCliSettings'
 import { SamCliInfoInvocation } from './cli/samCliInfo'
 import { parse } from 'semver'
+import { ChildProcessResult } from '../utilities/processUtils'
 
 /**
  * @description determines the root directory of the project given Template Item
@@ -83,3 +84,36 @@ export async function getSamCliPathAndVersion() {
 
     return { path: samCliPath, parsedVersion }
 }
+
+export function getSamCliErrorMessage(stderr: string): string {
+    // Split the stderr string by newline, filter out empty lines, and get the last line
+    const lines = stderr
+        .trim()
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+    return lines[lines.length - 1]
+}
+
+export function getErrorCode(error: unknown): string | undefined {
+    return error instanceof ToolkitError ? error.code : undefined
+}
+
+export function throwIfErrorMatches(result: ChildProcessResult) {
+    const errorMessage = getSamCliErrorMessage(result.stderr)
+    for (const errorType in SamCliErrorTypes) {
+        if (errorMessage.includes(SamCliErrorTypes[errorType as keyof typeof SamCliErrorTypes])) {
+            throw ToolkitError.chain(result.error, errorMessage, {
+                code: errorType,
+            })
+        }
+    }
+}
+
+export enum SamCliErrorTypes {
+    DockerUnreachable = 'Docker is unreachable.',
+    ResolveS3AndS3Set = 'Cannot use both --resolve-s3 and --s3-bucket parameters in non-guided deployments.',
+    DeployStackStatusMissing = 'Was not able to find a stack with the name:',
+    DeployStackOutPutFailed = 'Failed to get outputs from stack',
+    DeployBucketRequired = 'Templates with a size greater than 51,200 bytes must be deployed via an S3 Bucket.',
+    ChangeSetEmpty = 'is up to date',
+}

packages/core/src/test/shared/sam/utils.test.ts

@@ -6,12 +6,20 @@
 import * as vscode from 'vscode'
 import assert from 'assert'
 import sinon from 'sinon'
-import { getProjectRootUri, getProjectRoot, getSource, isDotnetRuntime } from '../../../shared/sam/utils'
+import {
+    getProjectRootUri,
+    getProjectRoot,
+    getSource,
+    isDotnetRuntime,
+    getSamCliErrorMessage,
+    throwIfErrorMatches,
+} from '../../../shared/sam/utils'
 import { TemplateItem } from '../../../shared/sam/sync'
 import { RegionNode } from '../../../awsexplorer/regionNode'
 import { Region } from '../../../shared/regions/endpoints'
-import { RegionProvider } from '../../../shared'
+import { RegionProvider, ToolkitError } from '../../../shared'
 import { DeployedResource, DeployedResourceNode } from '../../../awsService/appBuilder/explorer/nodes/deployedNode'
+import { ChildProcessResult } from '../../../shared/utilities/processUtils'
 
 describe('SAM utils', async function () {
     it('returns the projectRoot', async function () {
@@ -148,4 +156,36 @@ describe('SAM utils', async function () {
             })
         })
     })
+
+    describe('gets the SAM CLI error from stderr', async function () {
+        it('returns the error message', async function () {
+            const stderr =
+                'Starting Build use cache\nStarting Build inside a container\nCache is invalid, running build and copying resources for following functions (ResizerFunction)\nBuilding codeuri: /Users/mbfreder/TestApp/JavaSamApp/serverless-patterns/s3lambda-resizing-python/src runtime: python3.12 metadata: {} architecture: x86_64 functions: ResizerFunction\nError: Docker is unreachable. Docker needs to be running to build inside a container.'
+            const response = getSamCliErrorMessage(stderr)
+            assert.deepStrictEqual(
+                response,
+                'Error: Docker is unreachable. Docker needs to be running to build inside a container.'
+            )
+        })
+    })
+
+    describe('throwIfErrorMatches', async function () {
+        it('should throw a ToolkitError with the correct code when an error message matches', () => {
+            const mockError = new Error('Mock Error')
+            const mockResult: ChildProcessResult = {
+                exitCode: 1,
+                error: mockError,
+                stdout: '',
+                stderr: 'Docker is unreachable.',
+            }
+            assert.throws(
+                () => throwIfErrorMatches(mockResult),
+                (e: any) => {
+                    assert.strictEqual(e instanceof ToolkitError, true)
+                    assert.strictEqual(e.code, 'DockerUnreachable')
+                    return true
+                }
+            )
+        })
+    })
 })