diff --git a/nixos/modules/services/monitoring/prometheus/exporters.md b/nixos/modules/services/monitoring/prometheus/exporters.md new file mode 100644 index 000000000000..c085e46d20d7 --- /dev/null +++ b/nixos/modules/services/monitoring/prometheus/exporters.md @@ -0,0 +1,180 @@ +# Prometheus exporters {#module-services-prometheus-exporters} + +Prometheus exporters provide metrics for the +[prometheus monitoring system](https://prometheus.io). + +## Configuration {#module-services-prometheus-exporters-configuration} + +One of the most common exporters is the +[node exporter](https://github.com/prometheus/node_exporter), +it provides hardware and OS metrics from the host it's +running on. The exporter could be configured as follows: +``` + services.prometheus.exporters.node = { + enable = true; + port = 9100; + enabledCollectors = [ + "logind" + "systemd" + ]; + disabledCollectors = [ + "textfile" + ]; + openFirewall = true; + firewallFilter = "-i br0 -p tcp -m tcp --dport 9100"; + }; +``` +It should now serve all metrics from the collectors that are explicitly +enabled and the ones that are +[enabled by default](https://github.com/prometheus/node_exporter#enabled-by-default), +via http under `/metrics`. In this +example the firewall should just allow incoming connections to the +exporter's port on the bridge interface `br0` (this would +have to be configured separately of course). For more information about +configuration see `man configuration.nix` or search through +the [available options](https://nixos.org/nixos/options.html#prometheus.exporters). + +Prometheus can now be configured to consume the metrics produced by the exporter: +``` + services.prometheus = { + # ... + + scrapeConfigs = [ + { + job_name = "node"; + static_configs = [{ + targets = [ "localhost:${toString config.services.prometheus.exporters.node.port}" ]; + }]; + } + ]; + + # ... + } +``` + +## Adding a new exporter {#module-services-prometheus-exporters-new-exporter} + +To add a new exporter, it has to be packaged first (see +`nixpkgs/pkgs/servers/monitoring/prometheus/` for +examples), then a module can be added. The postfix exporter is used in this +example: + + - Some default options for all exporters are provided by + `nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix`: + + - `enable` + - `port` + - `listenAddress` + - `extraFlags` + - `openFirewall` + - `firewallFilter` + - `user` + - `group` + - As there is already a package available, the module can now be added. This + is accomplished by adding a new file to the + `nixos/modules/services/monitoring/prometheus/exporters/` + directory, which will be called postfix.nix and contains all exporter + specific options and configuration: + ``` + # 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 = "/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 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 " \\\n " cfg.extraFlags} + ''; + }; + }; + } + ``` + - 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: + `nixpkgs/nixos/modules/services/prometheus/exporters.nix` + +## Updating an exporter module {#module-services-prometheus-exporters-update-exporter-module} + +Should an exporter option change at some point, it is possible to add +information about the change to the exporter definition similar to +`nixpkgs/nixos/modules/rename.nix`: +``` +{ 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' -> 'services.prometheus.exporters.nginx.telemetryPath' + (mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ]) + + # removed option 'services.prometheus.exporters.nginx.insecure' + (mkRemovedOptionModule [ "insecure" ] '' + This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true. + '') + ({ options.warnings = options.warnings; }) + ]; +} +``` diff --git a/nixos/modules/services/monitoring/prometheus/exporters.nix b/nixos/modules/services/monitoring/prometheus/exporters.nix index f3fbfb149ad7..e14eb51e7047 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters.nix @@ -323,6 +323,8 @@ in ); meta = { + # Don't edit the docbook xml directly, edit the md and generate it: + # `pandoc exporters.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > exporters.xml` doc = ./exporters.xml; maintainers = [ maintainers.willibutz ]; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters.xml b/nixos/modules/services/monitoring/prometheus/exporters.xml index e922e1ace8d0..066903a81b3c 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters.xml +++ b/nixos/modules/services/monitoring/prometheus/exporters.xml @@ -1,138 +1,133 @@ - - Prometheus exporters - - Prometheus exporters provide metrics for the - prometheus monitoring system. - -
- Configuration - + + Prometheus exporters - One of the most common exporters is the - node - exporter, it provides hardware and OS metrics from the host it's - running on. The exporter could be configured as follows: - + Prometheus exporters provide metrics for the + prometheus monitoring + system. + +
+ Configuration + + One of the most common exporters is the + node + exporter, it provides hardware and OS metrics from the host + it's running on. The exporter could be configured as follows: + + services.prometheus.exporters.node = { enable = true; port = 9100; enabledCollectors = [ - "logind" - "systemd" + "logind" + "systemd" ]; disabledCollectors = [ - "textfile" + "textfile" ]; openFirewall = true; - firewallFilter = "-i br0 -p tcp -m tcp --dport 9100"; + firewallFilter = "-i br0 -p tcp -m tcp --dport 9100"; }; - It should now serve all metrics from the collectors that are explicitly - enabled and the ones that are - enabled - by default, via http under /metrics. In this - example the firewall should just allow incoming connections to the - exporter's port on the bridge interface br0 (this would - have to be configured separately of course). For more information about - configuration see man configuration.nix or search through - the - available - options. - - - - Prometheus can now be configured to consume the metrics produced by the exporter: + + It should now serve all metrics from the collectors that are + explicitly enabled and the ones that are + enabled + by default, via http under /metrics. In + this example the firewall should just allow incoming connections + to the exporter's port on the bridge interface + br0 (this would have to be configured + separately of course). For more information about configuration + see man configuration.nix or search through the + available + options. + + + Prometheus can now be configured to consume the metrics produced + by the exporter: + services.prometheus = { # ... scrapeConfigs = [ { - job_name = "node"; + job_name = "node"; static_configs = [{ - targets = [ "localhost:${toString config.services.prometheus.exporters.node.port}" ]; + targets = [ "localhost:${toString config.services.prometheus.exporters.node.port}" ]; }]; } ]; # ... } - - -
-
- Adding a new exporter - - - To add a new exporter, it has to be packaged first (see - nixpkgs/pkgs/servers/monitoring/prometheus/ for - examples), then a module can be added. The postfix exporter is used in this - example: - - - - + +
+
+ Adding a new exporter - Some default options for all exporters are provided by - nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix: + To add a new exporter, it has to be packaged first (see + nixpkgs/pkgs/servers/monitoring/prometheus/ for + examples), then a module can be added. The postfix exporter is + used in this example: - - - - - enable - - - - - port - - - - - listenAddress - - - - - extraFlags - - - - - openFirewall - - - - - firewallFilter - - - - - user - - - - - group - - - - - - - As there is already a package available, the module can now be added. This - is accomplished by adding a new file to the - nixos/modules/services/monitoring/prometheus/exporters/ - directory, which will be called postfix.nix and contains all exporter - specific options and configuration: - + + + Some default options for all exporters are provided by + nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix: + + + + + enable + + + + + port + + + + + listenAddress + + + + + extraFlags + + + + + openFirewall + + + + + firewallFilter + + + + + user + + + + + group + + + + + + + As there is already a package available, the module can now be + added. This is accomplished by adding a new file to the + nixos/modules/services/monitoring/prometheus/exporters/ + directory, which will be called postfix.nix and contains all + exporter specific options and configuration: + + # nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix { config, lib, pkgs, options }: @@ -151,7 +146,7 @@ in extraOpts = { telemetryPath = mkOption { type = types.str; - default = "/metrics"; + default = "/metrics"; description = '' Path under which to expose metrics. ''; @@ -188,32 +183,33 @@ in ${pkgs.prometheus-postfix-exporter}/bin/postfix_exporter \ --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \ --web.telemetry-path ${cfg.telemetryPath} \ - ${concatStringsSep " \\\n " cfg.extraFlags} + ${concatStringsSep " \\\n " cfg.extraFlags} ''; }; }; } - - - + + + + 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: + nixpkgs/nixos/modules/services/prometheus/exporters.nix + + + +
+
+ Updating an exporter module - 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: - nixpkgs/nixos/modules/services/prometheus/exporters.nix + Should an exporter option change at some point, it is possible to + add information about the change to the exporter definition + similar to nixpkgs/nixos/modules/rename.nix: - - -
-
- Updating an exporter module - - Should an exporter option change at some point, it is possible to add - information about the change to the exporter definition similar to - nixpkgs/nixos/modules/rename.nix: - + { config, lib, pkgs, options }: with lib; @@ -232,17 +228,16 @@ in # ... }; imports = [ - # 'services.prometheus.exporters.nginx.telemetryEndpoint' -> 'services.prometheus.exporters.nginx.telemetryPath' - (mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ]) + # 'services.prometheus.exporters.nginx.telemetryEndpoint' -> 'services.prometheus.exporters.nginx.telemetryPath' + (mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ]) # removed option 'services.prometheus.exporters.nginx.insecure' - (mkRemovedOptionModule [ "insecure" ] '' + (mkRemovedOptionModule [ "insecure" ] '' This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true. '') ({ options.warnings = options.warnings; }) ]; } -