Repository
Munin (master)
Last change
2018-08-10
Graph Categories
Family
auto
Capabilities
Keywords
Language
Perl
License
GPL-2.0-only
Authors

df

Example graph: month

Name

df - Munin plugin to monitor disk or inode usage

Applicable Systems

Every Linux system with df installed.

Configuration

The plugin excludes per default the following special, read-only or dynamically allocating file systems from graphing:

none unknown rootfs iso9660 squashfs udf romfs ramfs debugfs cgroup_root

Additionally, when graphing inode usage, nilfs2 will be ignored as well.

To change this set the environment variable “exclude” with a list of space separated fs types. The environment variables “warning” and “critical” sets the percentage from which Munin starts to warn about the disk usage.

This configuration snipplet is an example with the defaults:

[df]
  env.exclude none unknown rootfs iso9660 squashfs udf romfs ramfs debugfs cgroup_root devtmpfs
  env.warning 92
  env.critical 98

Put it in a file in /etc/munin/plugin-conf.d/ and restart the munin-node.

You may specify filesystem specific warning and critical levels:

env._dev_sda2_warning 98
env._dev_sda2_critical 99

Devices can be explicitly included or excluded based on their mountpoint or device name using the include_re and exclude_re environment variables. These environment variables are parsed as whitespace separated regular expressions. For example, if you wish to ignore the filesystem on /dev/sda2 and all filesystems mounted under /var except /var/tmp, these rules would achieve this:

env.include_re ^/var/tmp$
env.exclude_re /dev/sda2 ^/var/

Please note that these expressions are tried against both mountpoints and device names, therefore broad matches could potentially filter out desired devices. Anchoring is also useful for avoiding false positives (as seen in the example), but not strictly necessary. Testing with munin-run is always a good idea.

Also note that a mountpoint that is excluded by filesystem type but included by RE will not be included.

By default, only local filesystems will be included. In case you want to monitor network filesystems too, you can set the commandline options for “df” manually in the configuration file. The default options are “-P -l”. For example, if you want to monitor a mounted GlusterFS, you can omit the “-l” parameter in the config file:

env.dfopts -P

Please note that this will also add other shares you’ve mounted on your computer (Samba/CIFS, etc). If you don’t want them, you can exclude them, using the “env.include/env.exclude” settings mentioned above.

Usage

Link this plugin to /etc/munin/plugins/ and restart the munin-node. If you want to monitor inode usage instead of disk usage, just link the plugin as df_inode.

Magic Markers

#%# family=auto
#%# capabilities=autoconf multigraph

Bugs

Uses device names instead of mount points to identify mounted filesystems.

Author

Copyright (C) 2013 Diego Elio Pettenò
Copyright (C) 2006 Ingvar Hagelund

License

GPLv2

Pod Errors

Hey! The above document had some coding errors, which are explained below:

  • Around line 92:

    Non-ASCII character seen before =encoding in ‘Pettenò’. Assuming UTF-8

#!/usr/bin/perl

use strict;
use warnings;

=head1 NAME

df - Munin plugin to monitor disk or inode usage

=head1 APPLICABLE SYSTEMS

Every Linux system with df installed.

=head1 CONFIGURATION

The plugin excludes per default the following special, read-only or
dynamically allocating file systems from graphing:

  none unknown rootfs iso9660 squashfs udf romfs ramfs debugfs cgroup_root

Additionally, when graphing inode usage, C<nilfs2> will be ignored as
well.

To change this set the environment variable "exclude" with a list of
space separated fs types.  The environment variables "warning" and
"critical" sets the percentage from which Munin starts to warn about
the disk usage.

This configuration snipplet is an example with the defaults:

  [df]
    env.exclude none unknown rootfs iso9660 squashfs udf romfs ramfs debugfs cgroup_root devtmpfs
    env.warning 92
    env.critical 98

Put it in a file in /etc/munin/plugin-conf.d/ and restart the munin-node.

You may specify filesystem specific warning and critical levels:

    env._dev_sda2_warning 98
    env._dev_sda2_critical 99

Devices can be explicitly included or excluded based on their mountpoint or
device name using the include_re and exclude_re environment variables.  These
environment variables are parsed as whitespace separated regular expressions.
For example, if you wish to ignore the filesystem on /dev/sda2 and all
filesystems mounted under /var except /var/tmp, these rules would achieve this:

    env.include_re ^/var/tmp$
    env.exclude_re /dev/sda2 ^/var/

Please note that these expressions are tried against both mountpoints and
device names, therefore broad matches could potentially filter out desired
devices.  Anchoring is also useful for avoiding false positives (as seen in the
example), but not strictly necessary.  Testing with munin-run is always a good
idea.

Also note that a mountpoint that is excluded by filesystem type but included by
RE will not be included.

By default, only local filesystems will be included. In case you want to
monitor network filesystems too, you can set the commandline options for "df"
manually in the configuration file. The default options are "-P -l".  For
example, if you want to monitor a mounted GlusterFS, you can omit the "-l"
parameter in the config file:

    env.dfopts -P

Please note that this will also add other shares you've mounted on your
computer (Samba/CIFS, etc). If you don't want them, you can exclude them, using
the "env.include/env.exclude" settings mentioned above.


=head1 USAGE

