From aebc441251df25e305d7c9d459d7cfbc0d2e7851 Mon Sep 17 00:00:00 2001 From: Yury Molodov Date: Mon, 13 Mar 2023 01:16:26 +0100 Subject: [PATCH] vmui: predefined dashboards docs (#3895) * fix: correct display predefined panels * docs: update the documentation for predefined dashboards --- app/vmui/README.md | 199 +++++++++++++++++- app/vmui/packages/vmui/README.md | 56 ----- .../packages/vmui/public/dashboards/README.md | 116 +--------- .../hooks/useFetchDashboards.ts | 14 +- .../vmui/src/pages/PredefinedPanels/index.tsx | 5 +- .../src/pages/PredefinedPanels/style.scss | 18 +- 6 files changed, 221 insertions(+), 187 deletions(-) diff --git a/app/vmui/README.md b/app/vmui/README.md index 86686858c6..3730bc5303 100644 --- a/app/vmui/README.md +++ b/app/vmui/README.md @@ -2,7 +2,15 @@ Web UI for VictoriaMetrics -## Docker image build +* [Docker image build](#docker-image-build) +* [Static build](#static-build) +* [Updating vmui embedded into VictoriaMetrics](#updating-vmui-embedded-into-victoriametrics) +* [Predefined dashboards](#predefined-dashboards) +* [App mode config options](#app-mode-config-options) + +---- + +### Docker image build Run the following command from the root of VictoriaMetrics repository in order to build `victoriametrics/vmui` Docker image: @@ -19,7 +27,7 @@ docker run --rm --name vmui -p 8080:8080 victoriametrics/vmui Then navigate to `http://localhost:8080` in order to see the web UI. -## Static build +### Static build Run the following command from the root of VictoriaMetrics repository for building `vmui` static contents: @@ -30,7 +38,7 @@ make vmui-build The built static contents is put into `app/vmui/packages/vmui/` directory. -## Updating vmui embedded into VictoriaMetrics +### Updating vmui embedded into VictoriaMetrics Run the following command from the root of VictoriaMetrics repository for updating `vmui` embedded into VictoriaMetrics: @@ -53,3 +61,188 @@ bin/victoria-metrics -selfScrapeInterval=5s ``` Then navigate to `http://localhost:8428/vmui/`. See [these docs](https://docs.victoriametrics.com/#vmui) for more details. + +---- + + +## Predefined dashboards + +vmui allows you to pre-define dashboards.
+Predefined dashboards will be displayed in the `"Dashboards"` tab. +If there are no dashboards or if they cannot be fetched, the tab will be hidden. + +### Setup + +You can setup pre-defined dashboards in two ways: [Setup by local files](#setup-by-local-files) or [Setup by flag](#setup-by-flag) + +#### Setup by local files + +By creating local files in the "folder" directory: + +- In this case, to update the dashboards, you need to recompile the binary; +- These dashboards will be displayed if there are no dashboards located at the path set by the "--vmui.customDashboardsPath" flag. + +1. Create `.json` config file in a folder `app/vmui/packages/vmui/public/dashboards/` +2. Add the name of the created JSON file to `app/vmui/packages/vmui/public/dashboards/index.js` + +#### Setup by flag + +It is possible to define path to the predefined dashboards by setting `--vmui.customDashboardsPath`. +- The panels are updated when the web page is loaded; +- Only those dashboards that are located at the path specified by the `--vmui.customDashboardsPath` flag are displayed; +- Local files from the previous step are ignored. + +1. Single Version + If you use single version of the VictoriaMetrics this flag should be provided for you execution file. +``` +./victoria-metrics --vmui.customDashboardsPath=/path/to/your/dashboards +``` + +2. Cluster Version + If you use cluster version this flag should be defined for each `vmselect` component. +``` +./vmselect -storageNode=:8418 --vmui.customDashboardsPath=/path/to/your/dashboards +``` +At that moment all predefined dashboards files show be near each `vmselect`. For example +if you have 3 `vmselect` instances you should create 3 copy of your predefined dashboards. + +### Configuration options + +DashboardSettings: + +| Name | Type | Description | +|:----------|:----------------:|---------------------------:| +| rows* | `DashboardRow[]` | Sections containing panels | +| title | `string` | Dashboard title | + +
+DashboardRow: + +| Name | Type | Description | +|:-----------|:-----------------:|---------------------------:| +| panels* | `PanelSettings[]` | List of panels (charts) | +| title | `string` | Row title | + +
+PanelSettings: + +| Name | Type | Description | +|:------------|:----------:|--------------------------------------------------------------------------------------:| +| expr* | `string[]` | Data source queries | +| alias | `string[]` | Expression alias. Matched by index in array | +| title | `string` | Panel title | +| description | `string` | Additional information about the panel | +| unit | `string` | Y-axis unit | +| showLegend | `boolean` | If `false`, the legend hide. Default value - `true` | +| width | `number` | The number of columns the panel uses.
From 1 (minimum width) to 12 (full width). | + +### Example json + +```json +{ + "title": "Example", + "rows": [ + { + "title": "Per-job resource usage", + "panels": [ + { + "title": "Per-job CPU usage", + "width": 6, + "expr": [ + "sum(rate(process_cpu_seconds_total)) by (job)" + ] + }, + { + "title": "Per-job RSS usage", + "width": 6, + "expr": [ + "sum(process_resident_memory_bytes) by (job)" + ] + }, + { + "title": "Per-job disk read", + "width": 6, + "expr": [ + "sum(rate(process_io_storage_read_bytes_total)) by (job)" + ] + }, + { + "title": "Per-job disk write", + "width": 6, + "expr": [ + "sum(rate(process_io_storage_written_bytes_total)) by (job)" + ] + } + ] + }, + { + "title": "Free/used disk space", + "panels": [ + { + "unit": "MB", + "expr": [ + "sum(vm_data_size_bytes{type!=\"indexdb\"}) / 1024 / 1024", + "vm_free_disk_space_bytes / 1024 / 1024" + ], + "alias": [ + "usage space", + "free space" + ] + } + ] + } + ] +} +``` + +---- + + +## App mode config options +vmui can be used to paste into other applications + +1. Go to file `app/vmui/packages/vmui/public/index.html` +2. Find root element `
` +3. Add `data-params` with the options + +### Options (JSON): + +| Name | Default | Description | +|:------------------------|:-----------:|--------------------------------------------------------------------------------------:| +| serverURL | domain name | Can't be changed from the UI | +| useTenantID | - | If the flag is present, the "Tenant ID" select is displayed | +| headerStyles.background | `#FFFFFF` | Header background color | +| headerStyles.color | `#3F51B5` | Header font color | +| palette.primary | `#3F51B5` | used to represent primary interface elements for a user | +| palette.secondary | `#F50057` | used to represent secondary interface elements for a user | +| palette.error | `#FF4141` | used to represent interface elements that the user should be made aware of | +| palette.warning | `#FF9800` | used to represent potentially dangerous actions or important messages | +| palette.success | `#4CAF50` | used to indicate the successful completion of an action that user triggered | +| palette.info | `#03A9F4` | used to present information to the user that is neutral and not necessarily important | + +### JSON example: + +```json +{ + "serverURL": "http://localhost:8428", + "useTenantID": true, + "headerStyles": { + "background": "#FFFFFF", + "color": "#538DE8" + }, + "palette": { + "primary": "#538DE8", + "secondary": "#F76F8E", + "error": "#FD151B", + "warning": "#FFB30F", + "success": "#7BE622", + "info": "#0F5BFF" + } +} +``` + +### HTML example: + +```html +
+``` diff --git a/app/vmui/packages/vmui/README.md b/app/vmui/packages/vmui/README.md index 35bb4ad397..74a58ed98b 100644 --- a/app/vmui/packages/vmui/README.md +++ b/app/vmui/packages/vmui/README.md @@ -45,59 +45,3 @@ You don’t have to ever use `eject`. The curated feature set is suitable for sm You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started). To learn React, check out the [React documentation](https://reactjs.org/). - ---- - -# VMUI config options -VMUI can be used to paste into other applications - -1. Go to file `index.html` -2. Find root element `
` -3. Add `data-params` with the options - -#### Options (JSON): - -| Name | Default | Description | -|:------------------------|:-----------:|--------------------------------------------------------------------------------------:| -| serverURL | domain name | Can't be changed from the UI | -| useTenantID | - | If the flag is present, the "Tenant ID" select is displayed | -| headerStyles.background | `#FFFFFF` | Header background color | -| headerStyles.color | `#3F51B5` | Header font color | -| palette.primary | `#3F51B5` | used to represent primary interface elements for a user | -| palette.secondary | `#F50057` | used to represent secondary interface elements for a user | -| palette.error | `#FF4141` | used to represent interface elements that the user should be made aware of | -| palette.warning | `#FF9800` | used to represent potentially dangerous actions or important messages | -| palette.success | `#4CAF50` | used to indicate the successful completion of an action that user triggered | -| palette.info | `#03A9F4` | used to present information to the user that is neutral and not necessarily important | - -#### JSON example: -```json -{ - "serverURL": "http://localhost:8428", - "useTenantID": true, - "headerStyles": { - "background": "#FFFFFF", - "color": "#538DE8" - }, - "palette": { - "primary": "#538DE8", - "secondary": "#F76F8E", - "error": "#FD151B", - "warning": "#FFB30F", - "success": "#7BE622", - "info": "#0F5BFF" - } -} -``` - - -#### HTML example: -```html -
-``` - - - - - - diff --git a/app/vmui/packages/vmui/public/dashboards/README.md b/app/vmui/packages/vmui/public/dashboards/README.md index 4bb347e89f..1fab50792c 100644 --- a/app/vmui/packages/vmui/public/dashboards/README.md +++ b/app/vmui/packages/vmui/public/dashboards/README.md @@ -1,115 +1,3 @@ -### Setup -1. Create `.json` config file in a folder `dashboards` -2. Import your config file into the `dashboards/index.js` -3. Add filename into the array `window.__VMUI_PREDEFINED_DASHBOARDS__` +## Predefined dashboards -It is possible to define path to the predefined dashboards by setting `--vmui.customDashboardsPath`. - -1. Single Version -If you use single version of the VictoriaMetrics this flag should be provided for you execution file. -``` -./victoria-metrics --vmui.customDashboardsPath=/path/to/your/dashboards -``` - -2. Cluster Version -If you use cluster version this flag should be defined for each `vmselect` component. -``` -./vmselect -storageNode=:8418 --vmui.customDashboardsPath=/path/to/your/dashboards -``` -At that moment all predefined dashboards files show be near each `vmselect`. For example -if you have 3 `vmselect` instances you should create 3 copy of your predefined dashboards. - - - -### Configuration options - -
-DashboardSettings: - -| Name | Type | Description | -|:----------|:----------------:|---------------------------:| -| rows* | `DashboardRow[]` | Sections containing panels | -| title | `string` | Dashboard title | - -
-DashboardRow: - -| Name | Type | Description | -|:-----------|:-----------------:|---------------------------:| -| panels* | `PanelSettings[]` | List of panels (charts) | -| title | `string` | Row title | - -
-PanelSettings: - -| Name | Type | Description | -|:------------|:----------:|--------------------------------------------------------------------------------------:| -| expr* | `string[]` | Data source queries | -| alias | `string[]` | Expression alias. Matched by index in array | -| title | `string` | Panel title | -| description | `string` | Additional information about the panel | -| unit | `string` | Y-axis unit | -| showLegend | `boolean` | If `false`, the legend hide. Default value - `true` | -| width | `number` | The number of columns the panel uses.
From 1 (minimum width) to 12 (full width). | - ---- - -### Example json - -```json -{ - "title": "Example", - "rows": [ - { - "title": "Per-job resource usage", - "panels": [ - { - "title": "Per-job CPU usage", - "width": 6, - "expr": [ - "sum(rate(process_cpu_seconds_total)) by (job)" - ] - }, - { - "title": "Per-job RSS usage", - "width": 6, - "expr": [ - "sum(process_resident_memory_bytes) by (job)" - ] - }, - { - "title": "Per-job disk read", - "width": 6, - "expr": [ - "sum(rate(process_io_storage_read_bytes_total)) by (job)" - ] - }, - { - "title": "Per-job disk write", - "width": 6, - "expr": [ - "sum(rate(process_io_storage_written_bytes_total)) by (job)" - ] - } - ] - }, - { - "title": "Free/used disk space", - "panels": [ - { - "unit": "MB", - "expr": [ - "sum(vm_data_size_bytes{type!=\"indexdb\"}) / 1024 / 1024", - "vm_free_disk_space_bytes / 1024 / 1024" - ], - "alias": [ - "usage space", - "free space" - ] - } - ] - } - ] -} - -``` +See [this docs](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/app/vmui#predefined-dashboards) diff --git a/app/vmui/packages/vmui/src/pages/PredefinedPanels/hooks/useFetchDashboards.ts b/app/vmui/packages/vmui/src/pages/PredefinedPanels/hooks/useFetchDashboards.ts index ac90a8dff6..dcfa3dbb2f 100755 --- a/app/vmui/packages/vmui/src/pages/PredefinedPanels/hooks/useFetchDashboards.ts +++ b/app/vmui/packages/vmui/src/pages/PredefinedPanels/hooks/useFetchDashboards.ts @@ -24,10 +24,14 @@ export const useFetchDashboards = (): { const [dashboardsSettings, setDashboards] = useState([]); const fetchLocalDashboards = async () => { - const filenames = window.__VMUI_PREDEFINED_DASHBOARDS__; - if (!filenames?.length) return []; - const dashboards = await Promise.all(filenames.map(async f => importModule(f))); - setDashboards((prevDash) => [...dashboards, ...prevDash]); + try { + const filenames = window.__VMUI_PREDEFINED_DASHBOARDS__; + if (!filenames?.length) return []; + const dashboards = await Promise.all(filenames.map(async f => importModule(f))); + setDashboards((prevDash) => [...dashboards, ...prevDash]); + } catch (e) { + if (e instanceof Error) setError(`${e.name}: ${e.message}`); + } }; const fetchRemoteDashboards = async () => { @@ -43,6 +47,8 @@ export const useFetchDashboards = (): { const { dashboardsSettings } = resp; if (dashboardsSettings && dashboardsSettings.length > 0) { setDashboards((prevDash) => [...prevDash, ...dashboardsSettings]); + } else { + await fetchLocalDashboards(); } setIsLoading(false); } else { diff --git a/app/vmui/packages/vmui/src/pages/PredefinedPanels/index.tsx b/app/vmui/packages/vmui/src/pages/PredefinedPanels/index.tsx index 52d1ab3ba3..c6add4b0a7 100644 --- a/app/vmui/packages/vmui/src/pages/PredefinedPanels/index.tsx +++ b/app/vmui/packages/vmui/src/pages/PredefinedPanels/index.tsx @@ -34,14 +34,13 @@ const DashboardsLayout: FC = () => { return
{dashboardsLoading && } - {dashboardsError && {dashboardsError}} + {!dashboardsSettings.length && dashboardsError && {dashboardsError}} {!dashboardsSettings.length && Dashboards not found} {dashboards.length > 1 && (
{dashboards.map(tab => ( diff --git a/app/vmui/packages/vmui/src/pages/PredefinedPanels/style.scss b/app/vmui/packages/vmui/src/pages/PredefinedPanels/style.scss index 5b83cf0987..dac39b1783 100644 --- a/app/vmui/packages/vmui/src/pages/PredefinedPanels/style.scss +++ b/app/vmui/packages/vmui/src/pages/PredefinedPanels/style.scss @@ -13,10 +13,6 @@ padding: $padding-small 0; } - &-tabs.vm-block { - padding: $padding-global; - } - &-tabs { display: flex; flex-wrap: wrap; @@ -24,19 +20,27 @@ justify-content: flex-start; font-size: $font-size-small; gap: $padding-small; - white-space: nowrap; overflow: hidden; + @media (max-width: 768px) { + padding: 0 $padding-global; + } + &__tab { padding: $padding-small $padding-global; border-radius: $border-radius-medium; cursor: pointer; transition: background 200ms ease-in-out, color 150ms ease-in; - background: $color-white; + background: $color-background-block; text-transform: uppercase; - color: rgba($color-black, 0.2); + color: $color-text-secondary; + text-align: center; border: 1px solid rgba($color-black, 0.2); + @media (max-width: 500px) { + flex-grow: 1; + } + &:hover { color: $color-primary; }