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```
13 services.prometheus.exporters.node = {
14 enable = true;
15 port = 9100;
16 enabledCollectors = [
17 "logind"
18 "systemd"
19 ];
20 disabledCollectors = [
21 "textfile"
22 ];
23 openFirewall = true;
24 firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
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```
39 services.prometheus = {
40 # ...
41
42 scrapeConfigs = [
43 {
44 job_name = "node";
45 static_configs = [{
46 targets = [ "localhost:${toString config.services.prometheus.exporters.node.port}" ];
47 }];
48 }
49 ];
50
51 # ...
52 }
53```
54
55## Adding a new exporter {#module-services-prometheus-exporters-new-exporter}
56
57To add a new exporter, it has to be packaged first (see
58`nixpkgs/pkgs/servers/monitoring/prometheus/` for
59examples), then a module can be added. The postfix exporter is used in this
60example:
61
62 - Some default options for all exporters are provided by
63 `nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix`:
64
65 - `enable`
66 - `port`
67 - `listenAddress`
68 - `extraFlags`
69 - `openFirewall`
70 - `firewallFilter`
71 - `user`
72 - `group`
73 - As there is already a package available, the module can now be added. This
74 is accomplished by adding a new file to the
75 `nixos/modules/services/monitoring/prometheus/exporters/`
76 directory, which will be called postfix.nix and contains all exporter
77 specific options and configuration:
78 ```
79 # nixpkgs/nixos/modules/services/prometheus/exporters/postfix.nix
80 { config, lib, pkgs, options }:
81
82 with lib;
83
84 let
85 # for convenience we define cfg here
86 cfg = config.services.prometheus.exporters.postfix;
87 in
88 {
89 port = 9154; # The postfix exporter listens on this port by default
90
91 # `extraOpts` is an attribute set which contains additional options
92 # (and optional overrides for default options).
93 # Note that this attribute is optional.
94 extraOpts = {
95 telemetryPath = mkOption {
96 type = types.str;
97 default = "/metrics";
98 description = ''
99 Path under which to expose metrics.
100 '';
101 };
102 logfilePath = mkOption {
103 type = types.path;
104 default = /var/log/postfix_exporter_input.log;
105 example = /var/log/mail.log;
106 description = ''
107 Path where Postfix writes log entries.
108 This file will be truncated by this exporter!
109 '';
110 };
111 showqPath = mkOption {
112 type = types.path;
113 default = /var/spool/postfix/public/showq;
114 example = /var/lib/postfix/queue/public/showq;
115 description = ''
116 Path at which Postfix places its showq socket.
117 '';
118 };
119 };
120
121 # `serviceOpts` is an attribute set which contains configuration
122 # for the exporter's systemd service. One of
123 # `serviceOpts.script` and `serviceOpts.serviceConfig.ExecStart`
124 # has to be specified here. This will be merged with the default
125 # service configuration.
126 # Note that by default 'DynamicUser' is 'true'.
127 serviceOpts = {
128 serviceConfig = {
129 DynamicUser = false;
130 ExecStart = ''
131 ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
132 --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
133 --web.telemetry-path ${cfg.telemetryPath} \
134 ${concatStringsSep " \\\n " cfg.extraFlags}
135 '';
136 };
137 };
138 }
139 ```
140 - This should already be enough for the postfix exporter. Additionally one
141 could now add assertions and conditional default values. This can be done
142 in the 'meta-module' that combines all exporter definitions and generates
143 the submodules:
144 `nixpkgs/nixos/modules/services/prometheus/exporters.nix`
145
146## Updating an exporter module {#module-services-prometheus-exporters-update-exporter-module}
147
148Should an exporter option change at some point, it is possible to add
149information about the change to the exporter definition similar to
150`nixpkgs/nixos/modules/rename.nix`:
151```
152{ config, lib, pkgs, options }:
153
154with lib;
155
156let
157 cfg = config.services.prometheus.exporters.nginx;
158in
159{
160 port = 9113;
161 extraOpts = {
162 # additional module options
163 # ...
164 };
165 serviceOpts = {
166 # service configuration
167 # ...
168 };
169 imports = [
170 # 'services.prometheus.exporters.nginx.telemetryEndpoint' -> 'services.prometheus.exporters.nginx.telemetryPath'
171 (mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ])
172
173 # removed option 'services.prometheus.exporters.nginx.insecure'
174 (mkRemovedOptionModule [ "insecure" ] ''
175 This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true.
176 '')
177 ({ options.warnings = options.warnings; })
178 ];
179}
180```