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

   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  <title>Prometheus exporters</title>
   7  <para>
   8   Prometheus exporters provide metrics for the
   9   <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.
  10  </para>
  11  <section xml:id="module-services-prometheus-exporters-configuration">
  12   <title>Configuration</title>
  13
  14   <para>
  15    One of the most common exporters is the
  16    <link xlink:href="https://github.com/prometheus/node_exporter">node
  17    exporter</link>, it provides hardware and OS metrics from the host it's
  18    running on. The exporter could be configured as follows:
  19 <programlisting>
  20   services.prometheus.exporters.node = {
  21     enable = true;
  22     port = 9100;
  23     enabledCollectors = [
  24       "logind"
  25       "systemd"
  26     ];
  27     disabledCollectors = [
  28       "textfile"
  29     ];
  30     openFirewall = true;
  31     firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
  32   };
  33 </programlisting>
  34    It should now serve all metrics from the collectors that are explicitly
  35    enabled and the ones that are
  36    <link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled
  37    by default</link>, via http under <literal>/metrics</literal>. In this
  38    example the firewall should just allow incoming connections to the
  39    exporter's port on the bridge interface <literal>br0</literal> (this would
  40    have to be configured seperately of course). For more information about
  41    configuration see <literal>man configuration.nix</literal> or search through
  42    the
  43    <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available
  44    options</link>.
  45   </para>
  46
  47   <para>
  48     Prometheus can now be configured to consume the metrics produced by the exporter:
  49     <programlisting>
  50     services.prometheus = {
  51       # ...
  52
  53       scrapeConfigs = [
  54         {
  55           job_name = "node";
  56           static_configs = [{
  57             targets = [ "localhost:${toString config.services.prometheus.exporters.node.port}" ];
  58           }];
  59         }
  60       ];
  61
  62       # ...
  63     }
  64     </programlisting>
  65   </para>
  66  </section>
  67  <section xml:id="module-services-prometheus-exporters-new-exporter">
  68   <title>Adding a new exporter</title>
  69
  70   <para>
  71    To add a new exporter, it has to be packaged first (see
  72    <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for
  73    examples), then a module can be added. The postfix exporter is used in this
  74    example:
  75   </para>
  76
  77   <itemizedlist>
  78    <listitem>
  79     <para>
  80      Some default options for all exporters are provided by
  81      <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
  82     </para>
  83    </listitem>
  84    <listitem override='none'>
  85     <itemizedlist>
  86      <listitem>
  87       <para>
  88        <literal>enable</literal>
  89       </para>
  90      </listitem>
  91      <listitem>
  92       <para>
  93        <literal>port</literal>
  94       </para>
  95      </listitem>
  96      <listitem>
  97       <para>
  98        <literal>listenAddress</literal>
  99       </para>
 100      </listitem>
 101      <listitem>
 102       <para>
 103        <literal>extraFlags</literal>
 104       </para>
 105      </listitem>
 106      <listitem>
 107       <para>
 108        <literal>openFirewall</literal>
 109       </para>
 110      </listitem>
 111      <listitem>
 112       <para>
 113        <literal>firewallFilter</literal>
 114       </para>
 115      </listitem>
 116      <listitem>
 117       <para>
 118        <literal>user</literal>
 119       </para>
 120      </listitem>
 121      <listitem>
 122       <para>
 123        <literal>group</literal>
 124       </para>
 125      </listitem>
 126     </itemizedlist>
 127    </listitem>
 128    <listitem>
 129     <para>
 130      As there is already a package available, the module can now be added. This
 131      is accomplished by adding a new file to the
 132      <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal>
 133      directory, which will be called postfix.nix and contains all exporter
 134      specific options and configuration:
 135 <programlisting>
 136 # nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix
 137 { config, lib, pkgs, options }:
 138
 139 with lib;
 140
 141 let
 142   # for convenience we define cfg here
 143   cfg = config.services.prometheus.exporters.postfix;
 144 in
 145 {
 146   port = 9154; # The postfix exporter listens on this port by default
 147
 148   # `extraOpts` is an attribute set which contains additional options
 149   # (and optional overrides for default options).
 150   # Note that this attribute is optional.
 151   extraOpts = {
 152     telemetryPath = mkOption {
 153       type = types.str;
 154       default = "/metrics";
 155       description = ''
 156         Path under which to expose metrics.
 157       '';
 158     };
 159     logfilePath = mkOption {
 160       type = types.path;
 161       default = /var/log/postfix_exporter_input.log;
 162       example = /var/log/mail.log;
 163       description = ''
 164         Path where Postfix writes log entries.
 165         This file will be truncated by this exporter!
 166       '';
 167     };
 168     showqPath = mkOption {
 169       type = types.path;
 170       default = /var/spool/postfix/public/showq;
 171       example = /var/lib/postfix/queue/public/showq;
 172       description = ''
 173         Path at which Postfix places its showq socket.
 174       '';
 175     };
 176   };
 177
 178   # `serviceOpts` is an attribute set which contains configuration
 179   # for the exporter's systemd service. One of
 180   # `serviceOpts.script` and `serviceOpts.serviceConfig.ExecStart`
 181   # has to be specified here. This will be merged with the default
 182   # service confiuration.
 183   # Note that by default 'DynamicUser' is 'true'.
 184   serviceOpts = {
 185     serviceConfig = {
 186       DynamicUser = false;
 187       ExecStart = ''
 188         ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \
 189           --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
 190           --web.telemetry-path ${cfg.telemetryPath} \
 191           ${concatStringsSep " \\\n  " cfg.extraFlags}
 192       '';
 193     };
 194   };
 195 }
 196 </programlisting>
 197     </para>
 198    </listitem>
 199    <listitem>
 200     <para>
 201      This should already be enough for the postfix exporter. Additionally one
 202      could now add assertions and conditional default values. This can be done
 203      in the 'meta-module' that combines all exporter definitions and generates
 204      the submodules:
 205      <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
 206     </para>
 207    </listitem>
 208   </itemizedlist>
 209  </section>
 210  <section xml:id="module-services-prometheus-exporters-update-exporter-module">
 211   <title>Updating an exporter module</title>
 212    <para>
 213      Should an exporter option change at some point, it is possible to add
 214      information about the change to the exporter definition similar to
 215      <literal>nixpkgs/nixos/modules/rename.nix</literal>:
 216 <programlisting>
 217 { config, lib, pkgs, options }:
 218
 219 with lib;
 220
 221 let
 222   cfg = config.services.prometheus.exporters.nginx;
 223 in
 224 {
 225   port = 9113;
 226   extraOpts = {
 227     # additional module options
 228     # ...
 229   };
 230   serviceOpts = {
 231     # service configuration
 232     # ...
 233   };
 234   imports = [
 235     # 'services.prometheus.exporters.nginx.telemetryEndpoint' -> 'services.prometheus.exporters.nginx.telemetryPath'
 236     (mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ])
 237
 238     # removed option 'services.prometheus.exporters.nginx.insecure'
 239     (mkRemovedOptionModule [ "insecure" ] ''
 240       This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true.
 241     '')
 242     ({ options.warnings = options.warnings; })
 243   ];
 244 }
 245 </programlisting>
 246     </para>
 247   </section>
 248 </chapter>