The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Log-GELF-Util-0.91
River stage one • 2 direct dependents • 3 total dependents
/ Log::GELF::Util

NAME

Log::GELF::Util - Utility functions for Graylog's GELF format.

SYNOPSIS

use Log::GELF::Util qw( encode );

my $msg = encode( { short_message => 'message', } );


use Log::GELF::Util qw( :all );

sub process_chunks {

    my @chunks; my $msg;

    do {
        $msg = dechunk(\@chunks, decode_chunk(shift()));
    } until ($msg);

    return uncompress( $msg );
};

my $hr = validate_message( short_message => 'message' );

DESCRIPTION

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 by http://docs.graylog.org/en/latest/pages/gelf.html.

FUNCTIONS

validate_message( short_message => $ )

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:

short_message

Mandatory string, a short descriptive message

version

String, must be '1.1' which is the default.

host

String, defaults to hostname() from Sys::Hostname.

timestamp

Timestamp, defaults to time() from Time::HiRes.

level

Integer, equal to the standard syslog levels, default is 1 (ALERT).

facility

Deprecated, a warning will be issued.

line

Deprecated, a warning will be issued.

file

Deprecated, a warning will be issued.

_[additional_field]

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.

encode( \% )

Accepts HASHREF to a structure representing a GELF message. The message will be converted validated with validate_message.

Returns a JSON encoded string representing the message.

decode( $ )

Accepts a JSON encoded string representing the message. This will be converted to a hashref and validated with validate_message.

Returns a HASHREF representing the validated message with any defaulted values added to the data structure.

compress( $ [, $] )

Accepts a string and compresses it. The second parameter is optional and can take the value zlib or gzip, defaulting to gzip.

Returns a compressed string.

uncompress( $ )

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.

enchunk( $ [, $] )

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.

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.

dechunk( \@, \% )

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 @chunks;
    my $msg;

    do {
        $msg = dechunk(\@chunks, decode_chunk(shift()));
    } until ($msg);

    return $msg;
};

is_chunked( $ )

Accepts a string and returns a true value if it is a GELF message chunk.

decode_chunk( $ )

Accepts a GELF message chunk and returns an ARRAYREF representing the chunk. The message consists of the following keys:

id sequence_number sequence_count data

decode_chunk dies if the input is not a GELF chunk.

parse_level( $ )

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>'.

The string forms may also be elongated and will still be accepted. For example 'err' and 'error' are equivalent.

The associated syslog level is returned in numeric form.

parse_level dies upon invalid input.

parse_size( $ )

Accepts 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.

CONSTANTS

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';

$GELF_MSG_MAGIC

The magic number used to identify a GELF message chunk.

$ZLIB_MAGIC

The magic number used to identify a Zlib deflated message.

$GZIP_MAGIC

The magic number used to identify a gzipped message.

%LEVEL_NAME_TO_NUMBER

A HASH mapping the level names to numbers.

%LEVEL_NUMBER_TO_NAME

A HASH mapping the level numbers to names.

%GELF_MESSAGE_FIELDS

A HASH where each key is a valid core GELF message field name. Deprecated fields are associated with a false value.

LICENSE

Copyright (C) Strategic Data.

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

AUTHOR

Adam Clarke <adamc@strategicdata.com.au>