Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
155 lines (106 loc) · 5.85 KB

CONTRIBUTING.md

File metadata and controls

155 lines (106 loc) · 5.85 KB
Raw

How to Contribute to Jaeger UI

We'd love your help!

General contributing guidelines are described in Contributing Guidelines.

This document provides Jaeger UI-specific guidance to complement the general guidelines.

Setup

Prerequisites

Installation

Fork and/or clone the jaeger-ui repo and change directory into it.

git clone https://github.com/jaegertracing/jaeger-ui.git
cd jaeger-ui

Use the recommended Node versions: (defined in .nvmrc file):

nvm use

Install dependencies via pnpm:

corepack enable pnpm
pnpm install --frozen-lockfile

Running the application

Make sure you have Jaeger running on http://localhost:16686. For example, you can run Jaeger all-in-one Docker image as described in getting started documentation.

If you don't have it running locally, then tunnel to the correct host and port:

ssh -fN -L 16686:$BACKEND_HOST:$BACKEND_PORT $BACKEND_HOST

If you are using the UI Base Path feature, you need to append the base path into packages/jaeger-ui/vite.config.mts in proxyConfig object. For example, if the base path is "/jaeger", then the target should be "http://localhost:16686/jaeger" and your proxyConfig object would be:

const proxyConfig = {
  target: 'http://localhost:16686/jaeger',
  secure: false,
  changeOrigin: true,
  ws: true,
  xfwd: true,
};

Start the development server with hot loading:

pnpm start

The above command will run a web server on http://localhost:5173 that will serve the UI assets, with hot reloading support, and it will proxy all API requests to http://localhost:16686 where Jaeger query should be running.

Development Commands

Command Description
pnpm start Starts development server with hot reloading and api proxy.
pnpm test Run all the tests
pnpm --filter @jaegertracing/jaeger-ui test $file Run tests for a specific file, e.g. pnpm --filter @jaegertracing/jaeger-ui test src/api/jaeger.test.js
pnpm run lint Lint the project (oxlint, oxfmt, typescript, knip)
pnpm run fmt Format source code with Oxfmt
pnpm run build Runs production build. Outputs files to packages/jaeger-ui/build.
make bundle-stats Runs production build and outputs packages/jaeger-ui/build/bundle-stats.csv with per-package size breakdown (estimated post-minification bytes).

Code Coverage

This project uses Vitest for testing with Codecov integration for tracking.

Command Description
pnpm test -- --coverage Run all tests with full coverage report
pnpm --filter @jaegertracing/jaeger-ui test src/path/to/file.test.tsx Run a single test file
pnpm --filter @jaegertracing/jaeger-ui test src/path/to/file.test.tsx --coverage --coverage.include="src/path/to/file.tsx" Run a single test file with coverage scoped to its source file

Note: --filter @jaegertracing/jaeger-ui is required when passing a file pattern — without it, the root pnpm test also runs Vitest in packages/plexus, which finds no matching file and exits with an error. --coverage.include scopes which source files appear in the coverage report; it does not filter which tests run.

Example: pnpm --filter @jaegertracing/jaeger-ui test src/components/DeepDependencies/Graph/DdgNodeContent/index.test.tsx --coverage --coverage.include="src/components/DeepDependencies/Graph/DdgNodeContent/index.tsx"

Running on Windows OS

While we don't natively support Windows OS for running the Jaeger UI Dev Environment, you can use Windows Subsystem for Linux (WSL) to run it.

Here are some steps to follow:

  1. Install WSL: https://learn.microsoft.com/en-us/windows/wsl/install
  2. Install Node.JS: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
  3. Connect WSL Environment with VSCode: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-visual-studio-code
  4. Use the WSL Terminal inside VSCode and follow the Jaeger UI installation steps

Debugging

Debug unit tests from VSCode

Use the following launch.json configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Vitest: current file",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/node_modules/.bin/vitest",
      "args": ["run", "${file}"],
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}/packages/jaeger-ui"
    }
  ]
}

Style Guide

Use typescript for new code. Check types via pnpm run tsc-lint.

We use Oxfmt for code formatting (part of the Vite+ toolchain). It can be applied via pnpm run fmt.

Most issues will be caught by the linter, which can be applied via pnpm run oxlint.

Finally, we generally adhere to the Airbnb Style Guide, with exceptions configured in the lint section of vite.config.ts.

Toolchain configuration

All formatter and linter configuration lives in vite.config.ts as a single source of truth. To exclude a file from formatting, add it to the fmt.ignorePatterns array in vite.config.ts.

File Headers

If you are adding a new file it should have a header like below.

// Copyright (c) 2025 The Jaeger Authors.
// SPDX-License-Identifier: Apache-2.0

Cutting a Jaeger UI release

Please see RELEASE.md.