diff --git a/docs/sources/configuration/direct_db_datasource.md b/docs/sources/configuration/direct_db_datasource.md index e78ff77..78d6246 100644 --- a/docs/sources/configuration/direct_db_datasource.md +++ b/docs/sources/configuration/direct_db_datasource.md @@ -1,4 +1,13 @@ -# SQL Data Source Configuration +# Direct DB Data Source Configuration + +## Security notes + +Grafana-Zabbix plugin can use MySQL, Postgres or InfluxDB (if Zabbix configured to store history data in InfluxDB) data sources to query history and trend data directly from Zabbix database. In order to execute queries, plugin needs only read access to the `history`, `history_uint`, `trends` and `trends_uint` tables. To make connection more secure and prevent unnecessary data disclosure, it's highly recommended to grant read access to only that tables. But if you want to use this data source for querying another data, you can +grant `SELECT` privileges to entire zabbix database. Also, all queries are invoked by grafana server, so you can restrict connection to only grafana host. Here's MySQL example: + +```sql +GRANT SELECT ON zabbix.* TO 'grafana'@'grafana-host' identified by 'password'; +``` ## MySQL @@ -9,29 +18,12 @@ In order to use _Direct DB Connection_ feature you should configure SQL data sou Select _MySQL_ data source type and provide your database host address and port (3306 is default for MySQL). Fill database name (usually, `zabbix`) and specify credentials. -### Security notes - -As you can see in _User Permission_ note, Grafana doesn't restrict any queries to the database. So you should be careful -and create a special user with limited access to Zabbix database. Grafana-Zabbix plugin uses only `SELECT` queries to -`history`, `history_uint`, `trends` and `trends_uint` tables. So it's reasonable to grant only SELECT privileges to -these tables for grafana user. But if you want to use this MySQL data source for querying another data, you can -grant SELECT privileges to entire zabbix database. - -Also, all queries are invoked by grafana-server, so you can restrict connection to only grafana host. - -```sql -GRANT SELECT ON zabbix.* TO 'grafana'@'grafana-host' identified by 'password'; -``` - ## PostgreSQL Select _PostgreSQL_ data source type and provide your database host address and port (5432 is default). Fill database name (usually, `zabbix`) and specify credentials. ![Configure PostgreSQL data source](../img/installation-postgres_ds_config.png) -### Security notes - -Make sure you use read-only user for Zabbix database. ## InfluxDB diff --git a/docs/sources/configuration/index.md b/docs/sources/configuration/index.md index 7bbdc7e..3680dad 100644 --- a/docs/sources/configuration/index.md +++ b/docs/sources/configuration/index.md @@ -4,53 +4,48 @@ page_description: Plugin configuration instructions for Grafana-Zabbix. # Configuration ## Enable plugin + Go to the plugins in Grafana side panel, select _Apps_ tab, then select _Zabbix_, open _Config_ tab and enable plugin. ![Enable Zabbix App](../img/installation-enable_app.png) ## Configure Zabbix data source + After enabling plugin you can add Zabbix data source. -To add new Zabbix data source open _Data Sources_ in side panel, click _Add data source_ and -select _Zabbix_ from dropdown list. +To add new Zabbix data source open _Data Sources_ in side panel, click _Add data source_ and select _Zabbix_ from dropdown list. ![Configure Zabbix data source](../img/installation-datasource_config.png) ### HTTP settings -- **Url**: set Zabbix API url (full path with `api_jsonrpc.php`). -- **Access**: - - **Proxy**: access via Grafana backend - - **Direct**: access from browser. +- **URL**: set Zabbix API url (full path with `api_jsonrpc.php`). +- **Access**: Set to `Server (default)`. - **Http Auth**: configure if you use proxy authentication. - - **Basic Auth**: - - **With Credentials**: - -Proxy access means that the Grafana backend will proxy all requests from the browser, and send them on to the Data Source. This is useful because it can eliminate CORS (Cross Origin Site Resource) issues, as well as eliminate the need to disseminate authentication details to the Data Source to the browser. - -Direct access is still supported because in some cases it may be useful to access a Data Source directly depending on the use case and topology of Grafana, the user, and the Data Source. + - **Basic Auth**: + - **With Credentials**: ### Zabbix API details -- **User** and **Password**: setup login for access to Zabbix API. Also check user's permissions - in Zabbix if you can't get any groups and hosts in Grafana. -- **Trends**: enable if you use Zabbix 3.x or patch for trends - support in Zabbix 2.x ([ZBXNEXT-1193](https://support.zabbix.com/browse/ZBXNEXT-1193)). This option +- **Username** and **Password**: setup login for access to Zabbix API. Also check user's permissions + in Zabbix if you cannot get any groups and hosts in Grafana. +- **Trends**: enable if you use Zabbix 3.x or newer. This option is strictly recommended for displaying long time periods (more than few days, depending of your item's - updating interval in Zabbix) because few days of item history contains tons of points. Using trends + updating interval in Zabbix), because few days of item history contains tons of points. Using trends will increase Grafana performance. - - **After**: time after which trends will be used. + - **After**: time after which trends will be used. Best practice is to set this value to your history storage period (7d, 30d, etc). Default is **7d** (7 days). You can set the time in Grafana format. Valid time specificators are: - - **h** - hours - - **d** - days - - **M** - months - - **Range**: Time range width after which trends will be used instead of history. + - **h** - hours + - **d** - days + - **M** - months + - **Range**: Time range width after which trends will be used instead of history. It's better to set this value in range of 4 to 7 days to prevent loading large amount of history data. Default is 4 days. - **Cache TTL**: plugin caches some api requests for increasing performance. Set this value to desired cache lifetime (this option affect data like items list). +- **Timeout**: Zabbix connection timeout in seconds. Default is 30. ### Direct DB Connection @@ -70,47 +65,18 @@ Read [how to configure](./direct_db_datasource) SQL data source in Grafana. ### Other +- **Disable acknowledges for read-only users**: disable ability to acknowledge problems from Grafana for non-editors. + - **Disable data alignment**: disable time series data alignment. This feature aligns points based on item update interval. For instance, if value collected once per minute, then timestamp of the each point will be set to the start of corresponding minute. This alignment required for proper work of the stacked graphs. If you don't need stacked graphs and want to get exactly the same timestamps as in Zabbix, then you can disable this feature. Also, data alignment can be toggled for each query individually, in the query options. -Then click _Add_ - datasource will be added and you can check connection using -_Test Connection_ button. This feature can help to find some mistakes like invalid user name -or password, wrong api url. - -![Test Connection](../img/installation-test_connection.png) +Then click _Add_ - data source will be added and you can check connection using _Test Connection_ button. This feature can help to find some mistakes like invalid user name or password, wrong api url. ## Import example dashboards -You can import dashboard examples from _Dashboards_ tab in plugin config. +You can import dashboard examples from _Dashboards_ tab in the data source config. + ![Import dashboards](../img/installation-plugin-dashboards.png) -## Note about Zabbix 2.2 or less - -Zabbix API (api_jsonrpc.php) before zabbix 2.4 don't allow cross-domain requests (CORS). And you -can get HTTP error 412 (Precondition Failed). -To fix it add this code to api_jsonrpc.php immediately after the copyright: - -```php -header('Access-Control-Allow-Origin: *'); -header('Access-Control-Allow-Headers: Content-Type'); -header('Access-Control-Allow-Methods: POST'); -header('Access-Control-Max-Age: 1000'); - -if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { - return; -} -``` - -before - -```php -require_once dirname(__FILE__).'/include/func.inc.php'; -require_once dirname(__FILE__).'/include/classes/core/CHttpRequest.php'; -``` - -[Full fix listing](https://gist.github.com/alexanderzobnin/f2348f318d7a93466a0c). -For more details see zabbix issues [ZBXNEXT-1377](https://support.zabbix.com/browse/ZBXNEXT-1377) -and [ZBX-8459](https://support.zabbix.com/browse/ZBX-8459). - ## Note about Browser Cache After updating plugin, clear browser cache and reload application page. See details diff --git a/docs/sources/features.md b/docs/sources/features.md index 571311d..d789982 100644 --- a/docs/sources/features.md +++ b/docs/sources/features.md @@ -7,11 +7,11 @@ Grafana in couple with Grafana-Zabbix plugin allows to create great dashboards. features: - Rich graphing features +- Select multiple metrics [by using Regex](../guides/gettingstarted/#multiple-items-on-one-graph) - Create interactive and reusable dashboards with [template variables](../guides/templating/) - Show events on graphs with [Annotations](http://docs.grafana.org/reference/annotations/) -- Select multiple metrics [by using Regex](../guides/gettingstarted/#multiple-items-on-one-graph) -- Display active problems with Triggers panel - Transform and shape your data with [metric processing functions](../reference/functions/) (Avg, Median, Min, Max, Multiply, Summarize, Time shift, Alias) -- Find problems faster with [Alerting](../reference/alerting/) feature -- Mix metrics from multiple data sources in the same dashboard or even graph +- Mix metrics from multiple data sources in the same dashboard or panel +- Create [alerts](../reference/alerting/) in Grafana +- Display triggers with Problems panel - Discover and share [dashboards](https://grafana.com/dashboards) in the official library diff --git a/docs/sources/img/.gitattributes b/docs/sources/img/.gitattributes index 8dce774..e69de29 100644 --- a/docs/sources/img/.gitattributes +++ b/docs/sources/img/.gitattributes @@ -1,4 +0,0 @@ -*.png filter=lfs diff=lfs merge=lfs -text -*.jpg filter=lfs diff=lfs merge=lfs -text -*.psd filter=lfs diff=lfs merge=lfs -text -*.svg filter=lfs diff=lfs merge=lfs -text diff --git a/docs/sources/img/configuration-influxdb_ds_config.png b/docs/sources/img/configuration-influxdb_ds_config.png index b1578c0..591e90e 100644 Binary files a/docs/sources/img/configuration-influxdb_ds_config.png and b/docs/sources/img/configuration-influxdb_ds_config.png differ diff --git a/docs/sources/img/getstarting-dashboard_1.png b/docs/sources/img/getstarting-dashboard_1.png index 245e482..6e44e03 100644 Binary files a/docs/sources/img/getstarting-dashboard_1.png and b/docs/sources/img/getstarting-dashboard_1.png differ diff --git a/docs/sources/img/getstarting-metrics_filtering.png b/docs/sources/img/getstarting-metrics_filtering.png index c6b13c0..4151d7f 100644 Binary files a/docs/sources/img/getstarting-metrics_filtering.png and b/docs/sources/img/getstarting-metrics_filtering.png differ diff --git a/docs/sources/img/getstarting-mysql_operations_1.png b/docs/sources/img/getstarting-mysql_operations_1.png index 7a2ac5a..83d3c78 100644 Binary files a/docs/sources/img/getstarting-mysql_operations_1.png and b/docs/sources/img/getstarting-mysql_operations_1.png differ diff --git a/docs/sources/img/getstarting-mysql_operations_2.png b/docs/sources/img/getstarting-mysql_operations_2.png index 53c840c..10ff41b 100644 Binary files a/docs/sources/img/getstarting-mysql_operations_2.png and b/docs/sources/img/getstarting-mysql_operations_2.png differ diff --git a/docs/sources/img/getstarting-mysql_operations_3.png b/docs/sources/img/getstarting-mysql_operations_3.png index ee0eaf4..e0753d5 100644 Binary files a/docs/sources/img/getstarting-mysql_operations_3.png and b/docs/sources/img/getstarting-mysql_operations_3.png differ diff --git a/docs/sources/img/getstarting-processor_load.png b/docs/sources/img/getstarting-processor_load.png index 7448ac4..5076de7 100644 Binary files a/docs/sources/img/getstarting-processor_load.png and b/docs/sources/img/getstarting-processor_load.png differ diff --git a/docs/sources/img/getstarting-regex_backend_system_time.png b/docs/sources/img/getstarting-regex_backend_system_time.png index 29b1ccc..a9c5e3a 100644 Binary files a/docs/sources/img/getstarting-regex_backend_system_time.png and b/docs/sources/img/getstarting-regex_backend_system_time.png differ diff --git a/docs/sources/img/getstarting-regex_cpu_time.png b/docs/sources/img/getstarting-regex_cpu_time.png index 1191e02..f7af5ac 100644 Binary files a/docs/sources/img/getstarting-regex_cpu_time.png and b/docs/sources/img/getstarting-regex_cpu_time.png differ diff --git a/docs/sources/img/getstarting-singlestat_1.png b/docs/sources/img/getstarting-singlestat_1.png index 63db2f0..5196414 100644 Binary files a/docs/sources/img/getstarting-singlestat_1.png and b/docs/sources/img/getstarting-singlestat_1.png differ diff --git a/docs/sources/img/getstarting-singlestat_2.png b/docs/sources/img/getstarting-singlestat_2.png index 5c37b27..b28bc66 100644 Binary files a/docs/sources/img/getstarting-singlestat_2.png and b/docs/sources/img/getstarting-singlestat_2.png differ diff --git a/docs/sources/img/installation-add_datasource.png b/docs/sources/img/installation-add_datasource.png index 1163c20..9fe9a97 100644 Binary files a/docs/sources/img/installation-add_datasource.png and b/docs/sources/img/installation-add_datasource.png differ diff --git a/docs/sources/img/installation-datasource_config.png b/docs/sources/img/installation-datasource_config.png index ab3648d..70f110e 100644 Binary files a/docs/sources/img/installation-datasource_config.png and b/docs/sources/img/installation-datasource_config.png differ diff --git a/docs/sources/img/installation-enable_app.png b/docs/sources/img/installation-enable_app.png index 0c8db7b..5c0c4cb 100644 Binary files a/docs/sources/img/installation-enable_app.png and b/docs/sources/img/installation-enable_app.png differ diff --git a/docs/sources/img/installation-mysql_ds_config.png b/docs/sources/img/installation-mysql_ds_config.png index 3c8d221..67be336 100644 Binary files a/docs/sources/img/installation-mysql_ds_config.png and b/docs/sources/img/installation-mysql_ds_config.png differ diff --git a/docs/sources/img/installation-plugin-dashboards.png b/docs/sources/img/installation-plugin-dashboards.png index e1cdbd5..925bca3 100644 Binary files a/docs/sources/img/installation-plugin-dashboards.png and b/docs/sources/img/installation-plugin-dashboards.png differ diff --git a/docs/sources/img/installation-plugins-apps.png b/docs/sources/img/installation-plugins-apps.png index ec3ca67..2ee2c48 100644 Binary files a/docs/sources/img/installation-plugins-apps.png and b/docs/sources/img/installation-plugins-apps.png differ diff --git a/docs/sources/img/installation-postgres_ds_config.png b/docs/sources/img/installation-postgres_ds_config.png index 6c2f313..ba72703 100644 Binary files a/docs/sources/img/installation-postgres_ds_config.png and b/docs/sources/img/installation-postgres_ds_config.png differ diff --git a/docs/sources/img/installation-test_connection.png b/docs/sources/img/installation-test_connection.png index 6543428..87f81d6 100644 Binary files a/docs/sources/img/installation-test_connection.png and b/docs/sources/img/installation-test_connection.png differ diff --git a/docs/sources/img/installation-test_connection_error.png b/docs/sources/img/installation-test_connection_error.png index ee85b01..3dd9c31 100644 Binary files a/docs/sources/img/installation-test_connection_error.png and b/docs/sources/img/installation-test_connection_error.png differ diff --git a/docs/sources/img/reference-alerting_panels.png b/docs/sources/img/reference-alerting_panels.png deleted file mode 100644 index 3e206c2..0000000 --- a/docs/sources/img/reference-alerting_panels.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:32e4945bd571cb260a27822d073344539e65e4d31ba0f4908386916f41317560 -size 197334 diff --git a/docs/sources/img/reference-direct-db-connection.svg b/docs/sources/img/reference-direct-db-connection.svg index a48702c..9c5c722 100644 --- a/docs/sources/img/reference-direct-db-connection.svg +++ b/docs/sources/img/reference-direct-db-connection.svg @@ -1,3 +1,1698 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:f0b942ebdeec31f98ae800c78223fb96ec077e8396e2f33a71e29d4d6d096661 -size 200108 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/sources/img/templating-menu.png b/docs/sources/img/templating-menu.png index 4b547e7..e8abbba 100644 Binary files a/docs/sources/img/templating-menu.png and b/docs/sources/img/templating-menu.png differ diff --git a/docs/sources/img/templating-query_with_variables.png b/docs/sources/img/templating-query_with_variables.png index 9594a33..ca03411 100644 Binary files a/docs/sources/img/templating-query_with_variables.png and b/docs/sources/img/templating-query_with_variables.png differ diff --git a/docs/sources/img/templating-variable_editor.png b/docs/sources/img/templating-variable_editor.png index 003ba81..a6937ea 100644 Binary files a/docs/sources/img/templating-variable_editor.png and b/docs/sources/img/templating-variable_editor.png differ diff --git a/docs/sources/installation/index.md b/docs/sources/installation/index.md index c245d89..541fdbd 100644 --- a/docs/sources/installation/index.md +++ b/docs/sources/installation/index.md @@ -3,7 +3,12 @@ page_description: Installation instructions for Grafana-Zabbix. # Installation +## Choosing plugin version + +Currently (in version `4.x.x`) Grafana-Zabbix plugin supports Zabbix versions `4.x` and `5.x`. Zabbix `3.x` is not supported anymore. Generally, latest plugin should work with latest Grafana version, but if you have any compatibility issue, try to downgrade to previous minor release of Grafana. It's also helpful to report (but use search first to avoid duplicating issues) compatibility issues to the [GitHub](https://github.com/alexanderzobnin/grafana-zabbix/issues). + ## Using grafana-cli tool + Get list of available plugins ```sh @@ -25,6 +30,12 @@ Read more about installing plugins in [Grafana docs](https://grafana.com/docs/pl **WARNING!** The only reliable installation method is `grafana-cli`. Any other way should be treated as a workaround and doesn't provide any backward-compatibility guaranties. +## From github releases + +Starting from version 4.0, each plugin release on GitHub contains packaged plugin. To install it, go to [releases](https://github.com/alexanderzobnin/grafana-zabbix/releases) page, pick release you want to get and click on `Assests`. Built plugin packaged into `zip` archive having name `alexanderzobnin-zabbix-app-x.x.x.zip`. Download it, unpack into your Grafana plugins directory and restart grafana server. Each plugin package contains [digital signature](https://grafana.com/docs/grafana/latest/plugins/plugin-signatures/) which allows Grafana to verify that plugin was published by it's owner and files are not modified. + +**Note**: `since` plugin version 4.0, `grafana-cli` downloads plugin from GitHub release. So downloading plugin package manually, you get the same package as via `grafana-cli`. + ## From github repo **WARNING!** This way doesn't work anymore (`dist/` folder was removed from git). Use `grafana-cli` or build plugin from sources. diff --git a/docs/sources/installation/run_from_master.md b/docs/sources/installation/run_from_master.md index 0af29e5..6c0f933 100644 --- a/docs/sources/installation/run_from_master.md +++ b/docs/sources/installation/run_from_master.md @@ -2,32 +2,42 @@ page_title: Run Grafana-Zabbix from master page_description: Building instructions for Grafana-Zabbix. # Run from master + If you want to build a package yourself, or contribute - here is a guide for how to do that. -### Dependencies +## Prerequisites -- NodeJS LTS +- [NodeJS](https://nodejs.org/) LTS +- [Go](https://golang.org/) version 1.14 or above -### Building plugin +## Building + +### Install dependencies ```bash -npm install -g yarn -yarn install --pure-lockfile -yarn build +make install ``` -### To build plugin and rebuild on file change +### Build plugin (for all platforms) ```bash -yarn watch +make dist +``` + +### To run frontend and rebuild on file change + +```bash +make run-frontend +``` + +### To run backend and rebuild on file change + +```bash +make run-backend ``` ### Run tests -```bash -yarn test -``` -### Run tests on file change ```bash -yarn jest +make test ``` diff --git a/docs/sources/installation/upgrade.md b/docs/sources/installation/upgrade.md index ad99dd8..045724a 100644 --- a/docs/sources/installation/upgrade.md +++ b/docs/sources/installation/upgrade.md @@ -5,6 +5,6 @@ page_description: Upgrade instructions for Grafana-Zabbix. ## Upgrade from 2.x -After [enabling](configuration.md#enable-plugin) Zabbix App go to _Data Sources_, open your configured Zabbix +After [enabling](../../configuration/#enable-plugin) Zabbix App go to _Data Sources_, open your configured Zabbix data source end select _Zabbix_ from _Type_ list again. This is needed because plugin id was changed in Grafana 3.0. diff --git a/docs/sources/reference/alerting.md b/docs/sources/reference/alerting.md index 49dc0e1..fe2c4fd 100644 --- a/docs/sources/reference/alerting.md +++ b/docs/sources/reference/alerting.md @@ -1,41 +1,12 @@ # Alerting -Since version 4.0 [Grafana](https://grafana.com/) has its own alerting engine. +## Alerting overview -> Alerting in Grafana allows you to attach rules to your dashboard panels. When you save the dashboard Grafana will extract the alert rules into a separate alert rule storage and schedule them for evaluation. +Grafana-Zabbix plugin introduces [alerting](https://grafana.com/docs/grafana/latest/alerting/) feature support in 4.0 release. Work still in progress, so current alerting support has some limitations: -> In the alert tab of the graph panel you can configure how often the alert rule should be evaluated and the conditions that need to be met for the alert to change state and trigger its notifications. +- Only `Metrics` query mode supported. +- Queries with data processing functions are not supported. -Read more about alerting feature in [Grafana docs](http://docs.grafana.org/alerting/rules/). +## Creating alerts -On the other hand, Zabbix has its own alerting system with triggers, events and notifications. And the best way is to -combine benefits of these systems into Zabbix plugin for Grafana. So how it works you'll ask? Grafana alerting feature -consists of two main parts: - -- **Alerting execution engine** - The alert rules are evaluated in the Grafana backend in a scheduler and query execution engine that is part of core - Grafana. Only some data sources are supported right now. They include Graphite, Prometheus, InfluxDB and OpenTSDB. -- **Alerting visualisations** - Alerts highlight panels with problems and it can easily be found on the dashboard. - -So Zabbix plugin doesn't use execution engine and doesn't allow to configure rules in Grafana. But it fetches information -about triggers related to metrics at particular panel and fires alert state for these panels. - -![Alerting](../img/reference-alerting_panels.png) - -So there are three possible cases for each panel: - - 1. Panel contains Zabbix items which are used in triggers: - - At least one of these related triggers is in the PROBLEM state. - In this case panel will be highlighted with the red glow and broken heart icon. - - All triggers are in the OK state. - Panel will be displayed with green heart icon without highlighting. - 1. There aren't triggers related to items on panel. - Panel will be displayed without any changes. - -Note, that only triggers with severity above than configured at Data Source config page will be used for panel state -calculation. - -Also plugin can extract thresholds from trigger expression and set it on graph. You can enable this feature -in Data Source config. Thresholds are parts of panel JSON data, so it will be stored in backend if you save dashboard, -but plugin marks this thresholds with special tag, so it will be changed or deleted if you change it in Zabbix. +In order to create alert, open panel query editor and switch to the `Alert` tab. Click `Create Alert` button, configure alert and save dashboard. Refer to [Grafana](https://grafana.com/docs/grafana/latest/alerting/create-alerts/) documentation for more details about alerts configuration.