path: root/nixos/modules/services/monitoring/prometheus/exporters.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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 xml:id="module-services-prometheus-exporters-configuration">
    <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:
    </para>
    <programlisting>
  services.prometheus.exporters.node = {
    enable = true;
    port = 9100;
    enabledCollectors = [
      &quot;logind&quot;
      &quot;systemd&quot;
    ];
    disabledCollectors = [
      &quot;textfile&quot;
    ];
    openFirewall = true;
    firewallFilter = &quot;-i br0 -p tcp -m tcp --dport 9100&quot;;
  };
</programlisting>
    <para>
      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
      separately 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>
    <para>
      Prometheus can now be configured to consume the metrics produced
      by the exporter:
    </para>
    <programlisting>
    services.prometheus = {
      # ...

      scrapeConfigs = [
        {
          job_name = &quot;node&quot;;
          static_configs = [{
            targets = [ &quot;localhost:${toString config.services.prometheus.exporters.node.port}&quot; ];
          }];
        }
      ];

      # ...
    }
</programlisting>
  </section>
  <section xml:id="module-services-prometheus-exporters-new-exporter">
    <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>
        <itemizedlist spacing="compact">
          <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:
        </para>
        <programlisting>
# nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix
{ config, lib, pkgs, options }:

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 = &quot;/metrics&quot;;
      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 configuration.
  # Note that by default 'DynamicUser' is 'true'.
  serviceOpts = {
    serviceConfig = {
      DynamicUser = false;
      ExecStart = ''
        ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
          --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
          --web.telemetry-path ${cfg.telemetryPath} \
          ${concatStringsSep &quot; \\\n  &quot; cfg.extraFlags}
      '';
    };
  };
}
</programlisting>
      </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
          <quote>meta-module</quote> that combines all exporter
          definitions and generates the submodules:
          <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
        </para>
      </listitem>
    </itemizedlist>
  </section>
  <section xml:id="module-services-prometheus-exporters-update-exporter-module">
    <title>Updating an exporter module</title>
    <para>
      Should an exporter option change at some point, it is possible to
      add information about the change to the exporter definition
      similar to <literal>nixpkgs/nixos/modules/rename.nix</literal>:
    </para>
    <programlisting>
{ config, lib, pkgs, options }:

with lib;

let
  cfg = config.services.prometheus.exporters.nginx;
in
{
  port = 9113;
  extraOpts = {
    # additional module options
    # ...
  };
  serviceOpts = {
    # service configuration
    # ...
  };
  imports = [
    # 'services.prometheus.exporters.nginx.telemetryEndpoint' -&gt; 'services.prometheus.exporters.nginx.telemetryPath'
    (mkRenamedOptionModule [ &quot;telemetryEndpoint&quot; ] [ &quot;telemetryPath&quot; ])

    # removed option 'services.prometheus.exporters.nginx.insecure'
    (mkRemovedOptionModule [ &quot;insecure&quot; ] ''
      This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true.
    '')
    ({ options.warnings = options.warnings; })
  ];
}
</programlisting>
  </section>
</chapter>