/ 
Unix-Statgrab-0.101
River stage one • 2 direct dependents • 3 total dependents
/ Unix::Statgrab

NAME

Unix::Statgrab - Perl extension for collecting information about the machine

SYNOPSIS

    use Unix::Statgrab;

    my $host_stats = get_host_info();
    print $host_stats->hostname . " is a " . $host_stats->bitwidth . " " . $host_stats->os_name . "\n";

    my $filesystems = get_fs_stats();
    my @mount_points = map { $filesystems->mnt_point($_) } (0 .. $filesystems->entries() - 1);
    print $host_stats->hostname . " has " . join( ", ", @mount_points ) . " mounted\n";

    my $proc_list = get_process_stats();
    my @proc_by_type;
    foreach my $proc_entry (0 .. $proc_list->entries() - 1) {
	$proc_by_type[$proc_list->state($proc_entry)]++;
    }
    my $total_procs = 0;
    $total_procs += $_ for grep { defined $_ } @proc_by_type;
    foreach my $state (qw(SG_PROCESS_STATE_RUNNING SG_PROCESS_STATE_SLEEPING
			  SG_PROCESS_STATE_STOPPED SG_PROCESS_STATE_ZOMBIE
					  SG_PROCESS_STATE_UNKNOWN)) {
	defined $proc_by_type[Unix::Statgrab->$state] or next;
	print $proc_by_type[Unix::Statgrab->$state] . " of " . $total_procs . " procs in $state\n";
    }

    my $last_cpu_stats = get_cpu_stats() or croak( get_error()->strperror() );
    do_sth_way_longer();
    my $cpu_diff = get_cpu_stats()->get_cpu_stats_diff($last_cpu_stats);

    my $last_cpu_percent = $last_cpu_percent->get_cpu_percents();
    my $diff_cpu_percent = $cpu_diff->get_cpu_percents();
    my $now_cpu_percent = get_cpu_stats()->get_cpu_percents();

DESCRIPTION

Unix::Statgrab is a wrapper for libstatgrab as available from http://www.i-scream.org/libstatgrab/. It is a reasonably portable attempt to query interesting stats about your computer. It covers information on the operating system, CPU, memory usage, network interfaces, hard-disks etc.

Each of the provided functions follow a simple rule: It never takes any argument and returns either an object (in case of success) or undef. In case undef was returned, check the return value of get_error. Also see "ERROR HANDLING" further below.

To avoid error during copying documentation, the original function documentation will be refererred where reasonable. Each returned object has a getter method named as the attribute in original documentation. Those getters take a optional index argument, asking for the attribute of the nth statistic item. Further, each object provides an entries() method, telling you how much statistics for requested type are returned (yes, even get_host_info() has that, maybe we have more host_info when grabbing that statistic in a cluster, grid or cloud). Additionally, for the users of Perl's list processing features, each object has an as_list() method which returns the statistic as list of hash items containing each attribute / value pair of available attributes.

METHODS of sg_*_stats

  • entries

    Provides the number of statistic objects in the returned collection.

  • as_list

    Provides a list containing each statistic entry as a hash with the attribute names as key and the statistic attribute as appropriate value.

  • systime

    Even if it's always an attribute (beside for cpu_percents), returns the seconds since epoch of the time when the statistics are snapshotted.

  • attribute(offset = 0)

    Returns the value of the queried attribute of the given entry of the statistics collection. If offset exceeds the range, undef is returned.

FUNCTIONS

drop_privileges()

Unix::Statgrab can be told to discard setuid and setgid privileges which is usually a good thing. If your program doesn't need the elevated privileges somewhere else, call it right after useing the module.

This function is depreciated and might be removed in a future version of libstatgrab (and then in Unix::Statgrab, too).

get_host_info()

Returns generic information about this machine. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_host_info.3.html|Unix::Statgrab::sg_host_info.

get_cpu_stats

Returns information about this machine's usage of the CPU. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_cpu_stats.3.html|Unix::Statgrab::sg_cpu_stats.

extra sg_cpu_stats methods

get_disk_io_stats

Delivers the disk IO per disk stored in the kernel which holds the amount of data transferred since bootup. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_disk_io_stats.3.html|Unix::Statgrab::sg_disk_io_stats.

extra sg_disk_io_stats methods

get_fs_stats

Returns statistics about the mounted filesystems. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_fs_stats.3.html|Unix::Statgrab::sg_fs_stats.

extra sg_fs_stats methods

get_load_stats

Returns the load average over various span of times. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_load_stats.3.html|Unix::Statgrab::sg_load_stats.

get_mem_stats

Returns statistics about memory usage. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_mem_stats.3.html|Unix::Statgrab::sg_mem_stats.

get_swap_stats

Returns statistics about swap usage. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_swap_stats.3.html|Unix::Statgrab::sg_swap_stats.

get_network_io_stats

Returns statistics about the network traffic per network interface as stored in the kernel. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_network_io_stats.3.html|Unix::Statgrab::sg_network_io_stats.

extra sg_network_io_stats methods

get_network_iface_stats

Returns statistics about each of the found network interfaces in your computer. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_network_iface_stats.3.html|Unix::Statgrab::sg_network_iface_stats.

get_page_stats

Returns the number of pages the system has paged in and out since bootup. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_page_stats.3.html|Unix::Statgrab::sg_page_stats.

extra sg_page_stats methods

get_process_stats

