vmui: predefined dashboards docs (#3895)

* fix: correct display predefined panels

* docs: update the documentation for predefined dashboards
This commit is contained in:
Yury Molodov 2023-03-13 01:16:26 +01:00 committed by Aliaksandr Valialkin
parent 7d37ab63a5
commit aebc441251
No known key found for this signature in database
GPG key ID: A72BEC6CD3D0DED1
6 changed files with 221 additions and 187 deletions

View file

@ -2,7 +2,15 @@
Web UI for VictoriaMetrics 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: 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. 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: 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. 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: 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. 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. <br/>
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 |
<br/>
DashboardRow:
| Name | Type | Description |
|:-----------|:-----------------:|---------------------------:|
| panels* | `PanelSettings[]` | List of panels (charts) |
| title | `string` | Row title |
<br/>
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.<br/> 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 `<div id="root"></div>`
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
<div id="root" data-params='{"serverURL":"http://localhost:8428","useTenantID":true,"headerStyles":{"background":"#FFFFFF","color":"#538DE8"},"palette":{"primary":"#538DE8","secondary":"#F76F8E","error":"#FD151B","warning":"#FFB30F","success":"#7BE622","info":"#0F5BFF"}}'></div>
```

View file

@ -45,59 +45,3 @@ You dont 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). 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/). 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 `<div id="root"></div>`
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
<div id="root" data-params='{"serverURL":"http://localhost:8428","useTenantID":true,"headerStyles":{"background":"#FFFFFF","color":"#538DE8"},"palette":{"primary":"#538DE8","secondary":"#F76F8E","error":"#FD151B","warning":"#FFB30F","success":"#7BE622","info":"#0F5BFF"}}'></div>
```

View file

@ -1,115 +1,3 @@
### Setup ## Predefined dashboards
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__`
It is possible to define path to the predefined dashboards by setting `--vmui.customDashboardsPath`. See [this docs](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/app/vmui#predefined-dashboards)
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
<br/>
DashboardSettings:
| Name | Type | Description |
|:----------|:----------------:|---------------------------:|
| rows* | `DashboardRow[]` | Sections containing panels |
| title | `string` | Dashboard title |
<br/>
DashboardRow:
| Name | Type | Description |
|:-----------|:-----------------:|---------------------------:|
| panels* | `PanelSettings[]` | List of panels (charts) |
| title | `string` | Row title |
<br/>
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.<br/> 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"
]
}
]
}
]
}
```

View file

@ -24,10 +24,14 @@ export const useFetchDashboards = (): {
const [dashboardsSettings, setDashboards] = useState<DashboardSettings[]>([]); const [dashboardsSettings, setDashboards] = useState<DashboardSettings[]>([]);
const fetchLocalDashboards = async () => { const fetchLocalDashboards = async () => {
try {
const filenames = window.__VMUI_PREDEFINED_DASHBOARDS__; const filenames = window.__VMUI_PREDEFINED_DASHBOARDS__;
if (!filenames?.length) return []; if (!filenames?.length) return [];
const dashboards = await Promise.all(filenames.map(async f => importModule(f))); const dashboards = await Promise.all(filenames.map(async f => importModule(f)));
setDashboards((prevDash) => [...dashboards, ...prevDash]); setDashboards((prevDash) => [...dashboards, ...prevDash]);
} catch (e) {
if (e instanceof Error) setError(`${e.name}: ${e.message}`);
}
}; };
const fetchRemoteDashboards = async () => { const fetchRemoteDashboards = async () => {
@ -43,6 +47,8 @@ export const useFetchDashboards = (): {
const { dashboardsSettings } = resp; const { dashboardsSettings } = resp;
if (dashboardsSettings && dashboardsSettings.length > 0) { if (dashboardsSettings && dashboardsSettings.length > 0) {
setDashboards((prevDash) => [...prevDash, ...dashboardsSettings]); setDashboards((prevDash) => [...prevDash, ...dashboardsSettings]);
} else {
await fetchLocalDashboards();
} }
setIsLoading(false); setIsLoading(false);
} else { } else {

View file

@ -34,14 +34,13 @@ const DashboardsLayout: FC = () => {
return <div className="vm-predefined-panels"> return <div className="vm-predefined-panels">
{dashboardsLoading && <Spinner />} {dashboardsLoading && <Spinner />}
{dashboardsError && <Alert variant="error">{dashboardsError}</Alert>} {!dashboardsSettings.length && dashboardsError && <Alert variant="error">{dashboardsError}</Alert>}
{!dashboardsSettings.length && <Alert variant="info">Dashboards not found</Alert>} {!dashboardsSettings.length && <Alert variant="info">Dashboards not found</Alert>}
{dashboards.length > 1 && ( {dashboards.length > 1 && (
<div <div
className={classNames({ className={classNames({
"vm-predefined-panels-tabs": true, "vm-predefined-panels-tabs": true,
"vm-block": true, "vm-predefined-panels-tabs_mobile": isMobile,
"vm-block_mobile": isMobile,
})} })}
> >
{dashboards.map(tab => ( {dashboards.map(tab => (

View file

@ -13,10 +13,6 @@
padding: $padding-small 0; padding: $padding-small 0;
} }
&-tabs.vm-block {
padding: $padding-global;
}
&-tabs { &-tabs {
display: flex; display: flex;
flex-wrap: wrap; flex-wrap: wrap;
@ -24,19 +20,27 @@
justify-content: flex-start; justify-content: flex-start;
font-size: $font-size-small; font-size: $font-size-small;
gap: $padding-small; gap: $padding-small;
white-space: nowrap;
overflow: hidden; overflow: hidden;
@media (max-width: 768px) {
padding: 0 $padding-global;
}
&__tab { &__tab {
padding: $padding-small $padding-global; padding: $padding-small $padding-global;
border-radius: $border-radius-medium; border-radius: $border-radius-medium;
cursor: pointer; cursor: pointer;
transition: background 200ms ease-in-out, color 150ms ease-in; transition: background 200ms ease-in-out, color 150ms ease-in;
background: $color-white; background: $color-background-block;
text-transform: uppercase; text-transform: uppercase;
color: rgba($color-black, 0.2); color: $color-text-secondary;
text-align: center;
border: 1px solid rgba($color-black, 0.2); border: 1px solid rgba($color-black, 0.2);
@media (max-width: 500px) {
flex-grow: 1;
}
&:hover { &:hover {
color: $color-primary; color: $color-primary;
} }