Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eclipse-cdt-cloud/vscode-trace-extension

Trace viewer extension for Eclipse Theia applications and VSCode compatible applications, that uses the Trace Server Protocol (TSP)
https://github.com/eclipse-cdt-cloud/vscode-trace-extension

eclipse eclipse-foundation eclipse-theia javascript open-vsx timeline-chart trace trace-server-protocol trace-viewer trace-visualization traceviewer-base traceviewer-react-components tsp tsp-typescript-client typescript visual-studio-marketplace vscode vscode-extension vscode-trace-extension

Last synced: 15 days ago
JSON representation

Trace viewer extension for Eclipse Theia applications and VSCode compatible applications, that uses the Trace Server Protocol (TSP)

Awesome Lists containing this project

README 

        
# VSCode Trace Extension



This document contains information that may be useful for developers that want to build, modify, enhance and/or debug this extension. If you only intend to consume the extension, it might be easier to get it from the [public OpenVSX registry][tc-open-vsx],



This project started from the [VSCode webview react project][vscode-webview-react]. It works this way, with the extension itself being in the `vscode-trace-extension` directory and the react application being in the `vscode-trace-webapps` directory.



**👋 Want to help?** Read our [contributor guide](CONTRIBUTING.md) and follow the instructions to contribute code.



## Prerequisites



First, you need Node.js and yarn:



It's suggested to install [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) to manage node on your machine. Once that's done, install the required version:



```bash

   nvm install 18

   # optional: make it the default version

   nvm alias default

   # or set it every time like so

   nvm use 18

```



Then install `yarn`:



```bash

npm i -g yarn  # the default version should be ok

```



## Installation Instructions



It depends on the trace viewer plugins (traceviewer_base and traceviewer_react_components) from the [theia trace extension package][theia-trace] and the [tsp typescript client][tsp-client], as well as the [timeline chart][timeline-chart]. They are all available from the NPM package registry.



- timeline-chart

- traceviewer-base

- traceviewer-react-components

- tsp-typescript-client



To build the VSCode extension, run the `yarn` command:



``` bash

yarn

```

### Building from local sources



To build local changes in the above libraries you need to build the libaries from source code and link them to the vscode-trace-extension repository. Follow instructions on the above repositories to clone and build the libraries.



After cloing the libraries, you need to link each library so that a local build can be used. Using command `yarn link` a reference link into the user's home directory is created under `~/.config/yarn/link`. 

The `yarn link` command makes sure that the libraries are available locally and can be linked from the `vscode-trace-extension`. This also avoids conflicts caused by different versions of the librares and their dependencies used in the corresponding repositories.



Make sure that you don't have links in `~/.config/yarn/link` from other repositories than relevant for the trace viewer. The `yarn link` command won't override exising links. For example, if there is a link to `react` with the wrong version, then there will be runtime exection problems. Remove links beforehand.



Assuming all repositories are stored in your home directory under the `rootDir=~/git`



```bash

cd $rootDir/tsp-typescript-client

yarn

cd tsp-typescript-client

yarn link

```



```bash

cd $rootDir/timeline-chart

yarn

cd timeline-chart

yarn link

```



```bash

cd $rootDir/theia-trace-extension

yarn link tsp-typescript-client

yarn link timeline-chart

yarn

cd packages/base

yarn link

cd ../react-components

yarn link

cd ../../node-modules/react

yarn link

```



To link the local dependencies to this repository, run the following commands:



```bash

cd $rootDir/vscode-trace-extension

yarn link tsp-typescript-client

yarn link timeline-chart

yarn link traceviewer-base

yarn link traceviewer-react-components

yarn link react

```



After linking the local dependencies on this repo and before running the vscode extension, run the `yarn` command:



```bash

yarn

```



### Removing links to local sources



To remove the links execute the following commands:



```bash

cd $rootDir/vscode-trace-extension

yarn unlink tsp-typescript-client

yarn un link timeline-chart

yarn unlink traceviewer-base

yarn unlink traceviewer-react-components

yarn unlink react

```



