The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
BLHOTSKY / Parse-Syslog-Line-3.6 / README.mkdn

NAME

Parse::Syslog::Line - Simple syslog line parser

VERSION

version 3.6

SYNOPSIS

I wanted a very simple log parser for network based syslog input. Nothing existed that simply took a line and returned a hash ref all parsed out.

use Parse::Syslog::Line qw(parse_syslog_line);

$Parse::Syslog::Line::DateTimeCreate = 1;

my $href = parse_syslog_line( $msg );
#
# $href = {
#       preamble        => '13',
#       priority        => 'notice',
#       priority_int    => 5,
#       facility        => 'user',
#       facility_int    => 8,
#       date            => 'YYYY-MM-DD',
#       time            => 'HH::MM:SS',
#       epoch           => 1361095933,
#       datetime_str    => 'YYYY-MM-DD HH:MM:SS',
#       datetime_obj    => new C<DateTime()> or C<Time::Moment> object, depending on the NormalizeToUTC switch
#       datetime_utc    => ISO 8601 UTC datetime # If $NormalizeToUTC or returned by FmtDate formatter
#       datetime_raw    => 'Feb 17 11:12:13'
#       date_raw        => 'Feb 17 11:12:13'
#       host_raw        => 'hostname',  # Hostname as it appeared in the message
#       host            => 'hostname',  # Hostname without domain
#       domain          => 'blah.com',  # if provided
#       program_raw     => 'sshd(blah)[pid]',
#       program_name    => 'sshd',
#       program_sub     => 'pam_unix',
#       program_pid     => 20345,
#       content         => 'the rest of the message'
#       message         => 'program[pid]: the rest of the message',
#       message_raw     => 'The message as it was passed',
#       ntp             => 'ok',           # Only set for Cisco messages
# };
...

EXPORT

Exported by default: parse_syslog_line( $one_line_of_syslog_message );

Optional Exports: :preamble preamble_priority preamble_facility

:constants
     %LOG_FACILITY
     %LOG_PRIORITY

:with_timezones
     set_syslog_timezone
     get_syslog_timezone
     use_utc_syslog

VARIABLES

ExtractProgram

If this variable is set to 1 (the default), parse_syslog_line() will try it's best to extract a "program" field from the input. This is the most expensive set of regex in the module, so if you don't need that pre-parsed, you can speed the module up significantly by setting this variable.

Vendors who do proprietary non-sense with their syslog formats are to blame for this setting.

Usage:

$Parse::Syslog::Line::ExtractProgram = 0;

DateParsing

If this variable is set to 0 raw date will not be parsed further into components (datetime_str date time epoch). Default is 1 (parsing enabled).

Usage:

$Parse::Syslog::Line::DateParsing = 0;

DateTimeCreate

If this variable is set to 1 (the default), a DateTime object will be returned in the $m->{datetime_obj} field. Otherwise, this will be skipped.

NOTE: DateTime timezone calculation is fairly slow. Unless you really need to take timezones into account, you're better off using other modes (below).

Usage:

$Parse::Syslog::Line::DateTimeCreate = 0;

EpochCreate

If this variable is set to 1, the number of seconds from UNIX epoch will be returned in the $m->{epoch} field. If DateTimeCreate is not set, the parser will use HTTP::Date to perform the parsing. This is faster but assumes local timezone if its not present in parsed string. In other words it ignores the timezone you set for syslog with set_syslog_timezone.

Usage:

$Parse::Syslog::Line::EpochCreate = 1;

NormalizeToUTC

Coerces dates to ISO8601 format, using Time::Moment. There are two possible modes of operation:

If your syslog does not have UTC ISO 8601 timestamps

Using costly DateTime math we calculate the UTC version of the incomplete date for a given timezone and then parse the resulting DateTime object using Time::Moment.

Usage: $Parse::Syslog::Line::DateTimeCreate = 1; # default $Parse::Syslog::Line::NormalizeToUTC = 1;

See also: set_syslog_timezone.

If your syslog timestamps are ISO 8601 compliant

This allows us to skip costly datetime DST calculations, and is very fast. You get the same amount of date information as with the defaults.

Usage: $Parse::Syslog::Line::DateTimeCreate = 0; $Parse::Syslog::Line::EpochCreate = 0; $Parse::Syslog::Line::IgnoreTimeZones = 0; $Parse::Syslog::Line::NormalizeToUTC = 1;

# or

use Parse::Syslog::Line qw/:with_timezones/;
use_utc_syslog(); # sets syslog_timezone to 'UTC' and above variables

See also: set_syslog_timezone()

IgnoreTimeZones

Similarly to EpochCreate, parser will use HTTP::Date to perform the parsing, but this time using "parse_date" function. We then discard the timezone part from created dates. Even if the timezone is present in the message it will not be used to construct the date string and components (date, time, datetime_str).

FmtDate

You can pass your own formatter/parser here. Given a raw datetime string it should output a list containing date, time, epoch, datetime_str, datetime_utc in your wanted format. NOTE: No further date processing will be done, you're on your own here.

PruneRaw

This variable defaults to 0, set to 1 to delete all keys in the return hash ending in "_raw"

Usage:

$Parse::Syslog::Line::PruneRaw = 1;

PruneEmpty

This variable defaults to 0, set to 1 to delete all keys in the return hash which are undefined.

Usage:

$Parse::Syslog::Line::PruneEmpty = 1;

PruneFields

This should be an array of fields you'd like to be removed from the hash reference.

Usage:

@Parse::Syslog::Line::PruneFields = qw(date_raw facility_int priority_int);

FUNCTIONS

parse_syslog_line

Returns a hash reference of syslog message parsed data.

set_syslog_timezone($timezone_name)

Sets a timezone $timezone_name for parsed messages. This timezone will be used to calculate offset from UTC if a timezone designation is not present in the message being parsed. Returns the DateTime::TimeZone. object for given timezone. If called without parameters, assumes local timezone.

NOTE: this works in conjunction with $NormalizeToUTC and automagically sets: $NormalizeToUTC=1 $DateTimeCreate=1

See also $NormalizeToUTC

get_syslog_timezone

Returns the name of the timezone currently set by set_syslog_timezone.

use_utc_syslog

A convenient function which sets the syslog timezone to UTC and sets the config variables accordingly. NOTE: by using this you promise the parser that it will get ISO8601 compliant dates. If a date is unparsable the parser will emit a warning and set all date fields to undef.

preamble_priority

Takes the Integer portion of the syslog messsage and returns a hash reference as such:

$prioRef = {
    'preamble'  => 13
    'as_text'   => 'notice',
    'as_int'    => 5,
};

preamble_facility

Takes the Integer portion of the syslog messsage and returns a hash reference as such:

$facRef = {
    'preamble'  => 13
    'as_text'   => 'user',
    'as_int'    => 8,
};

DEVELOPMENT

This module is developed with Dist::Zilla. To build from the repository, use Dist::Zilla:

dzil authordeps |cpanm
dzil build
dzil test

AUTHOR

Brad Lhotsky brad@divisionbyzero.net

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by Brad Lhotsky.

This is free software, licensed under:

The (three-clause) BSD License

CONTRIBUTORS

SUPPORT

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Source Code

This module's source code is available by visiting: https://github.com/reyjrar/Parse-Syslog-Line