Log::GELF::Util - Utility functions for Graylog's GELF format.
use Log::GELF::Util qw( encode ); my $msg = encode( { short_message => 'message', } ); use Log::GELF::Util qw( :all ); sub process_chunks { my @accumulator; my $msg; do { $msg = dechunk( \@accumulator, decode_chunk(shift()) ); } until ($msg); return uncompress($msg); }; my $hr = validate_message( short_message => 'message' );
Log::GELF::Util is a collection of functions and data structures useful when working with Graylog's GELF Format version 1.1. It strives to support all of the features and options as described in the GELF specification.
Returns a HASHREF representing the validated message with any defaulted values added to the data structure.
Takes the following message parameters as per the GELF message specification:
Mandatory string, a short descriptive message
String, must be '1.1' which is the default.
String, defaults to hostname() from Sys::Hostname.
Timestamp, defaults to time() from Time::HiRes.
Integer, equal to the standard syslog levels, default is 1 (ALERT).
Deprecated, a warning will be issued.
Parameters prefixed with an underscore (_) will be treated as an additional field. Allowed characters in field names are any word character (letter, number, underscore), dashes and dots. As per the specification '_id' is disallowed.
Accepts a HASHREF representing a GELF message. The message will be validated with "validate_message".
Returns a JSON encoded string representing the message.
Accepts a JSON encoded string representing the message. This will be converted to a hashref and validated with "validate_message".
Accepts a string and compresses it. The second parameter is optional and can take the value zlib or gzip, defaulting to gzip.
zlib
gzip
Returns a compressed string.
Accepts a string and uncompresses it. The compression method (gzip or zlib) is determined automatically. Uncompressed strings are passed through unaltered.
Returns an uncompressed string.
Accepts an encoded message (JSON string) and chunks it according to the GELF chunking protocol.
The optional second parameter is the maximum size of the chunks to produce, this must be a positive integer or the special strings lan or wan, see "parse_size". Defaults to wan. A zero chunk size means no chunking will be applied.
lan
wan
The optional third parameter is the message id used to identify associated chunks. This must be 8 bytes. It defaults to 8 bytes of randomness generated by Math::Random::MT.
If the message size is greater than the maximum size then an array of chunks is retuned, otherwise the message is retuned unaltered as the first element of an array.
This facilitates reassembling a GELF message from a stream of chunks.
It accepts an ARRAYREF for accumulating the chunks and a HASHREF representing a decoded message chunk as produced by "decode_chunk".
It returns undef if the accumulator is not complete, i.e. all chunks have not yet been passed it.
Once the accumulator is complete it returns the de-chunked message in the form of a string. Note that this message may still be compressed.
Here is an example usage:
sub process_chunks { my @accumulator; my $msg; do { $msg = dechunk( \@accumulator, decode_chunk(shift()) ); } until ($msg); return uncompress($msg); };
Accepts a string and returns a true value if it is a GELF message chunk.
Accepts a GELF message chunk and returns an ARRAYREF representing the unpacked chunk. Dies if the input is not a GELF chunk.
The message consists of the following keys:
id sequence_number sequence_count data
Accepts a syslog style level in the form of a number (1-7) or a string being one of emerg, alert, crit, err, warn, notice, info, or debug. Dies upon invalid input.
syslog
emerg
alert
crit
err
warn
notice
info
debug
The string forms may also be elongated and will still be accepted. For example err and error are equivalent.
error
The associated syslog level is returned in numeric form.
Accepts an integer specifying the chunk size or the special string values lan or wan corresponding to 8154 or 1420 respectively. An explanation of these values is in the code.
Returns the passed size or the value corresponding to the lan or wan.
"parse_size" dies upon invalid input.
All Log::Gelf::Util constants are Readonly perl structures. You must use sigils when referencing them. They can be imported individually and are included when importing ':all';
The magic number used to identify a GELF message chunk.
The magic number used to identify a Zlib deflated message.
The magic number used to identify a gzipped message.
A HASH mapping the level names to numbers.
A HASH mapping the level numbers to names.
A HASH where each key is a valid core GELF message field name. Deprecated fields are associated with a false value.
Copyright (C) Strategic Data.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Adam Clarke <adamc@strategicdata.com.au>
To install Log::GELF::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Log::GELF::Util
CPAN shell
perl -MCPAN -e shell install Log::GELF::Util
For more information on module installation, please visit the detailed CPAN module installation guide.