chore(feature): knowledge hub Telemetry Setup

.github/workflows/pipeline.yml

@@ -38,6 +38,10 @@ jobs:
                   node-version: ${{ matrix.node-version }}
             - name: Install pnpm modules
               run: pnpm install
+            - name: Create a .env file in ide-extension package
+              run: |
+                  touch packages/ide-extension/.env
+                  echo KHE_TELEMETRY_INSTRUMENTATION_KEY=${{ secrets.INSTRUMENTATION_KEY }} >> packages/ide-extension/.env
             - name: Run build
               run: pnpm run build
             - name: Run linting

.vscode/launch.json

@@ -5,17 +5,7 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Knowledge Hub extension - Launch Knowledge Hub extension",
-            "type": "extensionHost",
-            "request": "launch",
-            "runtimeExecutable": "${execPath}",
-            "args": ["--log=debug", "--extensionDevelopmentPath=${workspaceFolder}/packages/ide-extension/"],
-            "outFiles": ["${workspaceFolder}/pacakges/ide-extension/dist/**/*.js"],
-            "preLaunchTask": "extension-watch",
-            "postDebugTask": "Terminate All Tasks"
-        },
-        {
-            "name": "Knowledge Hub extension - webapp: Run Current Jest File",
+            "name": "core: Run current jest file",
             "type": "node",
             "request": "launch",
             "program": "${workspaceFolder}/node_modules/jest/bin/jest",
@@ -25,10 +15,20 @@
             "windows": {
                 "program": "${workspaceFolder}/node_modules/jest/bin/jest"
             },
-            "cwd": "${workspaceFolder}/packages/webapp"
+            "cwd": "${workspaceFolder}/packages/core"
         },
         {
-            "name": "Knowledge Hub extension - ide-extension: Run Current Jest File",
+            "name": "ide-extension: Launch extension",
+            "type": "extensionHost",
+            "request": "launch",
+            "runtimeExecutable": "${execPath}",
+            "args": ["--log=debug", "--extensionDevelopmentPath=${workspaceFolder}/packages/ide-extension/"],
+            "outFiles": ["${workspaceFolder}/pacakges/ide-extension/dist/**/*.js"],
+            "preLaunchTask": "extension-watch",
+            "postDebugTask": "Terminate All Tasks"
+        },
+        {
+            "name": "ide-extension: Run current jest file",
             "type": "node",
             "request": "launch",
             "program": "${workspaceFolder}/node_modules/jest/bin/jest",
@@ -41,7 +41,7 @@
             "cwd": "${workspaceFolder}/packages/ide-extension"
         },
         {
-            "name": "Knowledge Hub extension - core: Run Current Jest File",
+            "name": "webapp: Run current jest file",
             "type": "node",
             "request": "launch",
             "program": "${workspaceFolder}/node_modules/jest/bin/jest",
@@ -51,7 +51,7 @@
             "windows": {
                 "program": "${workspaceFolder}/node_modules/jest/bin/jest"
             },
-            "cwd": "${workspaceFolder}/packages/core"
+            "cwd": "${workspaceFolder}/packages/webapp"
         }
     ]
 }

packages/ide-extension/esbuild.js

@@ -20,7 +20,7 @@ const buildConfig = {
         '.svg': 'file'
     },
     platform: 'node',
-    target: 'node12.22',
+    target: 'node16.1',
     external: [
         'vscode' // the vscode-module is created on-the-fly and must be excluded. Add other modules that cannot be webpack'ed, 📖 -> https://webpack.js.org/configuration/externals/
     ],

packages/ide-extension/package.json

