Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Syslog::Fast(3)  User Contributed Perl Documentation Log::Syslog::Fast(3)

NAME
       Log::Syslog::Fast - Perl	extension for sending syslog messages over
       TCP, UDP, or UNIX sockets with minimal CPU overhead.

SYNOPSIS
	 use Log::Syslog::Fast ':all';
	 my $logger = Log::Syslog::Fast->new(LOG_UDP, "127.0.0.1", 514,	LOG_LOCAL0, LOG_INFO, "mymachine", "logger");
	 $logger->send("log message", time);

DESCRIPTION
       This module sends syslog	messages over a	network	socket.	It works like
       Sys::Syslog in setlogsock's 'udp', 'tcp', or 'unix' modes, but without
       the significant CPU overhead of that module when	used for high-volume
       logging.	Use of this specialized	module is only recommended if 1) you
       must use	network	syslog as a messaging transport	but 2) need to
       minimize	the time spent in the logger.

       This module supercedes the less general Log::Syslog::UDP.

METHODS
       Log::Syslog::Fast->new($proto, $hostname, $port,	$facility, $severity,
       $sender,	$name);
	   Create a new	Log::Syslog::Fast object with the following
	   parameters:

	   $proto
	       The transport protocol: one of LOG_TCP, LOG_UDP,	or LOG_UNIX.

	       If LOG_TCP or LOG_UNIX is used, calls to	$logger->send()	will
	       block until remote receipt of the message is confirmed. If
	       LOG_UDP is used,	the call will never block and may fail if
	       insufficient buffer space exists	in the network stack (in which
	       case an exception will be thrown).

	       With LOG_UNIX, -_new will first attempt to connect with a
	       SOCK_STREAM socket, and then try	a SOCK_DGRAM if	that is	what
	       the server expects (e.g.	 rsyslog).

	   $hostname
	       For LOG_TCP and LOG_UDP,	the destination	hostname where a
	       syslogd is running.  For	LOG_UNIX, the path to the UNIX socket
	       where syslogd is	listening (typically /dev/log).

	   $port
	       For LOG_TCP and LOG_UDP,	the destination	port where a syslogd
	       is listening, usually 514. Unused for LOG_UNIX, but should not
	       be undefined or a warning will be emitted under strict.

	   $facility
	       The syslog facility constant, eg	16 for 'local0'. See RFC3164
	       section 4.1.1 (or <sys/syslog.h>) for appropriate constant
	       values. See EXPORTS below for making these available by name.

	       The priority value is computed from the facility	and severity
	       per the RFC.

	   $severity
	       The syslog severity constant, eg	6 for 'info'. See RFC3164
	       section 4.1.1 (or <sys/syslog.h>) for appropriate constant
	       values. See EXPORTS below for making these available by name.

	   $sender
	       The originating hostname. Sys::Hostname::hostname is typically
	       a reasonable source for this.

	   $name
	       The program name	or tag to use for the message.

       $logger->send($logmsg, [$time])
       $logger->emit($logmsg, [$time])
	   Send	a syslog message through the configured	logger.	If $time is
	   not provided, time(2) will be called	for you. That doubles the
	   syscalls per	message, so try	to pass	it if you're already calling
	   time() yourself.

	   ->send may throw an exception if the	system call fails (e.g.	the
	   transport becomes disconnected for connected	protocols, or the
	   kernel buffer is full for unconnected). For this reason it is
	   usually wise	to wrap	calls with an exception	handler. Likewise,
	   calling ->send from a $SIG{__DIE__} handler is unwise.

	   emit	is an alias for	send.

	   NEWLINE CAVEAT

	   Note	that send does not add any newline character(s)	to its input.
	   You will certainly want to do this yourself for TCP connections, or
	   the server will not treat each message as a separate	line. However
	   with	UDP the	server should accept a message without a trailing
	   newline (though some	implementations	may have difficulty with
	   that).

       $logger->set_receiver($proto, $hostname,	$port)
	   Change the protocol,	destination host, and port. This will force a
	   reconnection	in LOG_TCP or LOG_UNIX mode.

       $logger->set_priority($facility,	$severity)
	   Change both the syslog facility and severity.

       $logger->set_facility($facility)
	   Change only the syslog facility.

       $logger->set_severity($severity)
	   Change only the syslog severity.

       $logger->set_sender($sender)
	   Change what is sent as the hostname of the sender.

       $logger->set_name($name)
	   Change what is sent as the name of the sending program.

       $logger->set_pid($name)
	   Change what is sent as the process id of the	sending	program.

       $logger->set_format($format)
	   Change the message format. This should be either the	constant
	   LOG_RFC3164 (the default) or	LOG_RFC5424 or LOG_RFC3164_LOCAL
	   (without HOSTNAME).

       $logger->get_priority()
	   Returns the current priority	value.

       $logger->get_facility()
	   Returns the current facility	value.

       $logger->get_severity()
	   Returns the current severity	value.

       $logger->get_format($format)
	   Returns the current message format.

UNREACHABLE SERVERS
       If the remote syslogd is	unreachable, certain methods may throw an
       exception or raise a signal:

       o   LOG_TCP

	   If the server is unreachable	at connect time, -_new will fail with
	   an exception. If an established connection is closed	remotely,
	   -_send will fail with an exception.

       o   LOG_UDP

	   As UDP is connectionless, -_new will	not throw an error as no
	   attempt to connect is made then. However, if	the remote server
	   starts or becomes unreachable and 1)	the host is alive but 2) not
	   listening on	the specified port, and	3) ICMP	packets	are routable
	   to the client, an exception may be thrown by	-_send;	note that this
	   may happen only on the second call, and subsequently	every other
	   one.	This behavior also depends on specific kernel interactions.

       o   LOG_UNIX

	   With	both SOCK_STREAM- and SOCK_DGRAM-based servers,	-_new will
	   throw an exception if the socket is missing or not connectable.

	   With	SOCK_DGRAM, -_send to a	peer that went away will throw.	With
	   SOCK_STREAM,	-_send to a peer that went away	will raise SIGPIPE.

EXPORTS
       Use Log::Syslog::Constants to export priority constants,	e.g. LOG_INFO.

SEE ALSO
       Log::Syslog::Constants

       Sys::Syslog

BUGS
       LOG_UNIX	with SOCK_DGRAM	has not	been well tested.

AUTHOR
       Adam Thomason, <athomason@cpan.org>

COPYRIGHT AND LICENSE
       Copyright (C) 2009-2011 by Say Media, Inc.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.5 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.0			  2019-12-16		  Log::Syslog::Fast(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | UNREACHABLE SERVERS | EXPORTS | SEE ALSO | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Syslog::Fast&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help