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

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