/ 
Log-Fine-0.65
River stage zero No dependents
/ Log::Fine::Handle::Email

NAME

Log::Fine::Handle::Email - Email log messages to one or more addresses

SYNOPSIS

Provides messaging to one or more email addresses.

use Email::Sender::Simple qw(sendmail);
use Email::Sender::Transport::SMTP qw();
use Log::Fine;
use Log::Fine::Handle::Email;
use Log::Fine::Levels::Syslog;

# Get a new logger
my $log = Log::Fine->logger("foo");

# Create a formatter object for subject line
my $subjfmt = Log::Fine::Formatter::Template
    ->new( name     => 'template1',
           template => "%%LEVEL%% : The angels have my blue box" );

# Create a formatted msg template
my $msgtmpl = <<EOF;
The program, $0, has encountered the following error condition:

%%MSG%% at %%TIME%%

Contact Operations at 1-800-555-5555 immediately!
EOF

my $bodyfmt = Log::Fine::Formatter::Template
    ->new( name     => 'template2',
           template => $msgtmpl );

# Create an Email Handle
my $handle = Log::Fine::Handle::Email
    ->new( name => 'email0',
           mask => LOGMASK_EMERG | LOGMASK_ALERT | LOGMASK_CRIT,
           subject_formatter => $subjfmt,
           body_formatter    => $bodyfmt,
           header_from       => "alerts@example.com",
           header_to         => [ "critical_alerts@example.com" ],
           envelope          =>
             { to   => [ "critical_alerts@example.com" ],
               from => "alerts@example.com",
               transport =>
                 Email::Sender::Transport::SMTP->new({ host => 'smtp.example.com' }),
             }
         );

# Register the handle
$log->registerHandle($handle);

# Log something
$log->log(CRIT, "Beware the weeping angels");

DESCRIPTION

Log::Fine::Handle::Email provides formatted message delivery to one or more email addresses. The intended use is for programs that need to alert a user in the event of a critical condition. Conceivably, the destination address could be a pager or cell phone.

Implementation Details

Log::Fine::Handle::Email uses the Email::Sender framework for delivery of emails. Users who wish to use Log::Fine::Handle::Email are strongly encouraged to read the following documentation:

Be especially mindful of the following environment variables as they will take precedence when defining a transport:

  • EMAIL_SENDER_TRANSPORT

  • EMAIL_SENDER_TRANSPORT_host

  • EMAIL_SENDER_TRANSPORT_port

See Email::Sender::Manual::Quickstart for further details.

Email Address Validation

Log::Fine::Handle::Email will validate each email addresses prior to use. Upon initilization, L::F::H::E will search for and use the following email address validation modules in the following order of preference:

Should neither Mail::RFC822::Address nor Email::Valid be found, then a default regex will be used which should work for most instances. See CAVEATS for special considerations.

Constructor Parameters

The following parameters can be passed to Log::Fine::Handle::Email->new();

  • name

    [optional] Name of this object (see Log::Fine). Will be auto-set if not specified.

  • mask

    Mask to set the handle to (see Log::Fine::Handle)

  • subject_formatter

    A Log::Fine::Formatter object. Will be used to format the Email Subject Line.

  • body_formatter

    A Log::Fine::Formatter object. Will be used to format the body of the message.

  • header_from

    String containing text to be placed in "From" header of generated email.

  • header_to

    String containing text to be placed in "To" header of generated email. Optionally, this can be an array ref containing multiple addresses

  • envelope

    [optional] hash ref containing envelope information for email:

    + to

    array ref containing one or more destination addresses

    + from

    String containing email sender

    + transport

    An Email::Sender::Transport object. See Email::Sender::Manual for further details.

METHODS

msgWrite

Sends given message via Email::Sender module. Note that "_error" in Log::Fine will be called should there be a failure of delivery.

See "msgWrite" in Log::Fine::Handle

CAVEATS

Note that the Email::Valid module does not use the same checking algorithms as Mail::RFC822::Address. Email addresses considered valid under one module may not be considered valid under the other. For example, under Mail::RFC822::Address, jsmith@localhost is considered a valid address while Email::Valid will reject it. Consider researching each module prior to making a determination as to which is acceptable for your environment and needs.

BUGS

Please report any bugs or feature requests to bug-log-fine at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-Fine. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Log::Fine

You can also look for information at:

AUTHOR

Christopher M. Fuhrman, <cfuhrman at pobox.com>

SEE ALSO

perl, Log::Fine, Log::Fine::Handle

COPYRIGHT & LICENSE

Copyright (c) 2011-2013 Christopher M. Fuhrman, All rights reserved.

This program is free software licensed under the...

The BSD License

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