The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

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', ... );

Methods listed below are experimental and might change in future!

->report_message($message, $additional_parameters)

Sends "message" type event to Rollbar.

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

Parameters:

$message

Mandatory. Specifies message text to be sent.

In addition to text your message can contain additional custom metadata fields. In this case $message must be an arrayref, where first element is message text and second is hashref with metadata.

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

$additional_parameters

Optional. Takes a hashref which may contain any additional top-level fields that you want to send with your message. Full list of fields supported by Rollbar is available at https://rollbar.com/docs/api/items_post/.

Notable useful field is level which can be used to set severity of your message. Default level is "error". See ->notify() for list of supported levels. Other example fields supported by Rollbar include: context, request, person, server.

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

->report_trace($exception_class,..., $frames, $additional_parameters

Reports "trace" type event to Rollbar, which is basically an exception.

$exception_class

Mandatory. This is exception class name (string).

It can be followed by 0 to 2 additional scalar parameters, which are interpreted as exception message and exception description accordingly.

$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);

$frames

Mandatory. Contains frames from stacktrace. It can be either Devel::StackTrace object (in which case we extract frames from this object) or arrayref with frames in Rollbar format (described in https://rollbar.com/docs/api/items_post/)

$additional_parameters

Optional. See "$additional_parameters" for details. Note that for exceptions default level is "error".

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

Fork this module on GitHub: https://github.com/zoffixznet/WebService-Rollbar-Notifier

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/WebService-Rollbar-Notifier/issues

If you can't access GitHub, you can email your request to bug-webservice-rollbar-notifier at rt.cpan.org

AUTHOR

ZOFFIX 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.