nixos/prometheus-exporters: add postfix exporter & documentation

nixos/modules/services/monitoring/prometheus/exporters.nix

@@ -25,6 +25,7 @@ let
     minio    = import ./exporters/minio.nix    { inherit config lib pkgs; };
     nginx    = import ./exporters/nginx.nix    { inherit config lib pkgs; };
     node     = import ./exporters/node.nix     { inherit config lib pkgs; };
+    postfix  = import ./exporters/postfix.nix  { inherit config lib pkgs; };
     snmp     = import ./exporters/snmp.nix     { inherit config lib pkgs; };
     unifi    = import ./exporters/unifi.nix    { inherit config lib pkgs; };
     varnish  = import ./exporters/varnish.nix  { inherit config lib pkgs; };
@@ -166,4 +167,6 @@ in
       conf = cfg.${name};
     }) exporterOpts)
   );
+
+  meta.doc = ./exporters.xml;
 }

nixos/modules/services/monitoring/prometheus/exporters.xml

@@ -0,0 +1,135 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="module-services-prometheus-exporters">
+
+<title>Prometheus exporters</title>
+
+<para>Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.</para>
+
+<section><title>Configuration</title>
+  <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:
+<programlisting>
+  services.promtheus.exporters.node = {
+    enable = true;
+    enabledCollectors = [
+      "logind"
+      "systemd"
+    ];
+    disabledCollectors = [
+      "textfile"
+    ];
+    openFirewall = true;
+    firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
+  };
+</programlisting>
+It should now serve all metrics from the collectors
+that are explicitly enabled and the ones that are
+<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
+allow incoming connections to the exporter's port on the bridge interface <literal>br0</literal>
+(this would have to be configured seperately of course).
+For more information about configuration see <literal>man configuration.nix</literal> or
+search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>.
+</para>
+</section>
+<section><title>Adding a new exporter</title>
+  <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>
+<itemizedlist>
+  <listitem>
+    <para>
+      Some default options for all exporters are provided by
+      <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
+    </para>
+  </listitem>
+  <listitem override='none'>
+    <itemizedlist>
+      <listitem><para><literal>enable</literal></para></listitem>
+      <listitem><para><literal>port</literal></para></listitem>
+      <listitem><para><literal>listenAddress</literal></para></listitem>
+      <listitem><para><literal>extraFlags</literal></para></listitem>
+      <listitem><para><literal>openFirewall</literal></para></listitem>
+      <listitem><para><literal>firewallFilter</literal></para></listitem>
+      <listitem><para><literal>user</literal></para></listitem>
+      <listitem><para><literal>group</literal></para></listitem>
+    </itemizedlist>
+  </listitem>
+  <listitem>
+    <para>As there is already a package available, the module can now be added.
+      This is accomplished by adding a new file to the
+      <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> directory,
+      which will be called postfix.nix and contains all exporter specific options
+      and configuration:
+      <programlisting>
+        # nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix
+        { config, lib, pkgs }:
+
+        with lib;
+
+        let
+          # for convenience we define cfg here
+          cfg = config.services.prometheus.exporters.postfix;
+        in
+        {
+          port = 9154; # The postfix exporter listens on this port by default
+
+          # `extraOpts` is an attribute set which contains additional options
+          # (and optional overrides for default options).
+          # Note that this attribute is optional.
+          extraOpts = {
+            telemetryPath = mkOption {
+              type = types.str;
+              default = "/metrics";
+              description = ''
+                Path under which to expose metrics.
+              '';
+            };
+            logfilePath = mkOption {
+              type = types.path;
+              default = /var/log/postfix_exporter_input.log;
+              example = /var/log/mail.log;
+              description = ''
+                Path where Postfix writes log entries.
+                This file will be truncated by this exporter!
+              '';
+            };
+            showqPath = mkOption {
+              type = types.path;
+              default = /var/spool/postfix/public/showq;
+              example = /var/lib/postfix/queue/public/showq;
+              description = ''
+                Path at which Postfix places its showq socket.
+              '';
+            };
+          };
+
+          # `serviceOpts` is an attribute set which contains configuration
+          # for the exporter's systemd service. One of
+          # `serviceOpts.script` and `serviceOpts.serviceConfig.ExecStart`
+          # has to be specified here. This will be merged with the default
+          # service confiuration.
+          serviceOpts = {
+            serviceConfig = {
+              ExecStart = ''
+                ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
+                  --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
+                  --web.telemetry-path ${cfg.telemetryPath} \
+                  ${concatStringsSep " \\\n  " cfg.extraFlags}
+              '';
+            };
+          };
+        }
+      </programlisting>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      This should already be enough for the postfix exporter. Additionally one could
+      now add assertions and conditional default values. This can be done in the
+      'meta-module' that combines all exporter definitions and generates the submodules:
+      <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
+    </para>
+  </listitem>
+</itemizedlist>
+</section>
+</chapter>

nixos/modules/services/monitoring/prometheus/exporters/postfix.nix

@@ -0,0 +1,46 @@
+{ config, lib, pkgs }:
+
+with lib;
+
+let
+  cfg = config.services.prometheus.exporters.postfix;
+in
+{
+  port = 9154;
+  extraOpts = {
+    telemetryPath = mkOption {
+      type = types.str;
+      default = "/metrics";
+      description = ''
+        Path under which to expose metrics.
+      '';
+    };
+    logfilePath = mkOption {
+      type = types.path;
+      default = "/var/log/postfix_exporter_input.log";
+      example = "/var/log/mail.log";
+      description = ''
+        Path where Postfix writes log entries.
+        This file will be truncated by this exporter!
+      '';
+    };
+    showqPath = mkOption {
+      type = types.path;
+      default = "/var/spool/postfix/public/showq";
+      example = "/var/lib/postfix/queue/public/showq";
+      description = ''
+        Path where Postfix places it's showq socket.
+      '';
+    };
+  };
+  serviceOpts = {
+    serviceConfig = {
+      ExecStart = ''
+        ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
+          --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
+          --web.telemetry-path ${cfg.telemetryPath} \
+          ${concatStringsSep " \\\n  " cfg.extraFlags}
+      '';
+    };
+  };
+}