NAME

Monitor::MetricsAPI::Collector - Metrics collection object

SYNOPSIS

You should not create your own objects from this module directly. All Collector objects should be instantiated through the Monitor::MetricsAPI module's create() method. Please refer to that module's documentation for information on setting up your application's usage of this library.

DESCRIPTION

METHODS

metric ($name)

Returns the Monitor::MetricsAPI::Metric object for the given name. Metric names are collapsed to a slash-delimited string, which mirrors the path used by the reporting HTTP server to display individual metrics. Thus, this:

    Monitor::MetricsAPI->new(
        metrics => {
            server => {
                version => {
                    major => 'string',
                    minor => 'string',
                }
            }
        }
    );

Creates two metrics:

1. server/version/major

2. server/version/minor

The metric object returned by this method may then be modified, according to its own methods documented in Monitor::MetricsAPI::Metric and the type-specific documentation, or its value may be accessed via the standard value() metric method.

Updating a metric:

    $collector->metric('users/total')->set($user_count);

Retrieving the current value of a metric:

    $collector->metric('users/total')->value;

add_metrics (\%metrics)

Accepts a hashref of hierarchical metric definitions (please see documentation in Monitor::MetricsAPI::Tutorial for a more complete description). Used to bulk-add metrics to a collector.

add_metric ($name, $type, $callback)

Allows for adding a new metric to the collector as your application is running, instead of having to define everything at startup.

If the metric already exists, this method will be a noop as long as all of the metric options match (i.e. the existing metric is of the same type as what you specified in add_metric()). If the metric already exists and you have specified options which do not match the existing ones, a warning will be emitted and no other actions will be taken.

Both $name and $type are required. If $type is 'callback' then a subroutine reference must be passed in for $callback. Refer to the documentation in Monitor::MetricsAPI::Metric for details on individual metric types.

add_server ($listen)

Adds a new HTTP server listener to the collector. The $listen argument must be a string in the form of "<address>:<port>" where address may be an asterisk to indicate all interfaces should be listened on, and where port (as well as the leading colon) may be omitted if you wish to use the default port of 8200.

Examples:

    $collector->add_server('*:8201');
    $collector->add_server('127.0.0.1:8202');
    $collector->add_server('192.168.1.1');

You may add as many servers as you like. If you attempt to bind to the same address and port combination more than once, a warning will be emitted and no action will be taken.

AUTHORS

Jon Sime <jonsime@gmail.com>

LICENSE AND COPYRIGHT

This software is copyright (c) 2015 by OmniTI Computer Consulting, Inc.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cpanm Monitor::MetricsAPI

perl -MCPAN -e shell
install Monitor::MetricsAPI