NAME

WebService::Rollbar::Notifier - send messages to www.rollbar.com service

SYNOPSIS

use WebService::Rollbar::Notifier;

my $roll = WebService::Rollbar::Notifier->new(
    access_token => 'YOUR_post_server_item_ACCESS_TOKEN',
);

$roll->debug("Testing example stuff!",
    # this is some optional, abitrary data we're sending
    { foo => 'bar',
        caller => scalar(caller()),
        meow => {
            mew => {
                bars => [qw/1 2 3 4 5 /],
            },
    },
});

DESCRIPTION

This Perl module allows for blocking and non-blocking way to send messages to www.rollbar.com service.

HTTPS ON SOLARIS

Note, this module will use HTTPS on anything but Solaris, where it will switch to use plain HTTP. Based on CPAN Testers, the module fails with HTTPS there, but since I don't have a Solaris box, I did not bother investigating this fully. Patches are more than welcome.

METHODS

->new()

my $roll = WebService::Rollbar::Notifier->new(
    access_token => 'YOUR_post_server_item_ACCESS_TOKEN',

    # all these are optional; defaults shown:
    environment     => 'production',
    code_version    => undef,
    framework       => undef,
    server          => undef,
    callback        => sub {},
);

Creates and returns new WebService::Rollbar::Notifier object. Takes arguments as key/value pairs:

access_token

my $roll = WebService::Rollbar::Notifier->new(
    access_token => 'YOUR_post_server_item_ACCESS_TOKEN',
);

Mandatory. This is your post_server_item project access token.

environment

my $roll = WebService::Rollbar::Notifier->new(
    ...
    environment     => 'production',
);

Optional. Takes a string up to 255 characters long. Specifies the environment we're messaging from. Defaults to production.

code_version

my $roll = WebService::Rollbar::Notifier->new(
    ...
    code_version    => undef,
);

Optional. By default is not specified. Takes a string up to 40 characters long. Describes the version of the application code. Rollbar understands these formats: semantic version (e.g. 2.1.12), integer (e.g. 45), git SHA (e.g. 3da541559918a808c2402bba5012f6c60b27661c).

framework

my $roll = WebService::Rollbar::Notifier->new(
    ...
    framework    => undef,
);

Optional. By default is not specified. The name of the framework your code uses

server

my $roll = WebService::Rollbar::Notifier->new(
    ...
    server    => {
        # Rollbar claims to understand following keys:
        host    => "server_name",
        root    => "/path/to/app/root/dir",
        branch  => "branch_name",
        code_version => "b6437f45b7bbbb15f5eddc2eace4c71a8625da8c",
    }
);

Optional. By default is not specified. Takes a hashref, which is used as "server" part of every Rollbar request made by this notifier instance. See https://rollbar.com/docs/api/items_post/ for detailed description of supported fields.

callback

# do nothing in the callback; this is default
my $roll = WebService::Rollbar::Notifier->new(
    ...
    callback => sub {},
);

# perform a blocking call
my $roll = WebService::Rollbar::Notifier->new(
    ...
    callback => undef,
);

# non-blocking; do something usefull in the callback
my $roll = WebService::Rollbar::Notifier->new(
    ...
    callback => sub {
        my ( $ua, $tx ) = @_;
        say $tx->res->body;
    },
);

Optional. Takes undef or a subref as a value. Defaults to a null subref. If set to undef, notifications to www.rollbar.com will be blocking, otherwise non-blocking, with the callback subref called after a request completes. The subref will receive in its @_ the Mojo::UserAgent object that performed the call and Mojo::Transaction::HTTP object with the response.

->notify()

$roll->notify('debug', "Message to send", {
    any      => 'custom',
    optional => 'data',
    to       => [qw/send goes here/],
});

# if we're doing blocking calls, then return value will be
# the response JSON

use Data::Dumper;;
$roll->callback(undef);
my $response = $roll->notify('debug', "Message to send");
say Dumper( $response->res->json );

Takes two mandatory and one optional arguments. Always returns true value if we're making non-blocking calls (see callback argument to constructor). Otherwise, returns the response as Mojo::Transaction::HTTP object. The arguments are:

First argument

$roll->notify('debug', ...

Mandatory. Specifies the type of message to send. Valid values are critical, error, warning, info, and debug. The module provides shorthand methods with those names to call notify.

Second argument

$roll->notify(..., "Message to send",

Mandatory. Takes a string that specifies the message to send to www.rollbar.com.

Third argument

$roll->notify(
    ...,
    ..., {
    any      => 'custom',
    optional => 'data',
    to       => [qw/send goes here/],
});

Optional. Takes a hashref that will be converted to JSON and sent along with the notification's message.

->critical()

$roll->critical( ... );

# same as

$roll->notify( 'critical', ... );

->error()

$roll->error( ... );

# same as

$roll->notify( 'error', ... );

->warning()

$roll->warning( ... );

# same as

$roll->notify( 'warning', ... );

->info()

$roll->info( ... );

# same as

$roll->notify( 'info', ... );

->debug()

$roll->debug( ... );

# same as

$roll->notify( 'debug', ... );

$roll->report_message("Message to send");

$roll->report_message(["Message to send", { some_key => "value" });

$roll->report_message("Message to send", { context => "controller#action" });

$roll->report_trace("MyException", $frames);
$roll->report_trace("MyException", "Total failure in module X", $frames);
$roll->report_trace("MyException", "Total failure in module X", "Description", $frames);

ACCESSORS/MODIFIERS

->access_token()

say 'Access token is ' . $roll->access_token;
$roll->access_token('YOUR_post_server_item_ACCESS_TOKEN');

Getter/setter for access_token argument to ->new().

->code_version()

say 'Code version is ' . $roll->code_version;
$roll->code_version('1.42');

Getter/setter for code_version argument to ->new().

->environment()

say 'Current environment is ' . $roll->environment;
$roll->environment('1.42');

Getter/setter for environment argument to ->new().

->callback()

$roll->callback->(); # call current callback
$roll->callback( sub { say "Foo!"; } );

Getter/setter for callback argument to ->new().

SEE ALSO

Rollbar API docs: https://rollbar.com/docs/api/items_post/

REPOSITORY

BUGS

AUTHOR

ZOFFIX

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.