|
2 | 2 |
|
3 | 3 |  |
4 | 4 |
|
5 | | -This data-source plugin is a complete rewrite from the previous connector. It has |
6 | | -undergone a new architectural design and is not backwards compatible to the |
7 | | -previous version. We nevertheless provide an upgrade procedure to assist you on |
8 | | -the transition. |
| 5 | +This is a [Grafana][1] [data source][2] plugin for visualizing Checkmk metrics |
| 6 | +in Grafana. |
9 | 7 |
|
10 | | -This project has entered the Beta testing phase. |
| 8 | +The plugin requires Checkmk >= 2.1.0 and Grafana >= 8.0 |
| 9 | +(It is possible query data from Checkmk >= 2.0.0p20 but host and service |
| 10 | +dropdowns are not constrained by other active filters and single metric graphs |
| 11 | +do not work with Checkmk Raw Edition) |
11 | 12 |
|
12 | | -## Requirements |
| 13 | +All Checkmk Editions are supported by this plugin, but with different query |
| 14 | +interface as the Enterprise Edition has a more comprehensive filtering engine. |
13 | 15 |
|
14 | | -- Checkmk >= 2.0.0p20 |
15 | | -- Grafana >= 8.0 |
| 16 | +Please consult the chapter ["Integrating Checkmk in Grafana"][3] in the |
| 17 | +official Checkmk documentation on how to use this plugin. |
16 | 18 |
|
17 | | -This plugin release accompanies the checkmk 2.1 release. You can use it already |
18 | | -with checkmk 2.0.0p20 for testing purposes, however bug-fixes, changes and |
19 | | -updates will mainly take place on checkmk 2.1 to not compromise the stability |
20 | | -of checkmk 2.0. |
| 19 | + |
21 | 20 |
|
22 | | -## Getting started |
| 21 | +See [CHANGELOG.md](CHANGELOG.md) for information about updating from previous |
| 22 | +versions. |
23 | 23 |
|
24 | | -### Installation |
| 24 | +See [DEVELOPMENT.md](DEVELOPMENT.md) for information about how to build and |
| 25 | +release this software. |
25 | 26 |
|
26 | | -Download the released version of this repository or clone it. Released versions |
27 | | -include the built artifacts, for non-releases you need to build the plugin |
28 | | -yourself as explained further on this guide. |
29 | | - |
30 | | -This plugin's id is: `tribe-29-checkmk-datasource` |
31 | | -For development it is easiest to create a symlink inside your Grafana plugins |
32 | | -path(`/var/lib/grafana/plugins`) to this repository. Or if using docker mount |
33 | | -this repository as a volume. |
34 | | - |
35 | | -This plugin is not signed, thus you need to allow it on the `grafana.ini` file under |
36 | | -`allow_loading_unsigned_plugins=tribe-29-checkmk-datasource` |
37 | | - |
38 | | -Beware that starting Grafana>=8.2 the systemd start script changed permissions |
39 | | -and you need to make sure this plugin is readable under those conditions. [Issue |
40 | | -#52](https://github.com/tribe29/grafana-checkmk-datasource/issues/52#issuecomment-1026917446) |
41 | | -includes troubleshooting information. |
42 | | - |
43 | | -### Plugin configuration |
44 | | - |
45 | | -URL |
46 | | -: URL of the Checkmk Server used. |
47 | | -: Example: http://checkmk.server/site/ |
48 | | - |
49 | | -Edition |
50 | | -: Your checkmk edition |
51 | | -: The connector will validate against the checkmk server your selection. |
52 | | - |
53 | | -Username |
54 | | -: User for API calls. |
55 | | -: Don't use `automation`, because that user has also admin configuration rights. |
56 | | - Use a dedicated user that has only monitoring permissions. |
57 | | - |
58 | | -Secret |
59 | | -: Secret for the API User. |
60 | | -: This key is not transmitted from the Grafana UI, only the back-end has access |
61 | | - to it. This is a security improvement over the previous plugin. |
62 | | - |
63 | | -Save & Test will check if the User authenticates and the data source is |
64 | | -reachable. |
65 | | - |
66 | | -## Current state |
67 | | - |
68 | | -This plugin offers 2 different interfaces, depending if you connect to an |
69 | | -Enterprise editions site or a RAW edition one. |
70 | | - |
71 | | -- CEE interface is now a filter based selection for graph templates or single |
72 | | - metrics. |
73 | | -- RAW interface offers Service graphs and some single metrics. |
74 | | - |
75 | | -- Dropped "Label Format" option. Prefer Grafana overrides. |
76 | | -- Annotations are not available. |
77 | | - |
78 | | -### Filter base graph selection (Combined graphs, CEE) |
79 | | - |
80 | | -- Construct combined graphs using traditional Checkmk filters. Currently available: |
81 | | - - Site filter |
82 | | - - Host exact match |
83 | | - - Host regex |
84 | | - - Service exact match |
85 | | - - Service Regex |
86 | | - - Host labels multi select |
87 | | - - Host groups |
88 | | - - Service groups |
89 | | - - Host Tags |
90 | | - |
91 | | -### Static filter selection (Service Graphs, RAW) |
92 | | - |
93 | | -Service graphs are defined by their specific descriptors for |
94 | | - |
95 | | -- Site |
96 | | -- Hostname |
97 | | -- Service |
98 | | - |
99 | | -## Minor annoyances |
100 | | - |
101 | | -- When selecting a Filter. The focus jumps to the next Filter dropdown menu |
102 | | - instead of the more intuitive focus on the selected filter itself. |
103 | | -- Composed single metrics are not available anymore. E.g. from the Filesystem |
104 | | - service "Free space" is a composed metric being the difference between "Total |
105 | | - Size" and "Used Space". |
106 | | -- Graphs that consist of a single metric(e.g. Uptime) appear on the Single |
107 | | - metric graph type on the CEE interface, whereas there show up in duplication |
108 | | - as a Template Type and a Single metric type on the RAW interface. |
109 | | -- If connection to a checkmk 2.0 site. |
110 | | - - Host & service dropdown options are not constrained by other active filters in the query. |
111 | | - - Single metric graphs don't work on the RAW interface. |
112 | | - |
113 | | -## Updating from the previous connector |
114 | | - |
115 | | -We provide a Python script `utils/converter.py` which updates the Grafana |
116 | | -SQLite database from the old connector setup to the new one. In that process it |
117 | | -will go over all the dashboards and create a new version of them with the |
118 | | -updated connector. **PLEASE BACKUP THIS FILE BEFORE UPDATING.** |
119 | | - |
120 | | -1. Install and configure this new connector. Take note of the name you give it |
121 | | - and take note of which name you gave the old connector. In this example we call them "Latest cmk connector" and "checkmk". |
122 | | -2. Stop your Grafana instance and backup the file `grafana.db` |
123 | | -3. Use the `converter.py` script, it has a `-h` option to remind you of the |
124 | | - usage. To update from the previous datasource "checkmk" into this new |
125 | | - connector "Latest cmk connector" on the `grafana.db` file, execute: |
126 | | - |
127 | | -```BASH |
128 | | -python3 converter.py -o "checkmk" -n "Latest cmk connector" -db grafana.db |
129 | | -``` |
130 | | - |
131 | | -If any of the two datasources is your default datasource, omit that option on |
132 | | -the command. |
133 | | - |
134 | | -This script will go over all your dashboards, it might take some time because it |
135 | | -also queries information from your checkmk site, and that communication takes |
136 | | -time. |
137 | | - |
138 | | -4. After the update completes start your Grafana server again. |
139 | | - |
140 | | -### Building the plugin |
141 | | - |
142 | | -1. Install dependencies |
143 | | - |
144 | | -```BASH |
145 | | -yarn install |
146 | | -``` |
147 | | - |
148 | | -2. Build plugin in development mode or run in watch mode |
149 | | - |
150 | | -```BASH |
151 | | -yarn dev |
152 | | -``` |
153 | | - |
154 | | -or |
155 | | - |
156 | | -```BASH |
157 | | -yarn watch |
158 | | -``` |
159 | | - |
160 | | -3. Build plugin in production mode |
161 | | - |
162 | | -```BASH |
163 | | -yarn build |
164 | | -``` |
165 | | - |
166 | | -# Maintenance |
167 | | - |
168 | | -Code formatting |
169 | | - |
170 | | -```BASH |
171 | | -yarn prettier --write src |
172 | | -``` |
173 | | - |
174 | | -Update dependencies |
175 | | - |
176 | | -```BASH |
177 | | -yarn upgrade --latest |
178 | | -``` |
| 27 | +[1]: https://grafana.com/grafana/ |
| 28 | +[2]: https://grafana.com/docs/grafana/latest/datasources/ |
| 29 | +[3]: https://docs.checkmk.com/latest/en/grafana.html |
0 commit comments