Test: LSP Inspector JSON log output and streaming

[octref]

Testing microsoft/language-server-protocol-inspector#8 and microsoft/language-server-protocol-inspector#5.

• macOS @bpasero
• linux: @chrmarti
• windows @dbaeumer

Complexity: 3

This PR comment explains the high level change: microsoft/vscode-languageserver-node#366 (comment)

JSON Log output: Language Servers that use https://github.com/Microsoft/vscode-languageserver-node have the ability to use [langId].trace.server option to direct logs to an Output Channel, see: https://code.visualstudio.com/docs/extensions/example-language-server#_logging-support-for-language-server

In the past you have the setting [langId].trace.server: "off" | "message" | "verbose". Now the format is:

[langId].trace.server: {
  verbosity: "off" | "message" | "verbose",
  "format": "text" | "json"
}

Test JSON log:

• Use the next version of vscode-languageclient and vscode-languageserver
• Modify https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-sample so that it uses the latest version of vscode-languageserver-node
• Try the old [langId].trace.server options and make sure they still work.
• Try the new option described above, and make sure both the text output and json options work as you would expect.

Test Streaming:

• The LSP Inspector has been adapted to VS Code webview. Download it at: https://github.com/octref/vscode-lsp-inspector/releases/tag/v0.0.1
• When you run the command Start LSP Inspector, it would open the LSP Inspector in a webview in VS Code. The LSP Inspector starts a websocket server listening to incoming connections that could send in the logs.
• Modify your language server, equipped with the latest version of vscode-languageserver-node, to redirect the logs through outputChannel to the LSP Inspector UI through websocket connection. You can follow the example here: https://github.com/octref/vscode-language-server-template/pull/1/files

[bpasero]

@octref @dbaeumer please update the test plan to make this test able. It seems to lack proper setup steps.

[bpasero]

Seems to work when I set "vscode-languageserver": "^5.0.3" in the server and configure:

"json.trace.server": {
    "verbosity": "verbose",
    "format": "json"
}

The warning in the settings editor is expected according to Dirk.

[bpasero]

@octref I would appreciate if you could take a bit more time to make it possible/easier for a tester to test the second part (LSP inspector). Pointing to commits is not ideal, how would a real extension author discover how to do this? At the minimum I suggest to provide a sample in our vscode-extension-sample repository that leverages this functionality. Thanks!

[dbaeumer]

The version to use should simply be "next" on the client and server

[dbaeumer]

I couldn't get the streaming to work. I added the code and the following setting but in the extension I always got that no socket is open.

	"mls.debug.log": {
		"output": "websocket",
		"port": 9999
	}

I would highly recommend to consider https://github.com/octref/vscode-lsp-inspector/issues/1 since a socket transport looks very complicated to set up.

[chrmarti]

The referenced commit does not work for me. It first complained about the connection not being open and after working around that it now fails parsing JSON in the webview. Not sure what schema it would expect. https://github.com/octref/vscode-lsp-inspector/issues/1 sounds like a good idea.

[octref]

Pointing to commits is not ideal, how would a real extension author discover how to do this? At the minimum I suggest to provide a sample in our vscode-extension-sample repository that leverages this functionality. Thanks!

@bpasero Thanks for the feedback. I should have provided more detailed instructions and a sample. Also I shouldn't test "changing your code to add WebSocket support" without writing documentation first.

However, one issue is this page (https://code.visualstudio.com/docs/extensions/example-language-server) is already a 5000 words essay. I really want to avoid adding anything too specific to it, but meanwhile our extensibility doc is already a kitchen-sink and I want to avoid making it messier.

I'll open another issue to suggest improving organization of our extensibility doc.
Mean while I added samples: microsoft/vscode-extension-samples#88. See the last section of this comment for more details.

---

It seems you are all able to test the JSON output part, so here is an updated description for testing the LSP Inspector:

Preparation

• The LSP Inspector Extension can be downloaded at: https://github.com/octref/vscode-lsp-inspector/releases/tag/v0.0.1
• The LSP Inspector Extension provides a command LSP Inspector: Start LSP Inspector, that would
  • Open a webview showing the LSP Inspector
  • Setup a WebSocket server listening at ws://localhost:7000. The port is configurable through lspInspector.port setting.
• Install this LSP Streaming Sample Extension: lsp-streaming-sample-1.0.0.vsix.zip, built from https://github.com/Microsoft/vscode-extension-samples/tree/json-streaming
• This contains a
  • Plaintext language server
  • A command Start Stream Logs into languageServerExample.port to start streaming logs into LSP Inspector

Streaming

• Make sure both extensions are installed.
• Make sure you are using the correct config for server trace, e.g.

  "languageServerExample.trace.server": {
    "format": "json",
    "verbosity": "verbose"
  }
  

• Run LSP Inspector: Start LSP Inspector first. This would open the LSP Inspector.
• Open a plaintext file. This would activate the lsp-stream-sample extension.
• Run Start Stream Logs into languageServerExample.port. This should start directing the logs into the LSP Inspector.

Check that

• You can successfully setup streaming.
• The changes in extension.ts is understandable: microsoft/vscode-extension-samples@1c98dc2#diff-52345968663124eb7bb34b94c13b77a5. So, as a Language Server extension author, you could adopt the LSP Inspector.

The Commits on branch json-streaming of vscode-extension-samples

• microsoft/vscode-extension-samples@0b80a36. This just updated vscode-languageclient and vscode-languageserver, and you get JSON tracing out of the box.
• microsoft/vscode-extension-samples@73d502a: cp -r ./lsp-sample ./lsp-stream-sample
• microsoft/vscode-extension-samples@1c98dc2: Use ws for streaming support. I argue this is not that complicated and Language Server authors should be able to set this up with docs.

[bpasero]

@octref this is very cool, I verified it works on macOS. One question: wouldn't it make sense that the LSP library is providing this functionality out of the box instead of asking each extension to create and setup a websocket connection? I wonder if you need an extra library for this or if you could not just use node.js directly (to prevent the extra dependency)?

[octref]

@bpasero There is no native WebSocket object in Node. However the ws module has a very shallow dependency tree, so it does not add too much to vscode-languageserver-node:

├─ ws@6.0.0
│  └─ async-limiter@~1.0.0

If we do end up adding WebSocket support built-in for the LS library, ws wouldn't be too much a problem.