NAME

Sentry::Raven - A perl sentry client

VERSION

Version 0.03

SYNOPSIS

  my $raven = Sentry::Raven->new( sentry_dsn => 'http://<publickey>:<secretkey>@app.getsentry.com/<projectid>' );

  # capture all errors
  $raven->capture_errors( sub {
      ..do something here..
  } );

  # capture an individual event
  $raven->capture_message('The sky is falling');

  # annotate an event with context
  $raven->capture_message(
    'The sky is falling',
    Sentry::Raven->exception_context('SkyException', 'falling'),
  );

DESCRIPTION

This module implements the recommended raven interface for posting events to a sentry service.

CONSTRUCTOR

my $raven = Sentry::Raven->new( %options, %context )

Create a new sentry interface object. It accepts the following named options:

sentry_dsn => 'http://<publickey>:<secretkey>@app.getsentry.com/<projectid>'

The DSN for your sentry service. Get this from the client configuration page for your project.

timeout => 5

Do not wait longer than this number of seconds when attempting to send an event.

ERROR HANDLERS

These methods are designed to capture events and handle them automatically.

$raven->capture_errors( $subref, %context )

Execute the $subref and report any exceptions (die) back to the sentry service. This automatically includes a stacktrace. This requires $SIG{__DIE__} so be careful not to override it in subsequent code or error reporting will be impacted.

METHODS

These methods are for generating individual events.

$raven->capture_message( $message, %context )

Post a string message to the sentry service. Returns the event id.

$raven->capture_exception( $exception_value, %exception_context, %context )

Post an exception type and value to the sentry service. Returns the event id.

%exception_context can contain:

type => $type

$raven->capture_request( $url, %request_context, %context )

Post a web url request to the sentry service. Returns the event id.

%request_context can contain:

method => 'GET'

data => { $key => $value }

query_string => 'foo=bar'

cookies => 'foo=bar'

headers => { 'Content-Type' => 'text/html' }

env => { REMOTE_ADDR => '192.168.0.1' }

$raven->capture_stacktrace( $frames, %context )

Post a stacktrace to the sentry service. Returns the event id.

$frames is an arrayref of hashrefs with each hashref representing a single frame.

    my $frames = [
        {
            filename => 'my/file1.pl',
            function => 'function1',
            vars     => { foo => 'bar' },
            lineno   => 10,
        },
        {
            filename => 'my/file2.pl',
            function => 'function2',
            vars     => { bar => 'baz' },
            lineno   => 20,
        },
    ];

The first frame should be the oldest frame. Frames must contain at least one of filename, function, or module. These additional attributes are also supported:

filename => $file_name

function => $function_name

module => $module_name

lineno => $line_number

colno => $column_number

abs_path => $absolute_path_file_name

context_line => $line_of_code

pre_context => [ $previous_line1, $previous_line2 ]

post_context => [ $next_line1, $next_line2 ]

in_app => $one_if_not_external_library

vars => { $variable_name => $variable_value }

$raven->capture_user( %user_context, %context )

Post a user to the sentry service. Returns the event id.

%user_context can contain:

id => $unique_id'

username => $username'

email => $email'

$raven->capture_query( $query, %query_context, %context )

Post a query to the sentry service. Returns the event id.

%query_context can contain:

engine => $engine'

EVENT CONTEXT

These methods are for annotating events with additional context, such as stack traces or HTTP requests. Simply pass their output to any other method accepting %context. They accept all of the same arguments as their capture_* counterparts.

  $raven->capture_message(
    'The sky is falling',
    Sentry::Raven->exception_context('falling', type => 'SkyException'),
  );

Sentry::Raven->exception_context( $value, %exception_context )

Sentry::Raven->request_context( $url, %request_context )

Sentry::Raven->stacktrace_context( $frames )

Sentry::Raven->user_context( %user_context )

Sentry::Raven->query_context( $query, %query_context )

The default context can be modified with the following accessors:

my %context = $raven->get_context();

$raven->add_context( %context )

$raven->clear_context()

STANDARD OPTIONS

These options can be passed to all methods accepting %context. Passing context to the constructor overrides defaults.

culprit => 'Some::Software'

The source of the event. Defaults to undef.

event_id => '534188f7c1ff4ff280c2e1206c9e0548'

The unique identifier string for an event, usually UUID v4. Max 32 characters. Defaults to a new unique UUID for each event. Invalid ids may be discarded silently.

extra => { key1 => 'val1', ... }

Arbitrary key value pairs with extra information about an event. Defaults to {}.

level => 'error'

Event level of an event. Acceptable values are fatal, error, warning, info, and debug. Defaults to error.

logger => 'root'

The creator of an event. Defaults to 'root'.

platform => 'perl'

The platform (language) in which an event occurred. Defaults to perl.

server_name => 'localhost.example.com'

The hostname on which an event occurred. Defaults to the system hostname.

tags => { key1 => 'val1, ... }

Arbitrary key value pairs with tags for categorizing an event. Defaults to {}.

timestamp => '1970-01-01T00:00:00'

Timestamp of an event. ISO 8601 format. Defaults to the current time. Invalid values may be discarded silently.

CONFIGURATION AND ENVIRONMENT

SENTRY_DSN=http://<publickey>:<secretkey>@app.getsentry.com/<projectid>

A default DSN to be used if sentry_dsn is not passed to c<new>.

LICENSE

Copyright (C) 2014 by Rentrak Corporation

The full text of this license can be found in the LICENSE file included with this module.

cpanm Sentry::Raven

perl -MCPAN -e shell
install Sentry::Raven