@@ -44,6 +44,19 @@
         "onCommand:sap.ux.knowledgeHub.openKnowledgeHub"
     ],
     "contributes": {
+        "configuration": {
+            "id": "sap.ux.knowledgeHub",
+            "type": "object",
+            "title": "%configuration.title%",
+            "properties": {
+                "sap.ux.knowledgeHub.telemetryEnabled": {
+                    "type": "boolean",
+                    "description": "%configuration.telemetryEnabled%",
+                    "default": true,
+                    "scope": "window"
+                }
+            }
+        },
         "commands": [
             {
                 "command": "sap.ux.knowledgeHub.openKnowledgeHub",
@@ -55,15 +68,19 @@
     "devDependencies": {
         "@sap/knowledge-hub-extension-core": "workspace:*",
         "@sap/knowledge-hub-extension-types": "workspace:*",
+        "@types/uuid": "9.0.1",
         "@types/vscode": "1.39.0",
+        "@vscode/vsce": "2.19.0",
+        "applicationinsights": "2.5.1",
+        "axios": "1.3.4",
+        "dotenv": "16.0.3",
         "esbuild": "0.15.12",
         "esbuild-plugin-copy": "2.1.0",
         "i18next": "22.4.15",
         "jsdom": "21.1.0",
-        "vsce": "2.15.0",
-        "vscode-uri": "3.0.7",
-        "axios": "1.3.4",
-        "qs": "6.11.1"
+        "qs": "6.11.1",
+        "uuid": "9.0.0",
+        "vscode-uri": "3.0.7"
     },
     "galleryBanner": {
         "color": "#00195A",

packages/ide-extension/package.nls.json

@@ -1,6 +1,7 @@
 {
     "knowledgeHub.displayName": "Knowledge Hub extension by SAP",
     "knowledgeHub.description": "Knowledge Hub extension by SAP",
+    "configuration.telemetryEnabled": "If enabled, telemetry events to improve extension quality will be recorded",
     "commands.knowledgeHub.category": "SAP",
     "commands.knowledgeHub.openKnowledgeHub.title": "Open Knowledge Hub"
 }

packages/ide-extension/src/extension.ts

@@ -4,13 +4,18 @@ import type { ExtensionContext } from 'vscode';
 import { KnowledgeHubPanel } from './panels/knowledgeHubPanel';
 import { logString } from './logger/logger';
 import { initI18n } from './i18n';
-
+import { initTelemetry } from './telemetry';
 /**
  *  Activate function is called by VSCode when the extension gets active.
  *
  * @param {ExtensionContext} context  - context from VSCode
  */
 export async function activate(context: ExtensionContext): Promise<void> {
+    try {
+        context.subscriptions.push(initTelemetry());
+    } catch (error) {
+        logString(`Error during initialization of telemetry: ${(error as Error)?.message}`);
+    }
     // Initialize i18next
     await initI18n();
 

packages/ide-extension/src/panels/knowledgeHubPanel.ts

@@ -2,13 +2,16 @@ import type { WebviewPanel, ExtensionContext } from 'vscode';
 import { Uri, ViewColumn, window } from 'vscode';
 import i18next from 'i18next';
 
-import { RESTART_WEBVIEW } from '@sap/knowledge-hub-extension-types';
+import { RESTART_WEBVIEW, LOG_TELEMETRY_EVENT } from '@sap/knowledge-hub-extension-types';
 
+import type { KnowledgeHubActions } from '@sap/knowledge-hub-extension-types';
 import { MessageHandler } from '../knowledge-hub/messageHandler';
 import { AppSession } from '../knowledge-hub/appSession';
 import { getHtml, getWebviewUri } from '../utils/web';
 import { Storage } from '../utils/storage';
 import { errorInstance } from '../utils/error';
+import { trackAction } from '../telemetry';
+import { logString } from '../logger/logger';
 
 /**
  *  A class to handle the knowledge hub extension panel.
@@ -79,29 +82,46 @@ export class KnowledgeHubPanel {
         );
 
         const uri: string = getWebviewUri(knowledgeHubWebView.webview, viewRootUri).toString();
-
+        knowledgeHubWebView.webview.onDidReceiveMessage(this.onWebviewMessage.bind(this));
         knowledgeHubWebView.webview.html = getHtml(
             uri.toString(),
             i18next.t('KNOWLEDGE_HUB_VIEW_TITLE'),
             '/knowledgeHub.js',
             undefined,
             '/knowledgeHub.css'
         );
-
-        // Register for incoming messages from web view
-        knowledgeHubWebView.webview.onDidReceiveMessage(async (action) => {
-            await this.messageHandler.processRequestAction(action);
-            // Special case when restart is requested
-            if (action.type === RESTART_WEBVIEW) {
-                this.panel.dispose();
-                this.panel = this.createKnowledgeHubWebview();
-            }
-        });
-
         return knowledgeHubWebView;
     }
 
     public show(): void {
         this.panel.reveal();
     }
+
+    /**
+     *
+     * @param action
+     */
+    private async onWebviewMessage(action: KnowledgeHubActions): Promise<void> {
+        try {
+            await this.messageHandler.processRequestAction(action);
+            switch (action.type) {
+                case RESTART_WEBVIEW: {
+                    this.panel.dispose();
+                    this.panel = this.createKnowledgeHubWebview();
+                    break;
+                }
+                case LOG_TELEMETRY_EVENT: {
+                    await trackAction(action);
+                    break;
+                }
+                default: {
+                    // Nothing to do if the action is not handled
+                }
+            }
+        } catch (error: any) {
+            logString(
+                `Error while processing action.\n  Action: ${JSON.stringify(action)}\n  Message: ${error?.message}`
+            );
+        }
+    }
 }

packages/ide-extension/src/telemetry/action-map.ts

@@ -0,0 +1,23 @@
+import type { LogTelemetryEvent } from '@sap/knowledge-hub-extension-types';
+
+import { KHUB_OPEN_BLOGS, KHUB_OPEN_TUTORIAL } from '@sap/knowledge-hub-extension-types';
+import type { TelemetryUIOpenBlogProps, TelemetryUIOpenTutorialProps } from './types';
+
+/**
+ * Map redux action -> telemetry event properties
+ * Requires respective redux action to be in allowedTelemetryActions in packages/webapp/src/webview/state/middleware.ts
+ */
+export const actionMap: {
+    [action: string]: (action: LogTelemetryEvent) => any;
+} = {
+    [KHUB_OPEN_TUTORIAL]: (action: LogTelemetryEvent): TelemetryUIOpenTutorialProps => ({
+        action: 'OPEN_TUTORIAL',
+        title: action.payload?.title as string,
+        primaryTag: action.payload?.primaryTag as string
+    }),
+    [KHUB_OPEN_BLOGS]: (action: LogTelemetryEvent): TelemetryUIOpenBlogProps => ({
+        action: 'OPEN_BLOG',
+        title: action.payload?.title as string,
+        primaryTag: action.payload?.primaryTag as string
+    })
+};

packages/ide-extension/src/telemetry/index.ts

@@ -0,0 +1 @@
+export { initTelemetry, setCommonProperties, trackAction, trackEvent } from './telemetry';

packages/ide-extension/src/telemetry/telemetry.ts

@@ -0,0 +1,138 @@
+import { platform, arch, release } from 'os';
+import { env, workspace } from 'vscode';
+import type { Disposable } from 'vscode';
+import { TelemetryClient } from 'applicationinsights';
+import { logString } from '../logger/logger';
+import packageJson from '../../package.json';
+import type { TelemetryEvent, TelemetryReporter } from './types';
+import { config as dotenvConfig } from 'dotenv';
+import { join } from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { actionMap } from './action-map';
+
+// Telemetry reporter client
+let reporter: TelemetryReporter | undefined;
+
+/**
+ * Initialize telemetry.
+ *
+ * @returns - telemetry reporter
+ */
+export function initTelemetry(): TelemetryReporter {
+    if (!reporter) {
+        dotenvConfig({ path: join(__dirname, '../', `.env`) });
+        const instrumentationKey = process.env.KHE_TELEMETRY_INSTRUMENTATION_KEY;
+        if (!instrumentationKey) {
+            logString('Instrumentation key missing in .env file');
+        }
+        const enabled = updateTelemetryStatus();
+        const client = new TelemetryClient(instrumentationKey);
+        client.channel.setUseDiskRetryCaching(true);
+        client.context.tags[client.context.keys.userId] = env.machineId;
+        client.context.tags[client.context.keys.sessionId] = uuidv4();
+        client.context.tags[client.context.keys.cloudRole] = env.appName;
+
+        const disposables: Disposable[] = [];
+        disposables.push(workspace.onDidChangeConfiguration(() => updateTelemetryStatus()));
+        reporter = {
+            client,
+            enabled,
+            dispose: () => {
+                disposables.forEach((d) => d.dispose());
+                reporter = undefined;
+            }
+        };
+    }
+    return reporter;
+}
+
+/**
+ * Update the telemetry setting by reading configuration.
+ *
+ * @returns - status of telemetry setting, true: enabled; false: disabled
+ */
+function updateTelemetryStatus(): boolean {
+    const enabled = !!workspace.getConfiguration('sap.ux.knowledgeHub').get('telemetryEnabled');
+    if (reporter) {
+        reporter.enabled = enabled;
+    }
+    return enabled;
+}
+
+/**
+ * Set common properties which will be added to every telemetry event.
+ * If called without properties, all common properties are removed.
+ *
+ * @param properties - name/value pair of properties (optional)
+ * @param properties.ide - development environment VSCODE or SBAS
+ * @param properties.sbasdevSpace - SBAS devspace
+ */
+export function setCommonProperties(properties?: { ide: 'VSCODE' | 'SBAS'; sbasdevSpace: string }) {
+    if (reporter) {
+        reporter.commonProperties = properties
+            ? {
+                  'cmn.appstudio': properties.ide === 'SBAS' ? 'true' : 'false',
+                  'cmn.devspace': properties.sbasdevSpace,
+                  'common.os': platform(),
+                  'common.nodeArch': arch(),
+                  'common.platformversion': (release() || '').replace(/^(\d+)(\.\d+)?(\.\d+)?(.*)/, '$1$2$3'),
+                  'common.extname': packageJson.name,
+                  'common.extversion': packageJson.version
+              }
+            : undefined;
+    }
+}
+
+/**
+ * Track an even using telemetry.
+ *
+ * @param event - telemetry event
+ */
+export async function trackEvent(event: TelemetryEvent): Promise<void> {
+    if (!reporter?.enabled) {
+        return;
+    }
+    try {
+        const name = `${packageJson.name}/${event.name}`;
+        const properties = propertyValuesToString({ ...event.properties, ...(reporter.commonProperties ?? {}) });
+        reporter.client.trackEvent({ name, properties });
+    } catch (error) {
+        logString(`Error sending telemetry event '${event.name}': ${(error as Error).message}`);
+    }
+}
+
+/**
+ * Map specified redux actions to to telemetry events and track them.
+ *
+ * @param action - action that occurred
+ */
+export async function trackAction(action: any): Promise<void> {
+    if (!reporter?.enabled) {
+        return;
+    }
+    try {
+        if (actionMap[action.payload.action.type]) {
+            const properties = actionMap[action.payload.action.type](action.payload.action);
+            await trackEvent({ name: 'USER_INTERACTION', properties });
+        }
+    } catch (error) {
+        logString(`Error sending telemetry action '${action?.payload?.action?.type}': ${(error as Error).message}`);
+    }
+}
+
+/**
+ * Ensure all property values are strings. While type TelemetryEventProperties defines the values
+ * as string | number | any, the call LogTelemetryEvent() throws an exception if a non-string
+ * property value is passed.
+ *
+ * @param properties - key/value map of properties
+ * @returns - key/value map where all values are strings
+ */
+function propertyValuesToString(properties: { [key: string]: any }): { [key: string]: string } {
+    for (const property in properties) {
+        if (typeof properties[property] !== 'string') {
+            properties[property] = properties[property].toString();
+        }
+    }
+    return properties;
+}