The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Sentry-Raven-1.14
River stage one • 5 direct dependents • 5 total dependents
3 ++
/ Sentry::Raven

NAME

Sentry::Raven - A perl sentry client

VERSION

Version 1.14

SYNOPSIS

  my $raven = Sentry::Raven->new( sentry_dsn => 'https://<publickey>:<secretkey>@sentry.io/<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>@sentry.io/<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. If it is unable to submit an event (capture_message return undef), it will die and include the event details in the die message. This automatically includes a stacktrace unless $SIG{__DIE__} has been overridden in subsequent code.

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 => 'foo=bar'
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 can be either a Devel::StackTrace object, or 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
ip_address => $ip_address

$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->merge_tags( %tags )

Merge additional tags into any existing tags in the current context.

$raven->merge_extra( %tags )

Merge additional extra into any existing extra in the current context.

$raven->clear_context()

EVENT PROCESSORS

Processors are a mechanism for modifying events after they are generated but before they are posted to the sentry service. They are useful for scrubbing sensitive data, such as passwords, as well as adding additional context. If the processor fails (dies or returns undef), the failure will be passed to the caller.

See Sentry::Raven::Processor for information on creating new processors.

Available processors:

Sentry::Raven::Processor::RemoveStackVariables

$raven->add_processors( [ Sentry::Raven::Processor::RemoveStackVariables, ... ] )

$raven->clear_processors( [ Sentry::Raven::Processor::RemoveStackVariables, ... ] )

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.

release => 'ec899ea'

Track the release version of your application.

processors => [ Sentry::Raven::Processor::RemoveStackVariables, ... ]

A set or processors to be applied to events before they are posted. See Sentry::Raven::Processor for more information. This can only be set during construction and not on other methods accepting %context.

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 {}.

fingerprint => [ 'val1', 'val2', ... }

Array of strings used to control how events aggregate in the sentry web interface. The string '{{ default }}' has special meaning when used as the first value; it indicates that sentry should use the default aggregation method in addition to any others specified (useful for fine-grained aggregation). Defaults to ['{{ default }}'].

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

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

environment => 'production'

Specify the environment (i.e. staging, production, etc.) that your project is deployed in. More information can be found on the Sentry website.

CONFIGURATION AND ENVIRONMENT

SENTRY_DSN=http://<publickey>:<secretkey>@sentry.io/<projectid>

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

LICENSE

Copyright (C) 2019 by Matt Harrington

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