Link this plugin to /etc/munin/plugins/ and restart the
munin-node. If you want to monitor inode usage instead of disk usage,
just link the plugin as C<df_inode>.

=head1 MAGIC MARKERS

  #%# family=auto
  #%# capabilities=autoconf multigraph

=head1 BUGS

Uses device names instead of mount points to identify mounted
filesystems.

=head1 AUTHOR

  Copyright (C) 2013 Diego Elio Pettenò
  Copyright (C) 2006 Ingvar Hagelund

=head1 LICENSE

GPLv2

=cut

use Munin::Plugin;

need_multigraph();

# Reset locale to C
$ENV{LC_ALL} = 'C';

# For these devices use the mount point, the device is useless
my %usemntpt = ( tmpfs => 1, none => 1, udev => 1, simfs => 1 );

my @exclude = qw(none unknown rootfs iso9660 squashfs udf romfs ramfs debugfs cgroup_root devtmpfs);
my $dfopts  = $ENV{'dfopts'} || "-P -l";
$dfopts .= ' ';
my $title = "Disk usage";

if ( $Munin::Plugin::me eq "df_inode" ) {
  $title = "Inode usage";
  $dfopts .= "-i ";
  push(@exclude, 'nilfs2', 'reiserfs');
}

@exclude = split(/\s+/, $ENV{exclude}) if $ENV{exclude};

$dfopts .= join(' ', map { "-x" . $_ } @exclude);

my $mode = ($ARGV[0] or "print");

# Compile REs from env
my (@include_re, @exclude_re);
@include_re = map(qr/$_/, split(/\s+/, $ENV{include_re})) if ($ENV{include_re});
@exclude_re = map(qr/$_/, split(/\s+/, $ENV{exclude_re})) if ($ENV{exclude_re});


# Check for a given line of df's output, if it matches one item of 'include_re'
# (if given) and if it is not matched by one of the items of 'exclude_re'
# (if given). If all checks were successful, return an array reference for:
# fieldname, mountpoint, usage_percentage.
sub split_and_skip {
  my ($line) = @_;
  my ($name, $capacity, $mountpt);

  if ( m{
          ^           # beginning of line
          (.*\S)      # Filesystem
          \s+
          \d+         # 1024-blocks
          \s+
          \d+         # Used
          \s+
          \d+         # Available
          \s+
          (\d+)%      # Capacity
          \s+
          (/.*)       # Mounted on
          $           # end of line
        }smx
      ) {
    $name = $1;
    $capacity = $2;
    $mountpt = $3;
  } else {
    # this was the header line or we failed to parse a data line
    return;
  }

  return if $name eq 'Filesystem';

  # If "include_re" is non-empty, then we ignore all non-matching lines.
  if (scalar(@include_re) > 0) {
    my $item_found = 0;
    foreach my $re (@include_re) {
      if ($name =~ $re or $mountpt =~ $re) {
        $item_found = 1;
      }
    }
    if (not $item_found) {
      # "include_re" was given, but none of its entries matched - we give up on this line
      return;
    }
  }

  foreach my $re (@exclude_re) {
    return if ($name =~ $re or $mountpt =~ $re);
  }

  # For some virtual filesystems we use the mountpoint instead of the ambiguous device name.
  $name = $mountpt if $usemntpt{$name};

  return [clean_fieldname($name), $mountpt, $capacity];
}


# Assemble a filtered list of array references (each: fieldname, mountpoint, usage_percentage).
my @df_output = grep(defined($_), map(split_and_skip, split("\n", `df $dfopts 2>/dev/null`)));


if ($mode eq 'autoconf' ) {
  if ( scalar(@df_output) == 0) {
    print "no (no device to monitor)\n";
  } else {
    print "yes\n";
  }
  exit 0;
} elsif ($mode eq 'config' ) {
  print <<END;
multigraph df
graph_title $title in percent
graph_args --upper-limit 100 -l 0
graph_vlabel %
graph_scale no
graph_category disk
END

  # Summary graph
  print "min.label Lowest disk usage\n";
  print "max.label Highest disk usage\n";

  # Detailed graphs
  foreach my $df (@df_output) {
    my ($name, $mountpt, undef) = @{$df};
    print <<END;
multigraph df.$name
graph_title $title for $mountpt in percent
graph_args --upper-limit 100 -l 0
graph_vlabel %
graph_scale no
graph_category disk
df.label $mountpt
END
    print_thresholds("df", undef, undef, 92, 98);
  }

  unless ( ($ENV{MUNIN_CAP_DIRTYCONFIG} || 0) == 1 ) {
    exit 0;
  }
}

# Summary graph
# Find the smallest and the biggest usage percentage.
my $min, my $max;
foreach my $df (@df_output) {
  my (undef, undef, $percent) = @{$df};
  $min = $percent if not defined($min) or ($percent < $min);
  $max = $percent if not defined($max) or ($percent > $max);
}
$min = "U" if not defined($min);
$max = "U" if not defined($max);

# The overview graph contains only min/max of all filtered df entries.
print "multigraph df\n";
print "min.value ", $min, "\n";
print "max.value ", $max, "\n";

# Detailed graphs
foreach my $df (@df_output) {
  my ($name, undef, $percent) = @{$df};
  print "multigraph df.", $name, "\n";
  print "df.value ", $percent, "\n";
}