NAME

MojoX::Log::GELF - Non-blocking delivery of log messages in Graylog's GELF format

SYNOPSIS

my $log = MojoX::Log::GELF->new(
  host              => 'myserver.example.com',
  gelf_address      => 'logs.example.com',
  gelf_protocol     => 'udp',
  min_level         => 'info',
  additional_fields => {
    facility => 'MyApplication',
    version  => $VERSION,
  },
);

# Replace a Mojo app's default log, preserving the original logger
# and it's configuration
$app->log(MojoX::Log::GELF->new(
  mojo_log => $app->log,
));

# Log message using Log::Dispatch::Gelf style syntax
# attaching additional metadata
$log->log(
  message => 'The dev team is out of coffee!',
  level   => 'emerg',
  additional_fields => {
    brew_method    => 'french_press',
    cups_required  => 6 * 4,
    cups_available => 0,
  },
);
#

# Log message using Mojo::Log syntax
$log->debug('[context]', 'log message');

# Log message using Mojo::Log callback syntax
$log->debug(sub { expensive_sub_to_generate_log_message() });

DESCRIPTION

A drop-in replacement for Mojo::Log.

Delivers log messages over the network with the Graylog GELF protocol, alongside configurable Mojo::Log for console or file based logging.

Relies on Mojo::IOLoop for non blocking network sockets. When using this module, an event loop will be started if not already running.

EVENTS

MojoX::Log::GELF inherits all events from Mojo::EventEmitter and can emit the following new ones

error

$gelf->on(error => sub ($stream, $tx_error) {
  use Data::Printer;
  warn "oh no oh no tx error $tx_error fml";
});

Emitted upon a socket connection error, or a network communication error

log

$gelf->on(log => sub ($gelf, $log_arguments)) {
  $log_arguments->{message} .= ' (Hack The Planet!)';
});

Emitted upon calls to "log". Passed a reference to the log arguments. They may be modified by the event before continuing to be processed by "log".

METHODS

new( %args )

The constructor takes the following arguments:

host optional

Default value: machine hostname

Name of the machine generating the log message.

Appears in graylog as source metadata.
gelf_address optional

Default value: 127.0.0.1

Hostname or ip address of the graylog server.
gelf_port optional

Default value: 12201
gelf_protocol optional

Default value: tcp

Accepts values: tcp, udp

Socket protocol for server connection.
gelf_chunk_size optional

Default value: wan

Accepts values: lan, wan, or integer size in bytes.

Set value 0 to disable chunking.
log_level optional

Log messages of less severity will not be transmitted.
additional_fields optional

Accepts a hashref of metadata to inject in every GELF message.

is_level( $log_level )

Based on configured log_level, returns true if log message at the given level would be transmitted.

May be given Mojo log levels (trace, fatal) and sylog log levels (err, emerg). Module makes opinionated decisions how to co-mingle these differing standards.

log( %args )

Send log message to a graylog server without blocking.

Returns the id of the log process on the event loop.

Accepts the following arguments:

level required

Accepts a string or integer log severity level.

Accepts values: trace, debug, info, notice, warn, err, crit, alert, emerg, fatal, 0 .. 7

Log message will be ignored if log level is below the configured min_level.
additional_fields required

Accepts hashref metadata attached to the GELF message.

Where a metadata key name conflicts with metadata configured on the object instance, the value passed to this method will be used.

COMPATABILITY SHORTCUT METHODS

The following methods exist to provide limited interface compability with Mojo::Log

trace(@messages)

debug(@messages)

info(@messages)

notice(@messages)

warn(@messages)

warning(@messages)

err(@messages)

error(@messages)

crit(@messages)

critical(@messages)

alert(@messages)

emerg(@messages)

emergency(@messages)

fatal(@messages)

LICENSE and COPYRIGHT

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

AUTHOR

mjac [email protected]

mitchjacksontech / mojox-log-gelf Goto Github PK

mojox-log-gelf's Introduction