pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-services-prometheus-exporters">
6
7<title>Prometheus exporters</title>
8
9<para>Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.</para>
10
11<section xml:id="module-services-prometheus-exporters-configuration"><title>Configuration</title>
12 <para>One of the most common exporters is the <link xlink:href="https://github.com/prometheus/node_exporter">node exporter</link>, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows:
13<programlisting>
14 services.promtheus.exporters.node = {
15 enable = true;
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</programlisting>
27It should now serve all metrics from the collectors
28that are explicitly enabled and the ones that are
29<link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled by default</link>, via http under <literal>/metrics</literal>. In this example the firewall should just
30allow incoming connections to the exporter's port on the bridge interface <literal>br0</literal>
31(this would have to be configured seperately of course).
32For more information about configuration see <literal>man configuration.nix</literal> or
33search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>.
34</para>
35</section>
36<section xml:id="module-services-prometheus-exporters-new-exporter"><title>Adding a new exporter</title>
37 <para>To add a new exporter, it has to be packaged first (see <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for examples), then a module can be added. The postfix exporter is used in this example:</para>
38<itemizedlist>
39 <listitem>
40 <para>
41 Some default options for all exporters are provided by
42 <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
43 </para>
44 </listitem>
45 <listitem override='none'>
46 <itemizedlist>
47 <listitem><para><literal>enable</literal></para></listitem>
48 <listitem><para><literal>port</literal></para></listitem>
49 <listitem><para><literal>listenAddress</literal></para></listitem>
50 <listitem><para><literal>extraFlags</literal></para></listitem>
51 <listitem><para><literal>openFirewall</literal></para></listitem>
52 <listitem><para><literal>firewallFilter</literal></para></listitem>
53 <listitem><para><literal>user</literal></para></listitem>
54 <listitem><para><literal>group</literal></para></listitem>
55 </itemizedlist>
56 </listitem>
57 <listitem>
58 <para>As there is already a package available, the module can now be added.
59 This is accomplished by adding a new file to the
60 <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> directory,
61 which will be called postfix.nix and contains all exporter specific options
62 and configuration:
63 <programlisting>
64 # nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix
65 { config, lib, pkgs }:
66
67 with lib;
68
69 let
70 # for convenience we define cfg here
71 cfg = config.services.prometheus.exporters.postfix;
72 in
73 {
74 port = 9154; # The postfix exporter listens on this port by default
75
76 # `extraOpts` is an attribute set which contains additional options
77 # (and optional overrides for default options).
78 # Note that this attribute is optional.
79 extraOpts = {
80 telemetryPath = mkOption {
81 type = types.str;
82 default = "/metrics";
83 description = ''
84 Path under which to expose metrics.
85 '';
86 };
87 logfilePath = mkOption {
88 type = types.path;
89 default = /var/log/postfix_exporter_input.log;
90 example = /var/log/mail.log;
91 description = ''
92 Path where Postfix writes log entries.
93 This file will be truncated by this exporter!
94 '';
95 };
96 showqPath = mkOption {
97 type = types.path;
98 default = /var/spool/postfix/public/showq;
99 example = /var/lib/postfix/queue/public/showq;
100 description = ''
101 Path at which Postfix places its showq socket.
102 '';
103 };
104 };
105
106 # `serviceOpts` is an attribute set which contains configuration
107 # for the exporter's systemd service. One of
108 # `serviceOpts.script` and `serviceOpts.serviceConfig.ExecStart`
109 # has to be specified here. This will be merged with the default
110 # service confiuration.
111 serviceOpts = {
112 serviceConfig = {
113 ExecStart = ''
114 ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
115 --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
116 --web.telemetry-path ${cfg.telemetryPath} \
117 ${concatStringsSep " \\\n " cfg.extraFlags}
118 '';
119 };
120 };
121 }
122 </programlisting>
123 </para>
124 </listitem>
125 <listitem>
126 <para>
127 This should already be enough for the postfix exporter. Additionally one could
128 now add assertions and conditional default values. This can be done in the
129 'meta-module' that combines all exporter definitions and generates the submodules:
130 <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
131 </para>
132 </listitem>
133</itemizedlist>
134</section>
135</chapter>