vscgo: sidecar of the vscode go extension

We plan to collect telemetry for the VS Code Go extension's performance and usage. We would like to use the Go telemetry library, as we did for gopls, but the Go telemetry library is only available only in Go. The extension (we call it “vscode-go”) is written in Typescript. Our original plan was to have gopls collect the extension's metrics, but this plan has certain limitations:

Go telemetry groups and aggregates data using the instrumented program's name and version as the primary keys. If gopls records the extension’s performance data, the data will be classified based on the gopls version. Gopls and vscode-go have different release schedules. For example, the activation latency counter recorded by gopls v0.14.0 may be an arbitrary sum of the telemetry from vscode-go v0.39.x and v0.40.x.
Gopls may be temporarily disabled or experience problems. This is an important event to inspect for vscode-go performance, but dependency on gopls prohibits recording such events reliably.

Instead, we propose to record the extension’s telemetry using a separate program, vscgo[^1].

vscgo is released and distributed with the extension. Its functionality is tied to and tested with the specific version of the extension. When the extension is deleted or updated, it is deleted or updated. Its versioning follows the extension's, so telemetry data recorded through it can be easily associated with the extension of the same version.
vscgo is simple and small. It will have a limited number of dependencies, so it is fast to build. The current prototype is ~2.3MB on darwin. (Compared to gopls, which is ~29M.) It may grow a bit as we add more functionality in the future, but we do not expect it will ever reach the level of gopls' complexity and size.
vscgo is hosted in the same repo as vscode-go. The design and development work is driven by the vscode extension’s need, rather than other editors or general LSP client support.

We plan to introduce vscgo from the Go extension v0.41.0 (December release) for telemetry.

In the future, we plan to delegate some of the Go extension's functionalities that do not fall into gopls’ responsibilities. For example, go release watch, tools upgrade/installation, go survey prompt, coverage output conversion, playground integration. This migration will help us to reduce the amount of Typescript code in the project, and potentially encourage more Go developers to contribute.

Extension Telemetry

Old Plan: Go extension’s metrics are mixed in with gopls’ other counters. It is tricky to record gopls crash information.

Screenshot 2024-01-09 at 11 50 18 PM

Revised Plan: Go extension’s performance metrics and gopls crash info are recorded with vscode-go extension’s version info. The extension holds counters in memory, and periodically flushes them by invoking vscgo. Counters can be created and incremented before vscgo becomes available or gopls starts. Gopls crash or restart reports may be uploaded by gopls or go commands when they manage to run before the counters expire.

Screenshot 2024-01-09 at 11 50 36 PM

Code Location

github.com/golang/vscode-go/vscgo

Initially, this package will be in a separate module because the repo root module currently has many dependencies needed for the extension development work. It also contains many TS/JS code and media files that are irrelevant to the tool’s build. Our goal is to keep the vscgo module minimal. This arrangement requires extra steps during the release process: tag vscode-go/vscgo before the vscode-go during release if the extension will depend on go install vscgo@version for vscgo installation.

In early 2024, we will reorganize the project repository, in a way that the vscgo belongs to the vscode-go root module and other extension code is under a new vscode-go/extension module.

This migration plan may need intervention from the go module proxy team. golang/go#64279

Installation

The extension will install vscgo using go install during its activation. That means, ‘go’ should be present in the users’ computer.

The vscgo binary will be installed in the extension directory, not GOPATH/bin or GOBIN like other tools installed by the extension.[^4] The directory is managed by the VS Code. As the extension is installed, updated, or uninstalled, the directory will be created and deleted. Different extension versions will have different extension directories, so it is easier to manage compatibility with the extension code. Ultimately, we will consider to include a compiled binary in the extension, so this installation step is unnecessary in supported platforms.

The source of the vscgo main module is not included in the released extension.

Stable released extensions will install the vscgo at the version matching to the extension’s version.

Nightly extension’s versions are not semver nor tagged. They encode the last commit timestamps and are dynamically determined while building the extension. That means there is no tagged vscgo corresponding to the nightly extension versions. We considered some alternatives[^2] but neither is light weight. Assuming nightly is meant for users who want to stay on the bleeding edge, nightly will build vscgo from master.

When the extension runs during development (e.g. using the Development Extension Host), the extension has access to the project directory and can access the vscgo source code, so it will build from the local source code.

Extension Mode	Installation Method	Build Info	Version in Telemetry
stable release	go install vscgo@	Release version	Release version
rc	go install vscgo@	RC version	RC version
nightly/preview	go install vscgo@master	(devel)	devel
development/test	go install vscgo	(devel)	devel

We wish we could collect telemetry from nightly with meaningful version info, since nightly is how we test the stability and improvement of the upcoming releases. Unfortunately there are many obstacles. We could employ workarounds like fabricating the build info or adjusting the telemetry API to accept a custom version string (or a backdoor like cl/547879). But for now we will not take that direction yet.

In case the installation fails (for various reasons), the telemetry won’t be written to the disk, but other functionalities of the extension won’t be affected.[^3]

Status:

CL 549243 added vscgo. Nightly had been running in this mode for some time.
Tested on Mac and Windows.

Notes

[^1]: Vscode-go is the project name for the go plugin, and vscgo is the plugin’s little helper.

[^2]: Install with commit hash, daily tag the repo, hard code the compatible version, etc.

[^3]: When we start to delegate more functionalities to vscgo, however, we need to make this failure visible to users and help them to fix.

[^4]: An alternative is to use go run github.com/golang/vscode-go/vscgo@v0.41.0 ..., which won't leave the executable on disk. It's not suitable if vscgo needs to run frequently.

golang / vscode-go