```bash

cd $rootDir/theia-trace-extension

yarn unlink tsp-typescript-client

yarn unlink timeline-chart

```



Note that you will need to run `yarn install --force` to re-install the packages that were linked.



```bash

yarn install --force

```



## Running the extension



Then from VSCode, press `f5` to run the extension. The trace server needs to be started separately as described [here](#run-the-trace-server).



To open a trace use the VSCode file explorer to navigate to the trace directory. Then right mouse click on the trace and select menu option `Open with Trace Viewer`. See [here](#get-sample-traces) to get some sample traces.



Open the `Trace Viewer` view (`View` -> `Open view...`).



![open-trace][open-trace]



Two tabs will be visible: `Traces` and `Views`. The `Traces` tab will show all available traces on the trace server.



The `Views` tab shows all the available views for the selected trace. Click on a view to open the view under the timeline.



![open-output][open-output]



## Package as a VSCode extension (.vsix)



To package it as VSCode extension, run the command `yarn vsce:package`. If you get errors about case-sensitive files, just delete the node_modules folder and run `yarn` again.



The packaging will produce a `vscode-trace-extension-x.x.x.vsix` file in the subdirectory `vscode-trace-extension` of the repository.



## Running the extension in VSCode, VsCodium or Theia application



The packaged VSIX file can be installed in an existing `VSCode`, `VSCodium` or `Theia` application by using [Install from a vsix][install].



The trace server needs to be started separately as described [here](#run-the-trace-server).



## Running the extension in the Theia Trace Viewer example app



The packaged VSIX file can be run in the example app of the [theia-trace-extension][theia-trace]. For this the file can be can be symlinked in the `plugins` of the example app of `theia-trace-extension` repository.



``` bash

cd /examples/plugins

ln -s /vscode-trace-extension-x.x.x.vsix ./

```



## Developing the extension



From the root directory execute `yarn run watch`.  This will watch and bundle `vscode-trace-common`, `vscode-trace-extension`, and `vscode-trace-webviews`.  All outputs will be in one terminal.  Changes can be observed and tested in the `Extension Development Host` by pressing `F5`.



For more information about `VSCode WebView API` see [here][vscode-webview].



### Communication between components



To communicate between VSCode extension and webviews use the [VSCode message API][vscode-messages]. When using `vscode.postMessage(data)` data structure `data` will be serialized to JSON before being propagated. Be aware that it cannot include data structures like `BigInt`. Proper handling of such data structures need to be implemented when sending and receiving messages.



Inside a webview or inside the extension signals can be used where data structures can be passed on.



The following sequence diagram shows how the `experiment-selected` signal (with payload `Experiment`) is propagated inside the application. The webview `Opened Traces WebView App` is sending the signal to the`VSCode extension` which is forwarding the signal to the `Available Views WebView App`.



```mermaid

sequenceDiagram

    actor User

    participant reactOpenTraces as ReactOpenTracesWidget

    participant explorerOpenTraces as TraceExplorerOpenedTraces

    participant exOpenTraceProvider as TraceExplorerOpenedTracesViewProvider

    participant exViewsAvailProvider as TraceExplorerAvailableViewsProvider

    participant explorerAvailView as TraceExplorerViewsWidget

    participant reactAvailViewsexplorerOpenTraces as ReactAvailableViewsWidget

    participant server as Trace Server

    User->>reactOpenTraces: click on trace

    Note over reactOpenTraces,explorerOpenTraces: Opened Traces WebView App

    Note over exOpenTraceProvider,exViewsAvailProvider: VsCode extension

    Note over explorerAvailView,reactAvailViewsexplorerOpenTraces: Available Views WebView App

    reactOpenTraces->>explorerOpenTraces: sendSignal(exp-sel)

    explorerOpenTraces->>exOpenTraceProvider: vscode.postMessage(exp-sel)

    exOpenTraceProvider->>exViewsAvailProvider: sendSignal(exp-sel)

    exViewsAvailProvider->>explorerAvailView: vscode.postMessage(exp-sel)

    explorerAvailView->>reactAvailViewsexplorerOpenTraces: sendSignal(exp-sel)

    reactAvailViewsexplorerOpenTraces->>server: fetchOutputs(exp)

    server->>reactAvailViewsexplorerOpenTraces: success(200)

    reactAvailViewsexplorerOpenTraces->>reactAvailViewsexplorerOpenTraces: visualize availableViews

```



### Debugging the extension



It is straightforward to debug the code of the VSCode extension itself (the code in `vscode-trace-extension`) by just putting breakpoints in VSCode and running the extension with `f5`.



The react-app is another matter. The panel is a webview that is running in its own context, so current VSCode does not have access to it. _(Patches welcome!)_



Each panel is its own small web application, so to debug, while in the context of the webview, press `ctrl-shift-p` and enter the command `Developer: Open Webview Developer Tools`. This will open the developer tools. The code is in the `Sources` tab of the developer tools window that opens.



### Logging in the extension



The extension uses an output channel for logging. To view the logs, navigate to the output panel. The output panel can be accessed by navigating to view -> open view -> type 'output'. To open the extension output channel, navigate the drop down option and look for `Trace Extension`. An alternate way of opening the trace extension output channel is through command palette. Open command palette by pressing `ctrl-shift-p`, and then run `Output: Show Output Channels...\`. This will prompt a list of available outputs. Select `Trace Extension` from the list of available outputs.



For logging to the `Trace Extension` output channel, use the `traceLogger` object instantiated in `extension.ts`. The following are examples of using the log channel:



```javascript

traceLogger.addLogMessage('Hello from trace extension without tag');

```



This will add the following log entry in the output channel:



```text

[2023-04-25 11:07:22.500] Hello from trace extension without tag

```



```javascript

traceLogger.addLogMessage('Hello from trace extension with tag', 'tag');

```



This will add the following log entry in the output channel:



```text

[2023-04-25 11:08:40.500] [tag] Hello from trace extension with tag

```



### Troubleshooting



*The `Trace Viewer` panel is not there, or disappears when switching panel.



Right-click on the vscode activity bar and make sure `Trace Viewer` is checked.



![trace-explorer-activity-bar][trace-explorer-activity-bar]



## Run the Trace Server



In order to open traces, you need a trace server running on the same machine as the trace extension. You can download the [Eclipse Trace Compass server][tc-server] or let `yarn` download and run it:



```bash

yarn download:server

yarn start:server

```



You can also build the trace-server yourself using Trace Compass and the Incubator. Take a look at the [instructions here][tc-server-build].



## Get sample traces



To get sample traces to try run the following command. The traces will be stored under the subdirectory `TraceCompassTutorialTraces` of the repository.



```bash

yarn download:sample-traces

```



## Running UI tests



To run the UI tests locally, use the following commands.



Steps for setup that only need to be run once:



```bash

yarn download:sample-traces

yarn download:server

yarn download:openvscode-server

yarn configure:openvscode-server

yarn playwright install --with-deps

```



Steps to run once and again every time the application code is modified:



```bash

yarn

yarn vsce:package

# kill openvscode-server if running and restart it below

```



Steps to run once if the corresponding server is not already running:



```bash

yarn start:server & # or run in a separate shell

yarn start:openvscode-server & # or run in a separate shell

```



To run or re-run the tests after test code is modified:



```bash

yarn playwright test

```



To test in debug mode, test with tracing on, or test with retries on failure, use the following options:



```bash

yarn playwright test --debug

yarn playwright test --trace on

yarn playwright test --retries 

```



## Using the External API



VSCode Trace Extension provides an external API that adopter extensions can rely on for communication. Currently the API is limited to the following:



```javascript

getActiveExperiment(): Experiment | undefined

getActiveWebviewPanels(): { [key: string]: TraceViewerPanel | undefined; }

getActiveWebviews(): vscode.WebviewView[]

onWebviewCreated(listener: (data: vscode.WebviewView) => void): void

onWebviewPanelCreated(listener: (data: vscode.WebviewPanel) => void): void

onSignalManagerSignal(event: string | symbol, listener: (...args: unknown[]) => void): void;

offSignalManagerSignal(event: string | symbol, listener: (...args: unknown[]) => void): void;

addTraceServerContributor(contributor: TraceServerContributor): void;

setHandleTraceResourceType(handleFiles: boolean, handleFolders: boolean): void;

```



### Using the API from Adopter Extensions



```javascript

//The following retrieves the API object from the vscode-trace-extension

const ext = vscode.extensions.getExtension("eclipse-cdt.vscode-trace-extension");

const importedApi = ext.exports;

```



Once you have the API object, you can proceed to make API calls. For example, if you wish to retrieve the active experiment in the Trace Viewer, the following API call can be used:



```javascript

const experiment = importedApi.getActiveExperiment();

```



The API provides getters to retrieve the active webviews and panels. This can be useful for scenarios when webviews/panels were created before the adopter extension was activated but the adopter extension still wants to handle messages from them.



```javascript

for (const webview of importedApi.getActiveWebviews()) {

    webview.webview.onDidReceiveMessage((message) => {

        switch (message.command) {

            case "webviewReady":

            console.log("From adopter extension - webviewReady signal received");

            break;

            default:

            break;

        }

    });

}

```



The API also provides a way to attach a listener for when webview or webview panel is created. Note that this listener will not be called for webviews and panels created before the registration of the listener. It is recommended to register the listeners during the activation of the adopter extensions.



```javascript

importedApi.onWebviewPanelCreated(_panel => {

    // For newly created panel, handle messages from webviews

    _panel.webview.onDidReceiveMessage((message) => {

        switch (message.command) {

            case "webviewReady":

            console.log("From adopter extension - webviewReady signal received");

            break;

            default:

            break;

        }

    });

    _panel.onDidDispose(() => {

        console.log("panel disposed");

    });

});

```



As a general rule, adopter extensions should retrieve and handle the webviews and webview panels once during their activation by calling `getActiveWebviews` and `getActiveWebviewPanels`. This ensures that the webviews and panels created before the activation of the adopter extension are handled. To handle any new webviews and panels created afterwards, listeners can be registered by calling `onWebviewCreated` and `onWebviewPanelCreated`.



The adopter extensions can also add and remove listeners to signals propagated within the base extension.



```javascript

const _onExperimentOpened = (experiment: Experiment): void => {

    console.log(experiment.UUID);

};

//Add a listener

importedApi.onSignalManagerSignal('experiment opened', _onExperimentOpened);

//Remove a listener

importedApi.offSignalManagerSignal('experiment opened', _onExperimentOpened);

```



If the adopter extensions needs to add a custom hook to the trace server's start/stop API, a contribution can be made by calling `addTraceServerContributor`.



```javascript

const contributor: TraceServerContributor = {

    startServer: async () => { 

        //Perform pre-startup actions

        //Start the server

        console.log("server started"); 

        },

    stopServer: async () => {

        //Perform cleanup actions

        //Stop the server

        console.log("server stopped"); 

    },

    isApplicable: (pathToTrace: string) => {

        //Check whether this contributor applies for the trace at 'pathToTrace'

        return true; 

    }

  };



importedApi.addTraceServerContributor(contributor);

```



If adopter extensions want to customize the type of trace resources (File and/or Folder) that the base extension should handle, it can be set by calling `setHandleTraceResourceType`.



```javascript

const handleTraceFiles = true;

const handleTraceFolders = false;



//The base extension will only provide support for trace files, and not for trace folders

importedApi.setHandleTraceResourceType(handleTraceFiles, handleTraceFolders);

```



### Remote SSH Support



The `Trace Viewer for VSCode` extension is compatible with the use of [remote-ssh](https://code.visualstudio.com/docs/remote/ssh).  If you are using `remote-ssh`, you can simply install `Trace Viewer for VSCode` extension on your remote machine and begin using the extension. For VSCode compatible applications you can install the [open-remote-ssh][open-remote-ssh] extension from the [public OpenVSX registry][open-vsx] to get similar functionality.



The remote support works by forwarding the Trace Server's operating port from the client machine to the remote machine. The port is automatically forwarded on Trace Server startup.



Forwarded ports can be seen in the 'Ports' view of the remote VsCode.  To open the `Ports` view use menu `View -> Open view... -> Ports`.  You should see the forwarded Trace Server port in the `Ports` view, as shown below:



![ports-tab][vscode-ports-tab]



Make sure that there is no Trace Server running on your local host. If the `Trace Viewer for VSCode` is unresponsive, stop the port forwarding by pressing the 'Stop Port Fowarding (Delete)' of the trace server port and restart remote VSCode.



If you are a developers of the `Trace Viewer for VsCode` and want to modify and test the extension, you can [package it as a VSCode extension (.vsix)](#package-as-a-vscode-extension-vsix), upload the `VSIX` to the remote host and install the extension using the `Install from VSIX...` view menu of the `Extensions` view.



## Release/publish



We use GitHub CI to create a GitHub release and the corresponding git tag, and also to publish this repo's VSCode extension to the `open-vsx.org` and the `Visual Studio Marketplace` registries.



### Triggering a new release



Whenever a new release is desired, it can be triggered through a PR, as per the following:



Create a new branch for your PR, based on the repo's latest state. e.g.



```bash

git branch new-release && git checkout new-release

```



Then decide if the release shall be a `Major`, `Minor` or `Patch` release and use the corresponding command below to step the package's versions, according to the release type. A new release commit will be created:



``` bash

yarn version:major

# or

yarn version:minor

# or

yarn version:patch

```



Modify the _version tag_ in file `./RELEASE`, to match the new release. Amend the release commit to include this change:



```bash

git add RELEASE && git commit --amend

```



Finally, push the branch to the main repository (not a fork!) and use it to create a PR. When the PR is merged, a GitHub release should be created with auto-generated release notes, as well as a git tag. Then the `publish-*` CI jobs should trigger, and if everything goes well, publish the new version of the extension to both registries.



## Intital contribution

The code was migrated from the [PR in theia-trace-extension][init-contrib].



[init-contrib]: https://github.com/eclipse-cdt-cloud/theia-trace-extension/pull/124

[install]: https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix

[open-output]: https://raw.githubusercontent.com/eclipse-cdt-cloud/vscode-trace-extension/master/doc/images/vscode-trace-extension-001.png

[open-remote-ssh]: https://open-vsx.org/extension/jeanp413/open-remote-ssh

[open-trace]: https://raw.githubusercontent.com/eclipse-cdt-cloud/vscode-trace-extension/master/doc/images/vscode-open-with-trace-viewer-001.png

[open-vsx]: https://www.open-vsx.org/

[theia-trace]: https://github.com/eclipse-cdt-cloud/theia-trace-extension/

[tc-open-vsx]: https://www.open-vsx.org/extension/eclipse-cdt/vscode-trace-extension

[tc-server]: https://download.eclipse.org/tracecompass.incubator/trace-server/rcp/?d

[tc-server-build]: https://www.eclipse.org/tracecompass/download.html#trace-server

[timeline-chart]: https://github.com/eclipse-cdt-cloud/timeline-chart/

[trace-explorer-activity-bar]: https://raw.githubusercontent.com/eclipse-cdt-cloud/vscode-trace-extension/master/doc/images/vscode-show-trace-viewer-001.png

[tsp-client]: https://github.com/eclipse-cdt-cloud/tsp-typescript-client/

[vscode-messages]: https://code.visualstudio.com/api/extension-guides/webview#passing-messages-from-an-extension-to-a-webview

[vscode-webview]: https://github.com/rebornix/vscode-webview-react

[vscode-webview-react]: https://github.com/rebornix/vscode-webview-react

[vscode-ports-tab]: https://raw.githubusercontent.com/eclipse-cdt-cloud/vscode-trace-extension/master/doc/images/vscode-ports-tab-001.png