view release on metacpan or  search on metacpan

lib/Dancer2/Logger/Fluent.pm  view on Meta::CPAN

=head1 DESCRIPTION

Implements a structured event logger for Fluent via L<Fluent::Logger>.

When a connection to the C<fluentd> agent can't be established, messages
are "queued" internally. These messages will be flushed upon subsequent
calls to C<log()>, as soon as a connection is established.

=head1 METHODS

=head2 log($level, $message)

Writes the log message to Fluent.

=head1 CONFIGURATION

The setting B<logger> should be set to C<Fluent> in order to use this logging
engine in a Dancer2 application.

Below is a simple sample configuration:

  logger: "Fluent"

  engines:
    logger:
      Fluent:
        tag_prefix: "myapp"
        host: "127.0.0.1"
        port: 24224

The full list of allowed options are as follows:

=over 4

=item tag_prefix

Tag prepended to every message, defaults to the configured I<appname> or,
if not defined, to the executable's basename.

=item host

Host running the C<fluentd> agent, defaults to '127.0.0.1'.

=item port

Port listened by the C<fluentd> agent, defaults to 24224.

=item timeout

Timeout in seconds, defaults to 3.0 as implemented in
L<Fluent::Logger>.

=item socket

Socket file location, defaults to undef as implemented in
L<Fluent::Logger>.

=item prefer_integer

Whether integer is preferred as cascaded to
Data::MessagePack->prefer_integer.  Defaults to 1.

=item event_time

Whether event timestamps (includes nanoseconds as supported by
C<fluentd> >= 0.14.0) will be included. Defaults to 0.

=item buffer_limit

Buffer size limit, defaults to 8388608 (8MB) as implemented in
L<Fluent::Logger>.

=item buffer_overflow_handler

Custom coderef to handle buffer overflow in the event of connection
failure, to mitigate loss of data in the event of connection failure.

=item truncate_buffer_at_overflow

When I<truncate_buffer_at_overflow> is true and pending buffer size is
larger than I<buffer_limit>, pending buffer will still be kept but last
message will not be sent and will not be appended to the buffer.
Defaults to 0.

=back

=head1 MESSAGE FORMAT

Messages to C<fluentd> will be a hash containing the following:

  {
    env       => $environment,
    timestamp => $current_timestamp,
    host      => $hostname,
    level     => $level,
    message   => $message,
    pid       => $$
  }

=head1 AUTHOR

Arnold Tan Casis E<lt>atancasis@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright 2017- Arnold Tan Casis

=head1 LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 SEE ALSO

See L<Dancer2> for details about logging in route handlers.

See L<http://fluent.github.com> for details on C<fluentd> itself.

=cut