You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+63-67
Original file line number
Diff line number
Diff line change
@@ -12,29 +12,70 @@ For more information about mixins, see:
12
12
* "[Prometheus Monitoring Mixins: Using Jsonnet to Package Together Dashboards, Alerts and Exporters](https://www.youtube.com/watch?v=b7-DtFfsL6E)" talk from CloudNativeCon Copenhagen 2018.
13
13
* "[Prometheus Monitoring Mixins: Using Jsonnet to Package Together Dashboards, Alerts and Exporters](https://promcon.io/2018-munich/talks/prometheus-monitoring-mixins/)" talk from PromCon 2018 (slightly updated).
14
14
15
+
## Mixin creation guidelines
16
+
17
+
Mixins follow a standard structure, which is enforced by the [mixtool CLI](https://github.com/monitoring-mixins/mixtool).
18
+
19
+
The schema defines 4 root jsonnet objects to keep Grafana dashboards, Prometheus alerts and rules, and configuration parameters to be applied on the fly when building the mixin.
20
+
21
+
```
22
+
.
23
+
├── grafanaDashboards::
24
+
├── prometheusAlerts::
25
+
│ ├── groups:
26
+
├── prometheusRules::
27
+
│ ├── groups:
28
+
├── _config::
29
+
```
30
+
31
+
This is the expected structure of a mixin jsonnet object definition. The actual recommended file structure has a `mixin.libsonnet` file as root, like the following.
32
+
33
+
```
34
+
.
35
+
├── mixin.libsonnet
36
+
├── dashboards
37
+
│ ├── dashboards.libsonnet
38
+
│ │ ├── grafanaDashboards::
39
+
├── alerts
40
+
│ ├── alerts.libsonnet
41
+
│ │ ├── prometheusAlerts::
42
+
├── rules
43
+
│ ├── rules.libsonnet
44
+
│ │ ├── prometheusRules::
45
+
```
46
+
47
+
Please note that all the 3 jsonnet objects are made hidden/private (indicated by the trailing ::).
48
+
This is the expected standard to be used with mixtool CLI.
49
+
If you want to use pure jsonnet commands against the mixin, please make those objects public.
50
+
51
+
The mixin.libsonnet file imports all the files described on the previous section, packaging up the mixin.
52
+
It may also contain some changes to the original files, whenever needed.
53
+
These can be defined in itself or importing another jsonnet definition file that changes any of the 4 objects of the structure.
54
+
55
+
```json
56
+
(import 'dashboards/dashboards.libsonnet') +
57
+
(import 'alerts/alerts.libsonnet') +
58
+
(import 'rules/rules.libsonnet')
59
+
(import 'config.libsonnet') +
60
+
```
61
+
15
62
## How to use mixins.
16
63
17
64
Mixins are designed to be vendored into the repo with your infrastructure config.
18
65
To do this, use [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler):
19
66
20
67
You then have three options for deploying your dashboards
21
68
1. Generate the config files and deploy them yourself.
22
-
1. Use ksonnet to deploy this mixin along with Prometheus and Grafana.
23
-
1. Use kube-prometheus to deploy this mixin.
69
+
2. Use kube-prometheus to deploy this mixin.
70
+
3. Use Grizzly to deploy this mixin
24
71
25
72
## Generate config files
26
73
27
74
You can manually generate the alerts, dashboards and rules files, but first you
28
-
must install some tools:
75
+
must install some tools. Make sure you're using golang v1.17 or higher, and run:
29
76
30
77
```
31
-
$ go install github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb@latest
32
-
33
-
# macOS
34
-
$ brew install jsonnet-bundler
35
-
36
-
# Archlinux AUR
37
-
$ yay -S jsonnet
78
+
go install github.com/monitoring-mixins/mixtool/cmd/mixtool@master
38
79
```
39
80
40
81
Then, grab the mixin and its dependencies:
@@ -45,84 +86,38 @@ $ cd <mixin repo>
45
86
$ jb install
46
87
```
47
88
48
-
Finally, build the mixin:
89
+
Finally, build the mixin with the self contained Makefile, that can be copied from the one present in this repo:
49
90
50
91
```
51
92
$ make prometheus_alerts.yaml
52
93
$ make prometheus_rules.yaml
53
94
$ make dashboards_out
95
+
$ make all
54
96
```
55
97
98
+
All files are generated inside an `out` folder.
56
99
The `prometheus_alerts.yaml` and `prometheus_rules.yaml` file then need to passed
57
-
to your Prometheus server, and the files in `dashboards_out` need to be imported
100
+
to your Prometheus server, and the files in `out/dashboards` need to be imported
58
101
into you Grafana server. The exact details will depending on how you deploy your
Assuming you want to run in the default namespace ('environment' in ksonnet parlance), add the follow to the file `environments/default/main.jsonnet`:
98
-
99
-
```
100
-
local prometheus = import "prometheus-ksonnet/prometheus-ksonnet.libsonnet";
101
-
102
-
prometheus {
103
-
_config+:: {
104
-
namespace: "default",
105
-
},
106
-
}
107
-
```
104
+
## Using kube-prometheus
108
105
109
-
Apply your config:
106
+
See the kube-prometheus docs for [instructions on how to use mixins with kube-prometheus](https://github.com/coreos/kube-prometheus#kube-prometheus).
110
107
111
-
```
112
-
$ ks apply default
113
-
```
108
+
## Using Grizzly
114
109
115
-
## Using kube-prometheus
110
+
See the grizzly docs for [instructions on how to use mixins with grizzly](https://grafana.github.io/grizzly/hidden-elements/)
116
111
117
-
See the kube-prometheus docs for [instructions on how to use mixins with kube-prometheus](https://github.com/coreos/kube-prometheus#kube-prometheus).
112
+
Grizzly support for monitoring-mixin standard is deprecated, but you can use [this adapter](https://github.com/grafana/jsonnet-libs/tree/master/grizzly) to make it work on newer versions of Grizlly.
118
113
119
114
## Customising the mixin
120
115
121
116
Mixins typically allows you to override the selectors used for various jobs,
122
117
to match those used in your Prometheus set.
123
118
124
119
This example uses the [kubernetes-mixin](https://github.com/kubernetes-monitoring/kubernetes-mixin).
125
-
In a new directory, add a file `mixin.libsonnet`:
120
+
In a new directory, add a file `mixin.libsonnet`:
126
121
127
122
```
128
123
local kubernetes = import "kubernetes-mixin/mixin.libsonnet";
@@ -148,9 +143,10 @@ Generate the alerts, rules and dashboards:
0 commit comments