nixpkgs-custom/nixos/modules/services/monitoring/prometheus/exporters.xml

<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>