Jaeger UI Frontend#

The Jaeger UI is a React/TypeScript single-page application maintained in a separate repository (jaegertracing/jaeger-ui) and tracked as a Git submodule at jaeger-ui/ in the main backend repo 1. This separation lets the UI release independently from the backend. At runtime, the compiled assets are embedded directly in the jaeger binary and served by the jaegerquery extension.

Key source entry points:

Asset Embedding and Build Pipeline#

The UI is built from source (or pulled from the jaeger-ui submodule) and embedded into the Go binary at compile time.

Build flow:

1. make rebuild-ui invokes scripts/build/rebuild-ui.sh which runs yarn build inside the submodule.
2. The build-ui Make target copies build artifacts from $(JAEGER_UI_DIR)/packages/jaeger-ui/build/ into cmd/jaeger/internal/extension/jaegerquery/internal/ui/actual/, then gzips every file 2.
3. Go's //go:embed actual/* directive bundles the .gz files into the binary at compile time 3.

At startup, GetStaticFiles() checks whether actual/index.html.gz is present. If so, it wraps the embedded filesystem with gzipfs.New() for transparent decompression; otherwise it falls back to a non-functional placeholder index.html with a warning 4. This fallback prevents binary build failures in development when the UI hasn't been built yet.

A custom assets path can be supplied at runtime via ui.assets_path (overriding the embedded bundle entirely), enabling local UI development without rebuilding the binary 5.

Dynamic Injection into index.html#

Every SPA page load triggers deriveIndexHTML(), which performs three regex substitutions on the raw index.html bytes before sending them to the browser:

Because deriveIndexHTML() runs per request, capabilities that change at runtime — notably the aiAssistant flag, which reflects a live health-check against the AI sidecar — are always current without requiring a server restart 9.

BackendCapabilities struct 10:

• archiveStorage — whether archive storage is configured
• metricsStorage — whether metrics (SPM) storage is configured
• aiAssistant — whether the AI chat sidecar is healthy (checked via aiHealthCheck())

UI config caching: The config file is read eagerly at startup for early error detection, then re-read lazily with a 10-second TTL 11. On reload errors, the previously cached value is kept so a transient disk failure doesn't break page loads 12. Config files can be .json (parsed and re-serialized) or .js (must define a function UIConfig() {}) 13.

UI Configuration Options#

The config file is wired in via the jaeger_query extension in the collector YAML 14:

extensions:
  jaeger_query:
    ui:
      config_file: /path/to/config-ui.json

The full JSON schema lives in jaeger-ui/src/types/config.ts. Key options 15:

The UIConfig struct in flags.go exposes three server-side fields: config_file, assets_path, and log_access.

Theming (Light / Dark Mode)#

Theme support is opt-in via themes.enabled in the config file 16. When enabled, a toggle button appears in the top navigation bar. The selected theme is persisted in localStorage; if no stored preference exists, the UI respects the OS-level prefers-color-scheme media query. When disabled (the default), the UI always renders in light mode 17.

Embedded Mode#

The UI supports an embedded layout mode for integrating into third-party applications. It is activated by adding uiEmbed=v0 to any URL 18, e.g.:

http://localhost:16686/trace/abc123?uiEmbed=v0

This strips chrome elements to reduce visual footprint. Supported pages: Search and Trace. Additional query parameters control the layout further — for example, uiSearchHideGraph=1 removes the scatter plot and uiTimelineHideMinimap=1 removes the minimap 19. See the full documentation for the complete parameter reference.