telemetry: Add sessionId to metrics (aws#5510)

### Do not merge until service changes are live

## Problem:

I have filtered all the metrics in Kibana by `clientId: "XXXXXX"`, but
if they had multiple IDE windows opened at the same time sending metrics
I cannot know which window they are coming from since they share the
same clientID.

## Solution:

This adds a new field to the telemetry service called `sessionId` which
uniquely identifies a part of the UI in an IDE window. It is adjacent to
`clientId`.

Now in my metrics I will be able to differentiate metrics by their
sessionID since they both share the same clientId by design.

## Implementation Details:

Changes in the Telemetry service need to be merged before this change
can since they update the endpoint to accept this new field.

The updates of this commit only mirror the upstream, so this process is
manual.

---

<!--- 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.

---------

Signed-off-by: Nikolas Komonen <[email protected]>

Author: nkomonen-amazon

packages/core/src/shared/crypto.ts

@@ -30,3 +30,15 @@ export function randomUUID(): `${string}-${string}-${string}-${string}-${string}
 
     return require('crypto').randomUUID()
 }
+
+/**
+ * Returns true if the given string is a UUID
+ *
+ * NOTE: There are different UUID versions, this function does not discriminate between them.
+ * See: https://stackoverflow.com/questions/7905929/how-to-test-valid-uuid-guid
+ */
+export function isUuid(uuid: string): boolean {
+    // NOTE: This pattern must match, or at least be a subset of the "Session ID" pattern in `telemetry/service-2.json`
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+    return uuidPattern.test(uuid)
+}

packages/core/src/shared/telemetry/activation.ts

@@ -14,7 +14,7 @@ import { DefaultTelemetryService } from './telemetryService'
 import { getLogger } from '../logger'
 import { getComputeRegion, isAmazonQ, isCloud9, productName } from '../extensionUtilities'
 import { openSettingsId, Settings } from '../settings'
-import { TelemetryConfig } from './util'
+import { getSessionId, TelemetryConfig } from './util'
 import { isAutomation, isReleaseVersion } from '../vscode/env'
 import { AWSProduct } from './clienttelemetry'
 import { DefaultTelemetryClient } from './telemetryClient'
@@ -76,6 +76,12 @@ export async function activate(
         }
 
         await globals.telemetry.start()
+
+        if (globals.telemetry.telemetryEnabled) {
+            // Only log the IDs if telemetry is enabled, so that users who have it disabled do not think we are sending events.
+            getLogger().info(`Telemetry Client ID: ${globals.telemetry.clientId}`)
+            getLogger().info(`Telemetry Session ID: ${getSessionId()}`)
+        }
     } catch (e) {
         // Only throw in a production build because:
         //   1. Telemetry must never prevent normal Toolkit operation.

packages/core/src/shared/telemetry/service-2.json

@@ -58,6 +58,10 @@
       "type":"string",
       "pattern":"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
     },
+    "SessionID":{
+      "type":"string",
+      "pattern":"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
+    },
     "Command":{
       "type":"string",
       "max":2000
@@ -207,6 +211,7 @@
         "AWSProduct":{"shape":"AWSProduct"},
         "AWSProductVersion":{"shape":"AWSProductVersion"},
         "ClientID":{"shape":"ClientID"},
+        "SessionID":{"shape":"SessionID"},
         "OS":{"shape":"Value"},
         "OSVersion":{"shape":"Value"},
         "ComputeEnv": {"shape":"ComputeEnv"},

packages/core/src/shared/telemetry/telemetryClient.ts

@@ -17,7 +17,7 @@ import { ServiceConfigurationOptions } from 'aws-sdk/lib/service'
 import globals from '../extensionGlobals'
 import { DevSettings } from '../settings'
 import { ClassToInterfaceType } from '../utilities/tsUtils'
-import { getComputeEnvType } from './util'
+import { getComputeEnvType, getSessionId } from './util'
 
 export const accountMetadataKey = 'awsAccount'
 export const regionKey = 'awsRegion'
@@ -106,6 +106,7 @@ export class DefaultTelemetryClient implements TelemetryClient {
                         AWSProduct: DefaultTelemetryClient.productName,
                         AWSProductVersion: extensionVersion,
                         ClientID: this.clientId,
+                        SessionID: getSessionId(),
                         OS: os.platform(),
                         OSVersion: os.release(),
                         ComputeEnv: await getComputeEnvType(),

packages/core/src/shared/telemetry/telemetryService.ts

@@ -133,6 +133,12 @@ export class DefaultTelemetryService {
         getLogger().verbose(`Telemetry is ${value ? 'enabled' : 'disabled'}`)
     }
 
+    private _clientId: string | undefined
+    /** Returns the client ID, creating one if it does not exist. */
+    public get clientId(): string {
+        return (this._clientId ??= getClientId(globals.globalState))
+    }
+
     public get timer(): NodeJS.Timer | undefined {
         return this._timer
     }
@@ -224,8 +230,6 @@ export class DefaultTelemetryService {
 
     private async createDefaultPublisher(): Promise<TelemetryPublisher | undefined> {
         try {
-            // grab our clientId and generate one if it doesn't exist
-            const clientId = getClientId(globals.globalState)
             // grab our Cognito identityId
             const poolId = DefaultTelemetryClient.config.identityPool
             const identityMapJson = globals.globalState.tryGet(
@@ -240,7 +244,7 @@ export class DefaultTelemetryService {
 
             // if we don't have an identity, get one
             if (!identity) {
-                const identityPublisherTuple = await DefaultTelemetryPublisher.fromDefaultIdentityPool(clientId)
+                const identityPublisherTuple = await DefaultTelemetryPublisher.fromDefaultIdentityPool(this.clientId)
 
                 // save it
                 identityMap.set(poolId, identityPublisherTuple.cognitoIdentityId)
@@ -252,7 +256,7 @@ export class DefaultTelemetryService {
                 // return the publisher
                 return identityPublisherTuple.publisher
             } else {
-                return DefaultTelemetryPublisher.fromIdentityId(clientId, identity)
+                return DefaultTelemetryPublisher.fromIdentityId(this.clientId, identity)
             }
         } catch (err) {
             getLogger().error(`Got ${err} while initializing telemetry publisher`)

packages/core/src/shared/telemetry/util.ts

@@ -8,7 +8,7 @@ import { env, version } from 'vscode'
 import * as os from 'os'
 import { getLogger } from '../logger'
 import { fromExtensionManifest, migrateSetting, Settings } from '../settings'
-import { memoize } from '../utilities/functionUtils'
+import { memoize, once } from '../utilities/functionUtils'
 import {
     isInDevEnv,
     extensionVersion,
@@ -28,6 +28,7 @@ import { randomUUID } from '../crypto'
 import { ClassToInterfaceType } from '../utilities/tsUtils'
 import { FunctionEntry, type TelemetryTracer } from './spans'
 import { telemetry } from './telemetry'
+import { v5 as uuidV5 } from 'uuid'
 
 const legacySettingsTelemetryValueDisable = 'Disable'
 const legacySettingsTelemetryValueEnable = 'Enable'
@@ -90,6 +91,41 @@ export function convertLegacy(value: unknown): boolean {
     }
 }
 
+/**
+ * Returns an identifier that uniquely identifies a single application
+ * instance/window of a specific IDE. I.e if I have multiple VS Code
+ * windows open each one will have a unique session ID. This session ID
+ * can be used in conjunction with the client ID to differntiate between
+ * different VS Code windows on a users machine.
+ *
+ * ### Rules:
+ *
+ * - On startup of a new application instance, a new session ID must be created.
+ *   - This identifier must be a `UUID`, it is enforced by the telemetry service.
+ * - The session ID must be different from all other IDs on the machine
+ * - A session ID exists until the application instance is terminated.
+ *   It should never be used again after termination.
+ * - All extensions on the same application instance MUST return the same session ID.
+ *   - This will allow us to know which of our extensions (eg Q vs Toolkit) are in the
+ *     same VS Code window.
+ *
+ * `vscode.env.sessionId` behaves as described aboved, EXCEPT its
+ * value looks close to a UUID by does not exactly match it (has additional characters).
+ * As a result we process it through uuidV5 which creates a proper UUID from it.
+ * uuidV5 is idempotent, so as long as `vscode.env.sessionId` returns the same value,
+ * we will get the same UUID.
+ */
+export const getSessionId = once(() => uuidV5(vscode.env.sessionId, sessionIdNonce))
+/**
+ * This is an arbitrary nonce that is used in creating a v5 UUID for Session ID. We only
+ * have this since the spec requires it.
+ * - This should ONLY be used by {@link getSessionId}.
+ * - This value MUST NOT change during runtime, otherwise {@link getSessionId} will lose its
+ *   idempotency. But, if there was a reason to change the value in a PR, it would not be an issue.
+ * - This is exported only for testing.
+ */
+export const sessionIdNonce = '44cfdb20-b30b-4585-a66c-9f48f24f99b5' as const
+
 /**
  * Calculates the clientId for the current profile. This calculation is performed once
  * on first call and the result is stored for the remainder of the session.

packages/core/src/test/shared/crypto.test.ts

@@ -4,7 +4,7 @@
  */
 
 import assert from 'assert'
-import { randomUUID } from '../../shared/crypto'
+import { isUuid, randomUUID } from '../../shared/crypto'
 
 describe('crypto', function () {
     describe('randomUUID()', function () {
@@ -25,4 +25,22 @@ describe('crypto', function () {
             assert(uuidPattern.test('not-a-uuid') === false)
         })
     })
+
+    describe('isUuid()', function () {
+        assert.equal(isUuid(''), false)
+        assert.equal(isUuid('not-a-uuid'), false)
+        assert.equal(isUuid('47fe01cf-f37a-4e7c-b971'), false)
+        assert.equal(isUuid('47fe01cf_f37a_4e7c-b971-@10fe5897763'), false)
+        // The '9' in '9e7c' must actually be between 1-5 based on the UUID spec: https://stackoverflow.com/a/38191104
+        assert.equal(isUuid('47fe01cf-f37a-9e7c-b971-d10fe5897763'), false)
+        assert.equal(isUuid(' 47fe01cf-f37a-4e7c-b971-d10fe5897763'), false) // leading whitespace
+        assert.equal(isUuid('47fe01cf-f37a-4e7c-b971-d10fe5897763 '), false) // trailing whitespace
+        assert.equal(isUuid('47fe01cf-f37a-4e7c-b971-d10fe5897763z'), false) // one extra character
+        assert.equal(isUuid('47fe01cf-f37a-4e7c-b971-d10fe5897763 blah'), false) // trailing word
+
+        assert.equal(isUuid('47fe01cf-f37a-4e7c-b971-d10fe5897763'), true)
+        // The telemetry services indicates that per postel's law, uppercase is valid to pass in
+        // as they will lowerCase when necessary.
+        assert.equal(isUuid('47fe01cf-f37a-4e7c-b971-d10fe5897763'.toUpperCase()), true)
+    })
 })

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

@@ -9,15 +9,18 @@ import { Settings } from '../../../shared/settings'
 import {
     convertLegacy,
     getClientId,
+    getSessionId,
     getUserAgent,
     platformPair,
+    sessionIdNonce,
     telemetryClientIdEnvKey,
     TelemetryConfig,
 } from '../../../shared/telemetry/util'
 import { extensionVersion } from '../../../shared/vscode/env'
 import { FakeMemento } from '../../fakeExtensionContext'
 import { GlobalState } from '../../../shared/globalState'
 import { randomUUID } from 'crypto'
+import { isUuid } from '../../../shared/crypto'
 
 describe('TelemetryConfig', function () {
     const settingKey = 'aws.telemetry'
@@ -107,6 +110,19 @@ describe('TelemetryConfig', function () {
     })
 })
 
+describe('getSessionId', function () {
+    it('returns a stable UUID', function () {
+        const result = getSessionId()
+
+        assert.deepStrictEqual(isUuid(result), true)
+        assert.deepStrictEqual(getSessionId(), result, 'Subsequent call did not return the same UUID')
+    })
+
+    it('nonce is the same as always', function () {
+        assert.deepStrictEqual(sessionIdNonce, '44cfdb20-b30b-4585-a66c-9f48f24f99b5')
+    })
+})
+
 describe('getClientId', function () {
     before(function () {
         delete process.env[telemetryClientIdEnvKey]