mirror of
https://github.com/VictoriaMetrics/VictoriaMetrics.git
synced 2024-11-21 14:44:00 +00:00
Automatic update Grafana datasource docs from VictoriaMetrics/grafana-datasource@ef5cfe6 (#5700)
This commit is contained in:
Github Actions
Aliaksandr Valialkin
parent
c067f3f288
commit
41c48a4c59
2 changed files with 77 additions and 78 deletions
|
|
@ -11,6 +11,7 @@ aliases:
|
|||
---
|
||||
|
||||
# VictoriaMetrics datasource for Grafana
|
||||
|
||||
The [VictoriaMetrics](http://docs.victoriametrics.com/) datasource plugin allows you to query and visualize
|
||||
data from VictoriaMetrics in Grafana.
|
||||
|
||||
|
|
@ -25,8 +26,8 @@ data from VictoriaMetrics in Grafana.
|
|||
|
||||
Thanks to VictoriaMetrics compatibility with Prometheus API users can use
|
||||
[Prometheus datasource](https://docs.victoriametrics.com/#grafana-setup) for Grafana to query data from VictoriaMetrics.
|
||||
But with time, Prometheus and VictoriaMetrics diverge more and more. After some unexpected changes to Prometheus datasource
|
||||
we decided to create a datasource plugin specifically for VictoriaMetrics.
|
||||
But with time, Prometheus and VictoriaMetrics diverge more and more. After some unexpected changes to Prometheus
|
||||
datasource we decided to create a datasource plugin specifically for VictoriaMetrics.
|
||||
The benefits of using VictoriaMetrics plugin are the following:
|
||||
|
||||
* [MetricsQL](https://docs.victoriametrics.com/MetricsQL.html) functions support;
|
||||
|
|
@ -37,8 +38,8 @@ The benefits of using VictoriaMetrics plugin are the following:
|
|||
|
||||
## Installation
|
||||
|
||||
Installing VictoriaMetrics Grafana datasource [requires](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#allow_loading_unsigned_plugins)
|
||||
the following changes to Grafana's `grafana.ini` config:
|
||||
Installing VictoriaMetrics Grafana datasource [requires](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#allow_loading_unsigned_plugins) the following changes to Grafana's `grafana.ini` config:
|
||||
|
||||
``` ini
|
||||
[plugins]
|
||||
allow_loading_unsigned_plugins = victoriametrics-datasource
|
||||
|
|
@ -54,23 +55,17 @@ For `grafana-operator` users, please adjust `config:` section in your `kind=Graf
|
|||
|
||||
See [why VictoriaMetrics datasource is unsigned](#why-victoriaMetrics-datasource-is-unsigned).
|
||||
|
||||
For detailed instructions on how to install the plugin on Grafana Cloud or
|
||||
locally, please checkout the [Plugin installation docs](https://grafana.com/docs/grafana/latest/plugins/installation/).
|
||||
For detailed instructions on how to install the plugin on Grafana Cloud or locally, please checkout the [Plugin installation docs](https://grafana.com/docs/grafana/latest/plugins/installation/).
|
||||
|
||||
### Install via Docker
|
||||
|
||||
[VictoriaMetrics repo](https://github.com/victoriaMetrics/victoriaMetrics) provides a complete
|
||||
[docker-compose](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/deployment/docker#docker-compose-environment-for-victoriametrics)
|
||||
environment to spin-up all required components via Docker.
|
||||
[VictoriaMetrics repo](https://github.com/victoriaMetrics/victoriaMetrics) provides a complete [docker-compose](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/deployment/docker#docker-compose-environment-for-victoriametrics) environment to spin-up all required components via Docker.
|
||||
|
||||
To begin, clone [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) repository and follow
|
||||
steps described in the [README](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/deployment/docker#docker-compose-environment-for-victoriametrics).
|
||||
|
||||
To begin, clone [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) repository and follow steps described in the [README](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/deployment/docker#docker-compose-environment-for-victoriametrics).
|
||||
|
||||
### Grafana Provisioning
|
||||
|
||||
Provision of Grafana plugin requires to create
|
||||
[datasource config file](http://docs.grafana.org/administration/provisioning/#datasources).
|
||||
Provision of Grafana plugin requires to create [datasource config file](http://docs.grafana.org/administration/provisioning/#datasources).
|
||||
|
||||
Example of config file for provisioning VictoriaMetrics datasource is the following:
|
||||
|
||||
|
|
@ -80,37 +75,37 @@ apiVersion: 1
|
|||
# List of data sources to insert/update depending on what's
|
||||
# available in the database.
|
||||
datasources:
|
||||
# <string, required> Name of the VictoriaMetrics datasource
|
||||
# displayed in Grafana panels and queries.
|
||||
- name: VictoriaMetrics
|
||||
# <string, required> Sets the data source type.
|
||||
type: victoriametrics-datasource
|
||||
# <string, required> Name of the VictoriaMetrics datasource
|
||||
# displayed in Grafana panels and queries.
|
||||
- name: VictoriaMetrics
|
||||
# <string, required> Sets the data source type.
|
||||
type: victoriametrics-datasource
|
||||
# <string, required> Sets the access mode, either
|
||||
# proxy or direct (Server or Browser in the UI).
|
||||
# Some data sources are incompatible with any setting
|
||||
# but proxy (Server).
|
||||
access: proxy
|
||||
# <string> Sets default URL of the single node version of VictoriaMetrics
|
||||
url: http://victoriametrics:8428
|
||||
# <string> Sets the pre-selected datasource for new panels.
|
||||
# You can set only one default data source per organization.
|
||||
isDefault: true
|
||||
# but proxy (Server).
|
||||
access: proxy
|
||||
# <string> Sets default URL of the single node version of VictoriaMetrics
|
||||
url: http://victoriametrics:8428
|
||||
# <string> Sets the pre-selected datasource for new panels.
|
||||
# You can set only one default data source per organization.
|
||||
isDefault: true
|
||||
|
||||
# <string, required> Name of the VictoriaMetrics datasource
|
||||
# displayed in Grafana panels and queries.
|
||||
- name: VictoriaMetrics - cluster
|
||||
# <string, required> Sets the data source type.
|
||||
type: victoriametrics-datasource
|
||||
# <string, required> Sets the access mode, either
|
||||
# proxy or direct (Server or Browser in the UI).
|
||||
# Some data sources are incompatible with any setting
|
||||
# but proxy (Server).
|
||||
access: proxy
|
||||
# <string> Sets default URL of the cluster version of VictoriaMetrics
|
||||
url: http://vmselect:8481/select/0/prometheus
|
||||
# <string> Sets the pre-selected datasource for new panels.
|
||||
# You can set only one default data source per organization.
|
||||
isDefault: false
|
||||
# <string, required> Name of the VictoriaMetrics datasource
|
||||
# displayed in Grafana panels and queries.
|
||||
- name: VictoriaMetrics - cluster
|
||||
# <string, required> Sets the data source type.
|
||||
type: victoriametrics-datasource
|
||||
# <string, required> Sets the access mode, either
|
||||
# proxy or direct (Server or Browser in the UI).
|
||||
# Some data sources are incompatible with any setting
|
||||
# but proxy (Server).
|
||||
access: proxy
|
||||
# <string> Sets default URL of the cluster version of VictoriaMetrics
|
||||
url: http://vmselect:8481/select/0/prometheus
|
||||
# <string> Sets the pre-selected datasource for new panels.
|
||||
# You can set only one default data source per organization.
|
||||
isDefault: false
|
||||
```
|
||||
|
||||
Please find the example of provisioning Grafana instance with VictoriaMetrics datasource below:
|
||||
|
|
@ -118,7 +113,7 @@ Please find the example of provisioning Grafana instance with VictoriaMetrics da
|
|||
1. Create folder `./provisioning/datasource` with datasource example file:
|
||||
|
||||
1. Download the latest release:
|
||||
|
||||
|
||||
``` bash
|
||||
ver=$(curl -s https://api.github.com/repos/VictoriaMetrics/grafana-datasource/releases/latest | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1)
|
||||
curl -L https://github.com/VictoriaMetrics/grafana-datasource/releases/download/$ver/victoriametrics-datasource-$ver.tar.gz -o plugin.tar.gz
|
||||
|
|
@ -127,7 +122,7 @@ Please find the example of provisioning Grafana instance with VictoriaMetrics da
|
|||
```
|
||||
|
||||
1. Define Grafana installation via docker-compose:
|
||||
|
||||
|
||||
```yaml
|
||||
version: '3.0'
|
||||
services:
|
||||
|
|
@ -152,9 +147,7 @@ docker-compose -f docker-compose.yaml up
|
|||
|
||||
When Grafana starts successfully datasources should be present on the datasources tab
|
||||
|
||||
<p>
|
||||
<img src="provision_datasources.png" width="800" alt="Configuration">
|
||||
</p>
|
||||
<img src="provision_datasources.webp" width="800" alt="Configuration">
|
||||
|
||||
### Install in Kubernetes
|
||||
|
||||
|
|
@ -187,17 +180,17 @@ extraInitContainers:
|
|||
mountPath: /var/lib/grafana
|
||||
```
|
||||
|
||||
For `grafana-operator` users, the above configuration should be done for the part
|
||||
`/spec/deployment/spec/template/spec/initContainers` of your `kind=Grafana` resource.
|
||||
For `grafana-operator` users, the above configuration should be done for the part `/spec/deployment/spec/template/spec/initContainers` of your `kind=Grafana` resource.
|
||||
|
||||
This example uses init container to download and install plugin. To allow Grafana using this container as a sidecar set the following config:
|
||||
|
||||
This example uses init container to download and install plugin. To allow Grafana using this container as a sidecar
|
||||
set the following config:
|
||||
```yaml
|
||||
sidecar:
|
||||
datasources:
|
||||
initDatasources: true
|
||||
enabled: true
|
||||
```
|
||||
|
||||
See more about chart settings [here](https://github.com/grafana/helm-charts/blob/541d97051de87a309362e02d08741ffc868cfcd6/charts/grafana/values.yaml)
|
||||
|
||||
Another option would be to build custom Grafana image with plugin based on same installation instructions.
|
||||
|
|
@ -249,15 +242,13 @@ spec:
|
|||
allow_loading_unsigned_plugins: victoriametrics-datasource
|
||||
```
|
||||
|
||||
See [Grafana operator reference](https://grafana-operator.github.io/grafana-operator/docs/grafana/) to find more about
|
||||
Grafana operator.
|
||||
See [Grafana operator reference](https://grafana-operator.github.io/grafana-operator/docs/grafana/) to find more about Grafana operator.
|
||||
This example uses init container to download and install plugin.
|
||||
|
||||
### Dev release installation
|
||||
|
||||
|
||||
1. To download plugin build and move contents into Grafana plugins directory:
|
||||
|
||||
|
||||
``` bash
|
||||
ver=$(curl -s https://api.github.com/repos/VictoriaMetrics/grafana-datasource/releases/latest | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1)
|
||||
curl -L https://github.com/VictoriaMetrics/grafana-datasource/releases/download/$ver/victoriametrics-datasource-$ver.tar.gz -o /var/lib/grafana/plugins/plugin.tar.gz
|
||||
|
|
@ -267,21 +258,26 @@ This example uses init container to download and install plugin.
|
|||
|
||||
1. Restart Grafana
|
||||
|
||||
|
||||
## Getting started development
|
||||
|
||||
### 1. Configure Grafana
|
||||
|
||||
Installing dev version of Grafana plugin requires to change `grafana.ini` config to allow loading unsigned plugins:
|
||||
|
||||
``` ini
|
||||
# Directory where Grafana will automatically scan and look for plugins
|
||||
plugins = {{path to directory with plugin}}
|
||||
```
|
||||
|
||||
``` ini
|
||||
[plugins]
|
||||
allow_loading_unsigned_plugins = victoriametrics-datasource
|
||||
```
|
||||
|
||||
### 2. Run the plugin
|
||||
|
||||
In the project directory, you can run:
|
||||
|
||||
```
|
||||
# install dependencies
|
||||
yarn install
|
||||
|
|
@ -296,10 +292,13 @@ yarn build:zip
|
|||
### 3. How to build backend plugin
|
||||
|
||||
From the root folder of the project run the following command:
|
||||
|
||||
```
|
||||
make victoriametrics-backend-plugin-build
|
||||
```
|
||||
|
||||
This command will build executable multi-platform files to the `dist` folder for the following platforms:
|
||||
|
||||
* linux/amd64
|
||||
* linux/arm64
|
||||
* linux/arm
|
||||
|
|
@ -309,25 +308,28 @@ This command will build executable multi-platform files to the `dist` folder for
|
|||
* windows
|
||||
|
||||
### 4.How to build frontend plugin
|
||||
|
||||
From the root folder of the project run the following command:
|
||||
|
||||
```
|
||||
make victorimetrics-frontend-plugin-build
|
||||
```
|
||||
|
||||
This command will build all frontend app into `dist` folder.
|
||||
|
||||
### 5. How to build frontend and backend parts of the plugin:
|
||||
When frontend and backend parts of the plugin is required, run the following command from
|
||||
the root folder of the project:
|
||||
|
||||
When frontend and backend parts of the plugin is required, run the following command from the root folder of the project:
|
||||
|
||||
```
|
||||
make victoriametrics-datasource-plugin-build
|
||||
```
|
||||
This command will build frontend part and backend part or the plugin and locate both
|
||||
parts into `dist` folder.
|
||||
|
||||
This command will build frontend part and backend part or the plugin and locate both parts into `dist` folder.
|
||||
|
||||
## How to use WITH templates
|
||||
|
||||
The `WITH` templates feature simplifies the construction and management of complex queries.
|
||||
You can try this feature in the [WITH templates playground](https://play.victoriametrics.com/select/accounting/1/6a716b0f-38bc-4856-90ce-448fd713e3fe/expand-with-exprs).
|
||||
The `WITH` templates feature simplifies the construction and management of complex queries. You can try this feature in the [WITH templates playground](https://play.victoriametrics.com/select/accounting/1/6a716b0f-38bc-4856-90ce-448fd713e3fe/expand-with-exprs).
|
||||
|
||||
The "WITH templates" section allows you to create expressions with templates that can be used in dashboards.
|
||||
|
||||
|
|
@ -349,17 +351,19 @@ WITH expressions are stored in the datasource object. If the dashboard gets expo
|
|||
cpuIdle = sum(rate(node_cpu_seconds_total{mode='idle',commonFilters}[5m]))
|
||||
```
|
||||
|
||||
You can specify a comment before the variable and use markdown in it. The comment will be displayed as a hint during auto-completion. The comment can span multiple lines.
|
||||
You can specify a comment before the variable and use markdown in it. The comment will be displayed as a hint during
|
||||
auto-completion. The comment can span multiple lines.
|
||||
|
||||
### Using WITH Expressions
|
||||
|
||||
After saving the template, you can enter it into the query editor field:
|
||||
|
||||
```
|
||||
((cpuCount - cpuIdle) * 100) / cpuCount
|
||||
```
|
||||
|
||||
Thus, the entire query will look as follows:
|
||||
|
||||
|
||||
```
|
||||
WITH (
|
||||
commonFilters = {instance=~"$node:$port",job=~"$job"},
|
||||
|
|
@ -368,45 +372,40 @@ WITH (
|
|||
)
|
||||
((cpuCount - cpuIdle) * 100) / cpuCount
|
||||
```
|
||||
|
||||
To view the raw query in the interface, enable the `Raw` toggle.
|
||||
|
||||
## How to make new release
|
||||
|
||||
1. Make sure there are no open security issues.
|
||||
1. Create a release tag:
|
||||
* `git tag -s v1.xx.y` in `master` branch
|
||||
* `git tag -s v1.xx.y` in `master` branch
|
||||
1. Run `TAG=v1.xx.y make build-release` to build and package binaries in `*.tar.gz` release archives.
|
||||
1. Run `git push origin v1.xx.y` to push the tag created `v1.xx.y` at step 2 to public GitHub repository
|
||||
1. Go to <https://github.com/VictoriaMetrics/grafana-datasource/releases> and verify that draft release with the name `TAG` has been created
|
||||
and this release contains all the needed binaries and checksums.
|
||||
1. Go to <https://github.com/VictoriaMetrics/grafana-datasource/releases> and verify that draft release with the name `TAG` has been created and this release contains all the needed binaries and checksums.
|
||||
1. Remove the `draft` checkbox for the `TAG` release and manually publish it.
|
||||
|
||||
|
||||
## FAQ
|
||||
|
||||
### Why VictoriaMetrics datasource is unsigned?
|
||||
|
||||
Based on our previous experience of [developing Grafana plugins](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/)
|
||||
the signing procedure was a formal act. But when we tried [to sign the plugin](https://grafana.com/docs/grafana/latest/developers/plugins/publish-a-plugin/sign-a-plugin/)
|
||||
we were told by GrafanaLabs representative the plugin falls into a Commercial signature level. It matters not
|
||||
if plugin or VictoriaMetrics itself are opensource. The announced cost of Commercial signature level was much higher
|
||||
than expected, so we interrupted the procedure.
|
||||
Based on our previous experience of [developing Grafana plugins](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/) the signing procedure was a formal act. But when we tried [to sign the plugin](https://grafana.com/docs/grafana/latest/developers/plugins/publish-a-plugin/sign-a-plugin/)
|
||||
we were told by GrafanaLabs representative the plugin falls into a Commercial signature level.
|
||||
It matters not if plugin or VictoriaMetrics itself are opensource. The announced cost of Commercial signature level was much higher than expected, so we interrupted the procedure.
|
||||
|
||||
### How to convert dashboard from Prometheus to VictoriaMetrics datasource?
|
||||
|
||||
Make sure that VictoriaMetrics datasource plugin is [installed](#installation), and a new datasource is created from the plugin.
|
||||
|
||||
Each panel in Grafana dashboard has a datasource dropdown when in Edit mode. Just choose the VictoriaMetrics datasource
|
||||
instead of Prometheus datasource in dropdown.
|
||||
Each panel in Grafana dashboard has a datasource dropdown when in Edit mode. Just choose the VictoriaMetrics datasource instead of Prometheus datasource in dropdown.
|
||||
|
||||
If datasource is configured via Grafana variable, then change variable to VictoriaMetrics datasource type.
|
||||
|
||||
### Why VictoriaMetrics datasource doesn't support alerting?
|
||||
|
||||
Grafana doesn't allow forwarding Alert requests to alerting API /api/v1/rules for plugins which are not of Prometheus
|
||||
or Loki type. See more details [here](https://github.com/VictoriaMetrics/grafana-datasource/issues/59#issuecomment-1541456768).
|
||||
|
||||
Grafana doesn't allow forwarding Alert requests to alerting API /api/v1/rules for plugins which are not of Prometheus or Loki type. See more details [here](https://github.com/VictoriaMetrics/grafana-datasource/issues/59#issuecomment-1541456768).
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [AGPL-3.0-only](https://github.com/VictoriaMetrics/grafana-datasource/blob/main/LICENSE).
|
||||
This project is licensed under
|
||||
the [AGPL-3.0-only](https://github.com/VictoriaMetrics/grafana-datasource/blob/main/LICENSE).
|
||||
|
|
|
|||
BIN
docs/provision_datasources.webp
Normal file
BIN
docs/provision_datasources.webp
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Loading…
Reference in a new issue