pyrox.dev
1# Prometheus exporters {#module-services-prometheus-exporters}
2
3Prometheus exporters provide metrics for the
4[prometheus monitoring system](https://prometheus.io).
5
6## Configuration {#module-services-prometheus-exporters-configuration}
7
8One of the most common exporters is the
9[node exporter](https://github.com/prometheus/node_exporter),
10it provides hardware and OS metrics from the host it's
11running on. The exporter could be configured as follows:
12```nix
13{
14 services.prometheus.exporters.node = {
15 enable = true;
16 port = 9100;
17 enabledCollectors = [
18 "logind"
19 "systemd"
20 ];
21 disabledCollectors = [ "textfile" ];
22 openFirewall = true;
23 firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
24 };
25}
26```
27It should now serve all metrics from the collectors that are explicitly
28enabled and the ones that are
29[enabled by default](https://github.com/prometheus/node_exporter#enabled-by-default),
30via http under `/metrics`. In this
31example the firewall should just allow incoming connections to the
32exporter's port on the bridge interface `br0` (this would
33have to be configured separately of course). For more information about
34configuration see `man configuration.nix` or search through
35the [available options](https://nixos.org/nixos/options.html#prometheus.exporters).
36
37Prometheus can now be configured to consume the metrics produced by the exporter:
38```nix
39{
40 services.prometheus = {
41 # ...
42
43 scrapeConfigs = [
44 {
45 job_name = "node";
46 static_configs = [
47 {
48 targets = [
49 "localhost:${toString config.services.prometheus.exporters.node.port}"
50 ];
51 }
52 ];
53 }
54 ];
55
56 # ...
57 };
58}
59```
60
61## Adding a new exporter {#module-services-prometheus-exporters-new-exporter}
62
63To add a new exporter, it has to be packaged first (see
64`nixpkgs/pkgs/servers/monitoring/prometheus/` for
65examples), then a module can be added. The postfix exporter is used in this
66example:
67
68 - Some default options for all exporters are provided by
69 `nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix`:
70
71 - `enable`
72 - `port`
73 - `listenAddress`
74 - `extraFlags`
75 - `openFirewall`
76 - `firewallFilter`
77 - `firewallRules`
78 - `user`
79 - `group`
80 - As there is already a package available, the module can now be added. This
81 is accomplished by adding a new file to the
82 `nixos/modules/services/monitoring/prometheus/exporters/`
83 directory, which will be called postfix.nix and contains all exporter
84 specific options and configuration:
85 ```nix
86 # nixpkgs/nixos/modules/services/prometheus/exporters/postfix.nix
87 {
88 config,
89 lib,
90 pkgs,
91 options,
92 }:
93 let
94 # for convenience we define cfg here
95 cfg = config.services.prometheus.exporters.postfix;
96 in
97 {
98 port = 9154; # The postfix exporter listens on this port by default
99
100 # `extraOpts` is an attribute set which contains additional options
101 # (and optional overrides for default options).
102 # Note that this attribute is optional.
103 extraOpts = {
104 telemetryPath = lib.mkOption {
105 type = lib.types.str;
106 default = "/metrics";
107 description = ''
108 Path under which to expose metrics.
109 '';
110 };
111 logfilePath = lib.mkOption {
112 type = lib.types.path;
113 default = /var/log/postfix_exporter_input.log;
114 example = /var/log/mail.log;
115 description = ''
116 Path where Postfix writes log entries.
117 This file will be truncated by this exporter!
118 '';
119 };
120 showqPath = lib.mkOption {
121 type = lib.types.path;
122 default = /var/spool/postfix/public/showq;
123 example = /var/lib/postfix/queue/public/showq;
124 description = ''
125 Path at which Postfix places its showq socket.
126 '';
127 };
128 };
129
130 # `serviceOpts` is an attribute set which contains configuration
131 # for the exporter's systemd service. One of
132 # `serviceOpts.script` and `serviceOpts.serviceConfig.ExecStart`
133 # has to be specified here. This will be merged with the default
134 # service configuration.
135 # Note that by default 'DynamicUser' is 'true'.
136 serviceOpts = {
137 serviceConfig = {
138 DynamicUser = false;
139 ExecStart = ''
140 ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
141 --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
142 --web.telemetry-path ${cfg.telemetryPath} \
143 ${lib.concatStringsSep " \\\n " cfg.extraFlags}
144 '';
145 };
146 };
147 }
148 ```
149 - This should already be enough for the postfix exporter. Additionally one
150 could now add assertions and conditional default values. This can be done
151 in the 'meta-module' that combines all exporter definitions and generates
152 the submodules:
153 `nixpkgs/nixos/modules/services/prometheus/exporters.nix`
154
155## Updating an exporter module {#module-services-prometheus-exporters-update-exporter-module}
156
157Should an exporter option change at some point, it is possible to add
158information about the change to the exporter definition similar to
159`nixpkgs/nixos/modules/rename.nix`:
160```nix
161{
162 config,
163 lib,
164 pkgs,
165 options,
166}:
167
168let
169 cfg = config.services.prometheus.exporters.nginx;
170in
171{
172 port = 9113;
173 extraOpts = {
174 # additional module options
175 # ...
176 };
177 serviceOpts = {
178 # service configuration
179 # ...
180 };
181 imports = [
182 # 'services.prometheus.exporters.nginx.telemetryEndpoint' -> 'services.prometheus.exporters.nginx.telemetryPath'
183 (lib.mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ])
184
185 # removed option 'services.prometheus.exporters.nginx.insecure'
186 (lib.mkRemovedOptionModule [ "insecure" ] ''
187 This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true.
188 '')
189 ({ options.warnings = options.warnings; })
190 ];
191}
192```