github-mirrors/VictoriaMetrics
1
0
Fork 0
mirror of https://github.com/VictoriaMetrics/VictoriaMetrics.git synced 2024-11-21 14:44:00 +00:00
Code Issues Projects Releases Packages Wiki Activity

Automatic update Grafana datasource docs from VictoriaMetrics/grafana-datasource@ef5cfe6 (#5700)

Browse source
This commit is contained in:
Github Actions 2024-01-27 04:22:17 +08:00 committed by GitHub
parent 2655c02d5e
commit 5a8daa725e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 77 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

155
docs/grafana-datasource.md
View file

@ -11,6 +11,7 @@ aliases:
--- ---
# VictoriaMetrics datasource for Grafana # VictoriaMetrics datasource for Grafana
The [VictoriaMetrics](http://docs.victoriametrics.com/) datasource plugin allows you to query and visualize The [VictoriaMetrics](http://docs.victoriametrics.com/) datasource plugin allows you to query and visualize
data from VictoriaMetrics in Grafana. data from VictoriaMetrics in Grafana.
@ -25,8 +26,8 @@ data from VictoriaMetrics in Grafana.
Thanks to VictoriaMetrics compatibility with Prometheus API users can use 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. [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 But with time, Prometheus and VictoriaMetrics diverge more and more. After some unexpected changes to Prometheus
we decided to create a datasource plugin specifically for VictoriaMetrics. datasource we decided to create a datasource plugin specifically for VictoriaMetrics.
The benefits of using VictoriaMetrics plugin are the following: The benefits of using VictoriaMetrics plugin are the following:
* [MetricsQL](https://docs.victoriametrics.com/MetricsQL.html) functions support; * [MetricsQL](https://docs.victoriametrics.com/MetricsQL.html) functions support;
@ -37,8 +38,8 @@ The benefits of using VictoriaMetrics plugin are the following:
## Installation ## Installation
Installing VictoriaMetrics Grafana datasource [requires](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#allow_loading_unsigned_plugins) 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:
the following changes to Grafana's `grafana.ini` config:
``` ini ``` ini
[plugins] [plugins]
allow_loading_unsigned_plugins = victoriametrics-datasource 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). See [why VictoriaMetrics datasource is unsigned](#why-victoriaMetrics-datasource-is-unsigned).
For detailed instructions on how to install the plugin on Grafana Cloud or 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/).
locally, please checkout the [Plugin installation docs](https://grafana.com/docs/grafana/latest/plugins/installation/).
### Install via Docker ### Install via Docker
[VictoriaMetrics repo](https://github.com/victoriaMetrics/victoriaMetrics) provides a complete [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.
[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 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).
steps described in the [README](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/deployment/docker#docker-compose-environment-for-victoriametrics).
### Grafana Provisioning ### Grafana Provisioning
Provision of Grafana plugin requires to create Provision of Grafana plugin requires to create [datasource config file](http://docs.grafana.org/administration/provisioning/#datasources).
[datasource config file](http://docs.grafana.org/administration/provisioning/#datasources).
Example of config file for provisioning VictoriaMetrics datasource is the following: 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 # List of data sources to insert/update depending on what's
# available in the database. # available in the database.
datasources: datasources:
# <string, required> Name of the VictoriaMetrics datasource # <string, required> Name of the VictoriaMetrics datasource
# displayed in Grafana panels and queries. # displayed in Grafana panels and queries.
- name: VictoriaMetrics - name: VictoriaMetrics
# <string, required> Sets the data source type. # <string, required> Sets the data source type.
type: victoriametrics-datasource type: victoriametrics-datasource
# <string, required> Sets the access mode, either # <string, required> Sets the access mode, either
# proxy or direct (Server or Browser in the UI). # proxy or direct (Server or Browser in the UI).
# Some data sources are incompatible with any setting # Some data sources are incompatible with any setting
# but proxy (Server). # but proxy (Server).
access: proxy access: proxy
# <string> Sets default URL of the single node version of VictoriaMetrics # <string> Sets default URL of the single node version of VictoriaMetrics
url: http://victoriametrics:8428 url: http://victoriametrics:8428
# <string> Sets the pre-selected datasource for new panels. # <string> Sets the pre-selected datasource for new panels.
# You can set only one default data source per organization. # You can set only one default data source per organization.
isDefault: true isDefault: true
# <string, required> Name of the VictoriaMetrics datasource # <string, required> Name of the VictoriaMetrics datasource
# displayed in Grafana panels and queries. # displayed in Grafana panels and queries.
- name: VictoriaMetrics - cluster - name: VictoriaMetrics - cluster
# <string, required> Sets the data source type. # <string, required> Sets the data source type.
type: victoriametrics-datasource type: victoriametrics-datasource
# <string, required> Sets the access mode, either # <string, required> Sets the access mode, either
# proxy or direct (Server or Browser in the UI). # proxy or direct (Server or Browser in the UI).
# Some data sources are incompatible with any setting # Some data sources are incompatible with any setting
# but proxy (Server). # but proxy (Server).
access: proxy access: proxy
# <string> Sets default URL of the cluster version of VictoriaMetrics # <string> Sets default URL of the cluster version of VictoriaMetrics
url: http://vmselect:8481/select/0/prometheus url: http://vmselect:8481/select/0/prometheus
# <string> Sets the pre-selected datasource for new panels. # <string> Sets the pre-selected datasource for new panels.
# You can set only one default data source per organization. # You can set only one default data source per organization.
isDefault: false isDefault: false
``` ```
Please find the example of provisioning Grafana instance with VictoriaMetrics datasource below: 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. Create folder `./provisioning/datasource` with datasource example file:
1. Download the latest release: 1. Download the latest release:
``` bash ``` 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) 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 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: 1. Define Grafana installation via docker-compose:
```yaml ```yaml
version: '3.0' version: '3.0'
services: services:
@ -152,9 +147,7 @@ docker-compose -f docker-compose.yaml up
When Grafana starts successfully datasources should be present on the datasources tab When Grafana starts successfully datasources should be present on the datasources tab
<p> <img src="provision_datasources.webp" width="800" alt="Configuration">
<img src="provision_datasources.png" width="800" alt="Configuration">
</p>
### Install in Kubernetes ### Install in Kubernetes
@ -187,17 +180,17 @@ extraInitContainers:
mountPath: /var/lib/grafana mountPath: /var/lib/grafana
``` ```
For `grafana-operator` users, the above configuration should be done for the part For `grafana-operator` users, the above configuration should be done for the part `/spec/deployment/spec/template/spec/initContainers` of your `kind=Grafana` resource.
`/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 ```yaml
sidecar: sidecar:
datasources: datasources:
initDatasources: true initDatasources: true
enabled: true enabled: true
``` ```
See more about chart settings [here](https://github.com/grafana/helm-charts/blob/541d97051de87a309362e02d08741ffc868cfcd6/charts/grafana/values.yaml) 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. 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 allow_loading_unsigned_plugins: victoriametrics-datasource
``` ```
See [Grafana operator reference](https://grafana-operator.github.io/grafana-operator/docs/grafana/) to find more about See [Grafana operator reference](https://grafana-operator.github.io/grafana-operator/docs/grafana/) to find more about Grafana operator.
Grafana operator.
This example uses init container to download and install plugin. This example uses init container to download and install plugin.
### Dev release installation ### Dev release installation
1. To download plugin build and move contents into Grafana plugins directory: 1. To download plugin build and move contents into Grafana plugins directory:
``` bash ``` 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) 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 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 1. Restart Grafana
## Getting started development ## Getting started development
### 1. Configure Grafana ### 1. Configure Grafana
Installing dev version of Grafana plugin requires to change `grafana.ini` config to allow loading unsigned plugins: Installing dev version of Grafana plugin requires to change `grafana.ini` config to allow loading unsigned plugins:
``` ini ``` ini
# Directory where Grafana will automatically scan and look for plugins # Directory where Grafana will automatically scan and look for plugins
plugins = {{path to directory with plugin}} plugins = {{path to directory with plugin}}
``` ```
``` ini ``` ini
[plugins] [plugins]
allow_loading_unsigned_plugins = victoriametrics-datasource allow_loading_unsigned_plugins = victoriametrics-datasource
``` ```
### 2. Run the plugin ### 2. Run the plugin
In the project directory, you can run: In the project directory, you can run:
``` ```
# install dependencies # install dependencies
yarn install yarn install
@ -296,10 +292,13 @@ yarn build:zip
### 3. How to build backend plugin ### 3. How to build backend plugin
From the root folder of the project run the following command: From the root folder of the project run the following command:
``` ```
make victoriametrics-backend-plugin-build make victoriametrics-backend-plugin-build
``` ```
This command will build executable multi-platform files to the `dist` folder for the following platforms: This command will build executable multi-platform files to the `dist` folder for the following platforms:
* linux/amd64 * linux/amd64
* linux/arm64 * linux/arm64
* linux/arm * linux/arm
@ -309,25 +308,28 @@ This command will build executable multi-platform files to the `dist` folder for
* windows * windows
### 4.How to build frontend plugin ### 4.How to build frontend plugin
From the root folder of the project run the following command: From the root folder of the project run the following command:
``` ```
make victorimetrics-frontend-plugin-build make victorimetrics-frontend-plugin-build
``` ```
This command will build all frontend app into `dist` folder. This command will build all frontend app into `dist` folder.
### 5. How to build frontend and backend parts of the plugin: ### 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 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 ## How to use WITH templates
The `WITH` templates feature simplifies the construction and management of complex queries. 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).
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. 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])) 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 ### Using WITH Expressions
After saving the template, you can enter it into the query editor field: After saving the template, you can enter it into the query editor field:
``` ```
((cpuCount - cpuIdle) * 100) / cpuCount ((cpuCount - cpuIdle) * 100) / cpuCount
``` ```
Thus, the entire query will look as follows: Thus, the entire query will look as follows:
``` ```
WITH ( WITH (
commonFilters = {instance=~"$node:$port",job=~"$job"}, commonFilters = {instance=~"$node:$port",job=~"$job"},
@ -368,45 +372,40 @@ WITH (
) )
((cpuCount - cpuIdle) * 100) / cpuCount ((cpuCount - cpuIdle) * 100) / cpuCount
``` ```
To view the raw query in the interface, enable the `Raw` toggle. To view the raw query in the interface, enable the `Raw` toggle.
## How to make new release ## How to make new release
1. Make sure there are no open security issues. 1. Make sure there are no open security issues.
1. Create a release tag: 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 `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. 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 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.
and this release contains all the needed binaries and checksums.
1. Remove the `draft` checkbox for the `TAG` release and manually publish it. 1. Remove the `draft` checkbox for the `TAG` release and manually publish it.
## FAQ ## FAQ
### Why VictoriaMetrics datasource is unsigned? ### Why VictoriaMetrics datasource is unsigned?
Based on our previous experience of [developing Grafana plugins](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/) 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/)
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.
we were told by GrafanaLabs representative the plugin falls into a Commercial signature level. It matters not 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.
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? ### 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. 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 Each panel in Grafana dashboard has a datasource dropdown when in Edit mode. Just choose the VictoriaMetrics datasource instead of Prometheus datasource in dropdown.
instead of Prometheus datasource in dropdown.
If datasource is configured via Grafana variable, then change variable to VictoriaMetrics datasource type. If datasource is configured via Grafana variable, then change variable to VictoriaMetrics datasource type.
### Why VictoriaMetrics datasource doesn't support alerting? ### 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 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).
or Loki type. See more details [here](https://github.com/VictoriaMetrics/grafana-datasource/issues/59#issuecomment-1541456768).
## License ## 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
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 40 KiB