2018-03-14 15:59:28 +01:00
<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>
2018-09-01 22:15:29 +02:00
<section xml:id= "module-services-prometheus-exporters-configuration" > <title > Configuration</title>
2018-03-14 15:59:28 +01:00
<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>
2018-09-01 22:15:29 +02:00
<section xml:id= "module-services-prometheus-exporters-new-exporter" > <title > Adding a new exporter</title>
2018-03-14 15:59:28 +01:00
<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>