Returns loads of information about the current processes. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_process_stats.3.html|Unix::Statgrab::sg_process_stats.

get_user_stats

Returns session information about logged on users. The object it returns is a http://www.i-scream.org/libstatgrab/docs/sg_get_user_stats.3.html|Unix::Statgrab::sg_user_stats.

ERROR HANDLING

One function get_error exists that will return the last error encountered, if any. It's return value is an object of type http://www.i-scream.org/libstatgrab/docs/sg_get_error.3.html|Unix::Statgrab::sg_error_details.

extra sg_error_details methods

  • error_name

    Returns a textual representation for the error numeric value. The textual representation is delivered by the libstatgrab function sg_str_error.

  • strperror

    Returns a textual representation for the sg_error_details object. The textual representation is delivered by the libstatgrab function sg_strperror.

EXPORT

All by default. This means all of the above functions plus the following constants:

SG_ERROR_NONE
SG_ERROR_INVALID_ARGUMENT
SG_ERROR_ASPRINTF
SG_ERROR_SPRINTF
SG_ERROR_DEVICES
SG_ERROR_DEVSTAT_GETDEVS
SG_ERROR_DEVSTAT_SELECTDEVS
SG_ERROR_DISKINFO
SG_ERROR_ENOENT
SG_ERROR_GETIFADDRS
SG_ERROR_GETMNTINFO
SG_ERROR_GETPAGESIZE
SG_ERROR_HOST
SG_ERROR_KSTAT_DATA_LOOKUP
SG_ERROR_KSTAT_LOOKUP
SG_ERROR_KSTAT_OPEN
SG_ERROR_KSTAT_READ
SG_ERROR_KVM_GETSWAPINFO
SG_ERROR_KVM_OPENFILES
SG_ERROR_MALLOC
SG_ERROR_MEMSTATUS
SG_ERROR_OPEN
SG_ERROR_OPENDIR
SG_ERROR_READDIR
SG_ERROR_PARSE
SG_ERROR_PDHADD
SG_ERROR_PDHCOLLECT
SG_ERROR_PDHOPEN
SG_ERROR_PDHREAD
SG_ERROR_PERMISSION
SG_ERROR_PSTAT
SG_ERROR_SETEGID
SG_ERROR_SETEUID
SG_ERROR_SETMNTENT
SG_ERROR_SOCKET
SG_ERROR_SWAPCTL
SG_ERROR_SYSCONF
SG_ERROR_SYSCTL
SG_ERROR_SYSCTLBYNAME
SG_ERROR_SYSCTLNAMETOMIB
SG_ERROR_SYSINFO
SG_ERROR_MACHCALL
SG_ERROR_IOKIT
SG_ERROR_UNAME
SG_ERROR_UNSUPPORTED
SG_ERROR_XSW_VER_MISMATCH
SG_ERROR_GETMSG
SG_ERROR_PUTMSG
SG_ERROR_INITIALISATION
SG_ERROR_MUTEX_LOCK
SG_ERROR_MUTEX_UNLOCK

sg_unknown_configuration
sg_physical_host
sg_virtual_machine
sg_paravirtual_machine
sg_hardware_virtualized

sg_fs_unknown
sg_fs_regular
sg_fs_special
sg_fs_loopback
sg_fs_remote
sg_fs_local
sg_fs_alltypes

SG_IFACE_DUPLEX_FULL
SG_IFACE_DUPLEX_HALF
SG_IFACE_DUPLEX_UNKNOWN

SG_IFACE_DOWN
SG_IFACE_UP

SG_PROCESS_STATE_RUNNING
SG_PROCESS_STATE_SLEEPING
SG_PROCESS_STATE_STOPPED
SG_PROCESS_STATE_ZOMBIE
SG_PROCESS_STATE_UNKNOWN

If you don't want that, use the module thusly:

use Unix::Statgrab ();

or provide a list of those symbols you want:

    use Unix::Statgrab qw/get_network_iface_stats 
                          SG_IFACE_DUPLEX_FULL
			  SG_IFACE_DUPLEX_HALF
			  SG_IFACE_DUPLEX_UNKNOWN/;

SEE ALSO

The excellent and very complete manpage of statgrab(3). You can get additional information for each of the above functions by prefixing the function name with "sg_" and feed it to man:

man sg_get_network_iface_stats

libstatgrab's home is at http://www.i-scream.org/libstatgrab/

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Unix::Statgrab

You can also look for information at:

Where can I go for help?

If you have a bug report, a patch or a suggestion, please open a new report ticket at CPAN (but please check previous reports first in case your issue has already been addressed). You can mail any of the module maintainers, but you are more assured of an answer by posting to the dbi-users list or reporting the issue in RT.

Report tickets should contain a detailed description of the bug or enhancement request and at least an easily verifiable way of reproducing the issue or fix. Patches are always welcome, too.

Where can I go for help with a concrete version?

Bugs and feature requests are accepted against the latest version only. To get patches for earlier versions, you need to get an agreement with a developer of your choice - who may or not report the issue and a suggested fix upstream (depends on the license you have chosen).

Business support and maintenance

For business support you can contact Jens via his CPAN email address rehsackATcpan.org. Please keep in mind that business support is neither available for free nor are you eligible to receive any support based on the license distributed with this package.

AUTHOR

Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>

Jens Rehsack, <rehsack AT cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2004-2005 by Tassilo von Parseval

Copyright (C) 2012-2013 by Jens Rehsack

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.