🌱 Add ability to trace the jsonrpc MessageConnection (konveyor#319)

To make it easier to work between the jsonrpc server and the extension
client, add the ability to trace the messaging to an output channel.

Details:
  - The output channel's name is of the form:
    `${basename(kai-rpc-server)} message trace`

  - The trace output channel is created when the server is first started,
    and is independent from the `Konveyor-Analyzer` channel

  - Tracing is controlled by the configuration key
    `konveyor.logging.traceMessageConnection`. It is `false` by default.

Note: Supports konveyor#315

Signed-off-by: Scott J Dickerson <[email protected]>

vscode/package.json

@@ -651,6 +651,12 @@
           "description": "Should the analyzer analyze project dependencies?",
           "scope": "window",
           "order": 99
+        },
+        "konveyor.logging.traceMessageConnection": {
+          "type": "boolean",
+          "default": false,
+          "description": "Trace the jsonrpc calls between the extension and the kai server?",
+          "order": 100
         }
       }
     },

vscode/src/client/analyzerClient.ts

@@ -1,5 +1,6 @@
 import { ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { setTimeout } from "node:timers/promises";
+import { basename } from "node:path";
 import * as fs from "fs-extra";
 import * as vscode from "vscode";
 import * as rpc from "vscode-jsonrpc/node";
@@ -18,29 +19,31 @@ import { Extension } from "../helpers/Extension";
 import { ExtensionState } from "../extensionState";
 import { buildAssetPaths, AssetPaths } from "./paths";
 import {
-  getConfigLogLevel,
-  getConfigLabelSelector,
-  updateUseDefaultRuleSets,
-  getConfigKaiRpcServerPath,
+  getCacheDir,
   getConfigAnalyzerPath,
+  getConfigCustomRules,
+  getConfigKaiDemoMode,
+  getConfigKaiRpcServerPath,
+  getConfigLabelSelector,
+  getConfigLoggingTraceMessageConnection,
+  getConfigLogLevel,
   getConfigMaxDepth,
   getConfigMaxIterations,
   getConfigMaxPriority,
   getConfigMultiMaxDepth,
-  getConfigMultiMaxPriority,
   getConfigMultiMaxIterations,
-  getConfigKaiDemoMode,
+  getConfigMultiMaxPriority,
   getConfigUseDefaultRulesets,
-  getConfigCustomRules,
-  isAnalysisResponse,
-  getCacheDir,
   getTraceEnabled,
+  isAnalysisResponse,
+  updateUseDefaultRuleSets,
 } from "../utilities";
 import { allIncidents } from "../issueView";
 import { Immutable } from "immer";
 import { countIncidentsOnPaths } from "../analysis";
 import { KaiRpcApplicationConfig } from "./types";
 import { getModelProvider, ModelProvider } from "./modelProvider";
+import { tracer } from "./tracer";
 
 export class AnalyzerClient {
   private kaiRpcServer: ChildProcessWithoutNullStreams | null = null;
@@ -149,6 +152,12 @@ export class AnalyzerClient {
       new rpc.StreamMessageReader(this.kaiRpcServer.stdout),
       new rpc.StreamMessageWriter(this.kaiRpcServer.stdin),
     );
+    if (getConfigLoggingTraceMessageConnection()) {
+      this.rpcConnection.trace(
+        rpc.Trace.Verbose,
+        tracer(`${basename(this.kaiRpcServer.spawnfile)} message trace`),
+      );
+    }
     this.rpcConnection.listen();
   }
 

vscode/src/client/tracer.ts

@@ -0,0 +1,65 @@
+// Modified from https://github.com/microsoft/vscode-languageserver-node/blob/main/client/src/common/client.ts
+
+import * as vscode from "vscode";
+import { Logger, ResponseError, Tracer } from "vscode-jsonrpc/node";
+
+function isString(value: any): value is string {
+  return typeof value === "string" || value instanceof String;
+}
+
+function data2String(data: object): string {
+  if (data instanceof ResponseError) {
+    const responseError = data as ResponseError<any>;
+    return `  Message: ${responseError.message}\n  Code: ${responseError.code} ${responseError.data ? "\n" + responseError.data.toString() : ""}`;
+  }
+  if (data instanceof Error) {
+    if (isString(data.stack)) {
+      return data.stack;
+    }
+    return (data as Error).message;
+  }
+  if (isString(data)) {
+    return data;
+  }
+  return data.toString();
+}
+
+const tracerToLogOutputChannel = (channel: vscode.LogOutputChannel): Tracer => {
+  const logTrace = (message: string, data?: any) => {
+    channel.info(message);
+    if (data) {
+      channel.info(data2String(data));
+    }
+  };
+
+  const logObjectTrace = (data: any) => {
+    if (data) {
+      channel.info(JSON.stringify(data, null, 2));
+    }
+  };
+
+  const log = (messageOrDataObject: string | any, data?: string) => {
+    if (isString(messageOrDataObject)) {
+      logTrace(messageOrDataObject, data);
+    } else {
+      logObjectTrace(messageOrDataObject);
+    }
+  };
+
+  return { log };
+};
+
+/** Enable a `MessageConnection` to trace comms to a `LogOutputChannel`. */
+export const tracer = (channelName: string): Tracer => {
+  const traceLogChannel = vscode.window.createOutputChannel(channelName, {
+    log: true,
+  });
+  return tracerToLogOutputChannel(traceLogChannel);
+};
+
+export const logger = (channel: vscode.LogOutputChannel): Logger => ({
+  error: (message: string) => channel.error(message),
+  warn: (message: string) => channel.warn(message),
+  info: (message: string) => channel.info(message),
+  log: (message: string) => channel.debug(message),
+});

vscode/src/utilities/configuration.ts

@@ -18,6 +18,10 @@ export function getConfigLogLevel(): ServerLogLevels {
   return getConfigValue<ServerLogLevels>("logLevel") || "DEBUG";
 }
 
+export function getConfigLoggingTraceMessageConnection(): boolean {
+  return getConfigValue<boolean>("logging.traceMessageConnection") ?? false;
+}
+
 export function getConfigIncidentLimit(): number {
   return getConfigValue<number>("analysis.incidentLimit") || 10000;
 }