The vscode-trace-viewer extension enables the visualization and analysis of trace data directly within Visual Studio Code. This guide is intended to help developers understand the internal architecture of the extension, contribute to its development, and set up a development environment.

1. Getting Started
2. Development Environment Setup
3. Architecture Overview
4. Adding New Features
5. Understanding the Trace Data Formats
6. Running Tests
7. Debugging
8. Contributing
9. Best Practices
10. Additional Resources

• Node.js (v18 or later)
• npm (Node Package Manager)
• Eclipse Theia, Vscodium or Visual Studio Code (with the extension development tools installed)
• yarn the build system
• Git for version control
• Familiarity with TypeScript, JavaScript, and VSCode extension API

1. Clone the repository:

   git clone https://github.com/eclipse-cdt-cloud/vscode-trace-viewer.git
   cd vscode-trace-viewer

2. Install dependencies:

   npm install

3. Launch the extension in Theia/VSCode:

   • Press F5 to start the extension in a new VSCode window (extension development host).

• src/: Source code for the extension.
• package.json: Contains metadata about the extension and its dependencies.
• tsconfig.json: TypeScript configuration file.
• README.md: Documentation for end-users.

It's suggested to install nvm to manage node on your machine. Once that's done, install the required version:

   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

1. Install Node.js and npm from Node.js official site.
2. Install Eclispe Theia IDE from Theia official site or Visual Studio Code from VSCode official site.
3. Install the VSCode Extension Development Host via the Extensions Marketplace.
4. Clone the repository and install dependencies using npm install.

• Set up linting and prettier for code formatting.
• Use the Debugger in VSCode to step through the extension and ensure proper functionality.

1. Open the vscode-trace-viewer directory in VSCode.
2. Press F5 to launch the extension.
3. The extension will open in a new VSCode window, and you can begin interacting with it to visualize trace data.

• Theia-Trace-Extension: The place where most of the business logic resides including connections to communicate with the trace server protocol back-end as well as the views.
• Trace file openening: a view to handle opening trace files, be they folders such as ctf, or files such as trace-event json files.
• Visualization: using chart.js, and d3.js for x-y plots, ag-grid for tables and timeline-chart for gantt charts. (note, timeline-chart supports millions of entries as well as nanosecond precision)
• Event Filter: Allows users to filter trace events based on certain criteria such as time range, event type, and more.
• Inter-webview messaging: TBD
• tsp-Typescript-client: How to communicate with the trace server back-end such as Eclispe Trace Compass.
• (Suggested) vscode-server-extension: to control the server.

All data flows via the Trace Server Protocol.

• When a trace file is opened, the Trace File Handler sends the path to the trace server vi.
• The parsed data is fed into the theia-trace-extension, which create the graphical representations.
• The UI Components handle user interactions and display the visualization.

sequenceDiagram participant Trace Server participant vscode-trace-extension participant user user->>vscode-trace-extension: open trace vscode-trace-extension->>Trace Server: send trace url loop indexing Trace Server->>Trace Server: index trace end vscode-trace-extension->>Trace Server: Get available views Trace Server->>vscode-trace-extension: Available views user->>vscode-trace-extension: open view vscode-trace-extension->>vscode-trace-extension: Create view vscode-trace-extension->>Trace Server: query region Trace Server->>vscode-trace-extension: Get Data vscode-trace-extension->>vscode-trace-extension: Fill Data

1. Define the new trace data you wish to visualize.
2. Create a data provider in trace server.
3. Update the react components to include a new graph or chart type, if need be.
4. Update the trace server protocol to include a new graph or chart type, if need be.
5. Add corresponding controls in the react components to let users interact with this new feature.

TBD

The vscode-trace-extension is designed with a few restrictions.

• The data is expected to be monotonic.
• The data is not expected to be stored in the ui.
• The trace server is not expected to save the context.

Custom trace servers may use out of order events, but this workflow is currently untested.

To add support for a new trace format, follow these steps:

1. Define the new format’s structure.
2. Modify the trace server.

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

Steps for setup that only need to be run once:

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:

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:

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:

yarn playwright test

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

yarn playwright test --debug
yarn playwright test --trace on
yarn playwright test --retries <retries>

To write new tests, follow the standard format in the existing test files and ensure that your tests are comprehensive. playwright for unit testing.

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 Theia/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 Theia/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:

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

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

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

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

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

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

• Check for missing or incorrect trace data by logging the parsed data in the console.
• Use Theia/VSCode’s debugging tools to step through the event handling and visualization code to ensure correct data flow.

1. Fork the repository.
2. Create a feature branch.
3. Create a bug describing what the change does.
4. Commit your changes with descriptive messages Follow conformal commit.
5. Push the changes and submit a pull request.

• All pull requests are reviewed by project maintainers.
• Tests must pass before merging.
• New features should include documentation and examples.

If you encounter bugs or have feature requests, please report them in the GitHub issues section.

• Write Tests: Ensure that new features and bug fixes have corresponding tests.
• Code Style: Follow the existing code style and use Prettier for automatic formatting.
• Document Changes: Update the README.md or relevant documentation for any new features.

• VSCode API Documentation
• D3.js Documentation
• TypeScript Documentation