diff options
author | WilliButz <wbutz@cyberfnord.de> | 2018-03-14 15:59:28 +0100 |
---|---|---|
committer | WilliButz <wbutz@cyberfnord.de> | 2018-03-22 14:52:23 +0100 |
commit | c54aa1f2939afeb5d8e32a6f1bba387f6b79ffc2 (patch) | |
tree | 35c935c9954e83557e829be64bc87dcd5786b56f /nixos | |
parent | 8a1310122679b1d646a2c753e869f448f6b99796 (diff) |
nixos/prometheus-exporters: add postfix exporter & documentation
Diffstat (limited to 'nixos')
3 files changed, 184 insertions, 0 deletions
diff --git a/nixos/modules/services/monitoring/prometheus/exporters.nix b/nixos/modules/services/monitoring/prometheus/exporters.nix index 4315194ed325f..8d6ca1e40a19b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters.nix @@ -25,6 +25,7 @@ let minio = import ./exporters/minio.nix { inherit config lib pkgs; }; nginx = import ./exporters/nginx.nix { inherit config lib pkgs; }; node = import ./exporters/node.nix { inherit config lib pkgs; }; + postfix = import ./exporters/postfix.nix { inherit config lib pkgs; }; snmp = import ./exporters/snmp.nix { inherit config lib pkgs; }; unifi = import ./exporters/unifi.nix { inherit config lib pkgs; }; varnish = import ./exporters/varnish.nix { inherit config lib pkgs; }; @@ -166,4 +167,6 @@ in conf = cfg.${name}; }) exporterOpts) ); + + meta.doc = ./exporters.xml; } diff --git a/nixos/modules/services/monitoring/prometheus/exporters.xml b/nixos/modules/services/monitoring/prometheus/exporters.xml new file mode 100644 index 0000000000000..4f0bcb2981067 --- /dev/null +++ b/nixos/modules/services/monitoring/prometheus/exporters.xml @@ -0,0 +1,135 @@ +<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> diff --git a/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix b/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix new file mode 100644 index 0000000000000..1e909aa27d833 --- /dev/null +++ b/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix @@ -0,0 +1,46 @@ +{ config, lib, pkgs }: + +with lib; + +let + cfg = config.services.prometheus.exporters.postfix; +in +{ + port = 9154; + 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 where Postfix places it's showq socket. + ''; + }; + }; + 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} + ''; + }; + }; +} |