telemetry: add UA environment variable to SAM CLI invocations (#3170)

## Problem
SAM CLI doesn't know which products are executing it on the user's behalf

## Solution
Add an environment variable containing additional context

Author: JadenSimon

src/shared/awsClientBuilder.ts

@@ -6,12 +6,9 @@
 import { Request, AWSError, Credentials } from 'aws-sdk'
 import { CredentialsOptions } from 'aws-sdk/lib/credentials'
 import { ServiceConfigurationOptions } from 'aws-sdk/lib/service'
-import { env, version } from 'vscode'
 import { AwsContext } from './awsContext'
-import globals from './extensionGlobals'
 import { DevSettings } from './settings'
-import { getClientId } from './telemetry/util'
-import { extensionVersion } from './vscode/env'
+import { getUserAgent } from './telemetry/util'
 
 // These are not on the public API but are very useful for logging purposes.
 // Tests guard against the possibility that these values change unexpectedly.
@@ -129,9 +126,7 @@ export class DefaultAWSClientBuilder implements AWSClientBuilder {
         }
 
         if (userAgent && !opt.customUserAgent) {
-            const platformName = env.appName.replace(/\s/g, '-')
-            const clientId = await getClientId(globals.context.globalState)
-            opt.customUserAgent = `AWS-Toolkit-For-VSCode/${extensionVersion} ${platformName}/${version} ClientId/${clientId}`
+            opt.customUserAgent = await getUserAgent({ includeClientId: true })
         }
 
         const apiConfig = (opt as { apiConfig?: { metadata?: Record<string, string> } } | undefined)?.apiConfig

src/shared/sam/cli/samCliInvoker.ts

@@ -6,6 +6,7 @@
 import * as logger from '../../logger'
 import { ChildProcess, ChildProcessResult } from '../../utilities/childProcess'
 import {
+    addTelemetryEnvVar,
     makeRequiredSamCliProcessInvokeOptions,
     SamCliProcessInvokeOptions,
     SamCliProcessInvoker,
@@ -47,7 +48,7 @@ export class DefaultSamCliProcessInvoker implements SamCliProcessInvoker {
         const samCommand = sam.path ? sam.path : 'sam'
         this.childProcess = new ChildProcess(samCommand, invokeOptions.arguments, {
             logging: options?.logging ? 'yes' : 'no',
-            spawnOptions: invokeOptions.spawnOptions,
+            spawnOptions: await addTelemetryEnvVar(options?.spawnOptions),
         })
 
         getLogger('channel').info(localize('AWS.running.command', 'Command: {0}', `${this.childProcess}`))

src/shared/sam/cli/samCliInvokerUtils.ts

@@ -5,6 +5,7 @@
 
 import { SpawnOptions } from 'child_process'
 import { getLogger } from '../../logger'
+import { getUserAgent } from '../../telemetry/util'
 import { ChildProcessResult, ChildProcessOptions } from '../../utilities/childProcess'
 
 export interface SamCliProcessInvokeOptions {
@@ -99,3 +100,13 @@ function startsWithEscapeSequence(text: string, sequences = acceptedSequences):
 function startsWithError(text: string): boolean {
     return text.startsWith('Error:')
 }
+
+export async function addTelemetryEnvVar(options: SpawnOptions | undefined): Promise<SpawnOptions> {
+    return {
+        ...options,
+        env: {
+            SAM_CLI_TELEMETRY_FROM_IDE: await getUserAgent({ includeClientId: false }),
+            ...options?.env,
+        },
+    }
+}

src/shared/sam/cli/samCliLocalInvoke.ts

@@ -14,6 +14,7 @@ import { removeAnsi } from '../../utilities/textUtilities'
 import * as vscode from 'vscode'
 import globals from '../../extensionGlobals'
 import { SamCliSettings } from './samCliSettings'
+import { addTelemetryEnvVar } from './samCliInvokerUtils'
 
 const localize = nls.loadMessageBundle()
 
@@ -58,7 +59,9 @@ export class DefaultSamLocalInvokeCommand implements SamLocalInvokeCommand {
     ) {}
 
     public async invoke({ options, ...params }: SamLocalInvokeCommandArgs): Promise<ChildProcess> {
-        const childProcess = new ChildProcess(params.command, params.args, { spawnOptions: options })
+        const childProcess = new ChildProcess(params.command, params.args, {
+            spawnOptions: await addTelemetryEnvVar(options),
+        })
         getLogger('channel').info('AWS.running.command', 'Command: {0}', `${childProcess}`)
         // "sam local invoke", "sam local start-api", etc.
         const samCommandName = `sam ${params.args[0]} ${params.args[1]}`

src/shared/sam/sync.ts

@@ -39,6 +39,7 @@ import { SamCliInfoInvocation } from './cli/samCliInfo'
 import { parse } from 'semver'
 import { isAutomation } from '../vscode/env'
 import { getOverriddenParameters } from '../../lambda/config/parameterUtils'
+import { addTelemetryEnvVar } from './cli/samCliInvokerUtils'
 
 export interface SyncParams {
     readonly region: string
@@ -348,10 +349,10 @@ export async function runSamSync(args: SyncParams) {
     }
 
     const sam = new ChildProcess(samCliPath, ['sync', ...boundArgs], {
-        spawnOptions: {
+        spawnOptions: await addTelemetryEnvVar({
             cwd: args.projectRoot.fsPath,
             env: await injectCredentials(args.connection),
-        },
+        }),
     })
 
     await runSyncInTerminal(sam)

src/shared/telemetry/util.ts

@@ -3,13 +3,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Memento } from 'vscode'
+import { env, Memento, version } from 'vscode'
 import { getLogger } from '../logger'
 import { fromExtensionManifest } from '../settings'
 import { shared } from '../utilities/functionUtils'
-import { isAutomation } from '../vscode/env'
+import { extensionVersion, isAutomation } from '../vscode/env'
 import { v4 as uuidv4 } from 'uuid'
 import { addTypeName } from '../utilities/typeConstructors'
+import globals from '../extensionGlobals'
 
 const legacySettingsTelemetryValueDisable = 'Disable'
 const legacySettingsTelemetryValueEnable = 'Enable'
@@ -59,3 +60,23 @@ export const getClientId = shared(
         }
     }
 )
+
+/**
+ * Returns a string that should be used as the extension's user agent.
+ *
+ * Omits the `ClientId` pair by default.
+ */
+export async function getUserAgent(
+    opt?: { includeClientId?: boolean },
+    globalState = globals.context.globalState
+): Promise<string> {
+    const platformName = env.appName.replace(/\s/g, '-')
+    const pairs = [`AWS-Toolkit-For-VSCode/${extensionVersion}`, `${platformName}/${version}`]
+
+    if (opt?.includeClientId) {
+        const clientId = await getClientId(globalState)
+        pairs.push(`ClientId/${clientId}`)
+    }
+
+    return pairs.join(' ')
+}

src/test/shared/sam/cli/samCliInvokerUtils.test.ts

@@ -5,6 +5,7 @@
 
 import * as assert from 'assert'
 import {
+    addTelemetryEnvVar,
     collectAcceptedErrorMessages,
     logAndThrowIfUnexpectedExitCode,
     makeUnexpectedExitCodeError,
@@ -81,3 +82,20 @@ describe('collectAcceptedErrorMessages()', async () => {
         assert(!result.includes(prependEscapeCode('[100m This is not an accepted escape sequence')))
     })
 })
+
+describe('addTelemetryEnvVar', async function () {
+    it('adds a new variable, preserving the existing contents', async function () {
+        const result = await addTelemetryEnvVar({
+            cwd: '/foo',
+            env: { AWS_REGION: 'us-east-1' },
+        })
+
+        assert.deepStrictEqual(result, {
+            cwd: '/foo',
+            env: {
+                SAM_CLI_TELEMETRY_FROM_IDE: result.env?.['SAM_CLI_TELEMETRY_FROM_IDE'],
+                AWS_REGION: 'us-east-1',
+            },
+        })
+    })
+})

src/test/shared/telemetry/util.test.ts

@@ -6,7 +6,8 @@
 import * as assert from 'assert'
 import { Memento, ConfigurationTarget } from 'vscode'
 import { Settings } from '../../../shared/settings'
-import { convertLegacy, getClientId, TelemetryConfig } from '../../../shared/telemetry/util'
+import { convertLegacy, getClientId, getUserAgent, TelemetryConfig } from '../../../shared/telemetry/util'
+import { extensionVersion } from '../../../shared/vscode/env'
 import { FakeMemento } from '../../fakeExtensionContext'
 
 describe('TelemetryConfig', function () {
@@ -157,3 +158,22 @@ describe('getClientId', function () {
         assert.strictEqual(clientId, '11111111-1111-1111-1111-111111111111')
     })
 })
+
+describe('getUserAgent', function () {
+    it('includes product name and version', async function () {
+        const userAgent = await getUserAgent()
+        const lastPair = userAgent.split(' ')[0]
+        assert.ok(lastPair?.startsWith(`AWS-Toolkit-For-VSCode/${extensionVersion}`))
+    })
+
+    it('omits `ClientId` by default', async function () {
+        const userAgent = await getUserAgent()
+        assert.ok(!userAgent.includes('ClientId'))
+    })
+
+    it('includes `ClientId` at the end if opted in', async function () {
+        const userAgent = await getUserAgent({ includeClientId: true })
+        const lastPair = userAgent.split(' ').pop()
+        assert.ok(lastPair?.startsWith('ClientId/'))
+    })
+})