Skip to content

Latest commit

 

History

History
341 lines (270 loc) · 9.41 KB

syslog.md

File metadata and controls

341 lines (270 loc) · 9.41 KB

README ➟ syslog

Module syslog

Behaviours: gen_server.
Authors: Christopher Faulet ([email protected]).

Description

Main module of the sysloggerl application. It contains functions to manage loggers and to log messages to syslog daemons.

Exported types

facility() :: kern   | user   | mail   | daemon | auth     | syslog
            | lpr    | news   | uucp   | cron   | authpriv | ftp
            | local0 | local1 | local2 | local3 | local4   | local5
            | local6 | local7.

loglevel() :: emergency | alert | critical | error | warning | notice
            | info      | debug.

priority() :: #priority{}. %% Defined in 'sysloggerl.hrl'

logger() :: #logger{}.     %% Defined in 'sysloggerl.hrl'

Functions index

Function name Description
Loggers management functions
set/1,4 Creates a new logger or updates an existing one.
unset/1 Removes an existing logger.
loggers/0 Returns all existing loggers.
logger/1 Returns a logger given its name.
Logging functions
log/1,2,3 Basic functions to log messages.
LOGLEVEL_msg/1,2,3 Functions to log messages with the LOGLEVEL log level.
Functions to handle #priority{} record
priority/2 Creates a #priority{} record.
set_facility/2 Sets the facility of a #priority{} record.
get_facility/1 Gets the facility of a #priority{} record.
set_loglevel/2 Sets the log level of a #priority{} record.
get_loglevel/1 Gets the log level of a #priority{} record.
is_facility_valid/1 Tests if the given facility is valid.
is_loglevel_valid/1 Tests if the given log level is valid.
Convenient routines specifying log levels and facility codes
LOGLEVEL/0 Returns the code corresponding to the LOGLEVEL log level.
FACILITY/0 Returns the code corresponding to the FACILITY facilty.

Functions details

Loggers management functions

set/1,4

set(Name, Ident, Priority, Options) -> Result when
      Name     :: any(),
      Ident    :: string(),
      Priority :: priority(),
      Options  :: proplists:proplist(),
      Result   :: {ok, logger()}
                | {error, invalid_facility | invalid_loglevel}.

Creates a new logger or updates an existing one. The available options are:

  • log_pid: Include the caller's PID with each message.
  • {host, string()}: Send messages to the specified syslog server.
  • {port, pos_integer()}: Use the specified port.

If the logger creation is successful, the function should return {ok, Logger}, where Logger is the created logger. If the Priority is malformed, the function should return {error, invalid_facility} or {error, invalid_loglevel} depending on which field is invalid.

set(Logger) -> Result when
      Logger   :: logger(),
      Result   :: {ok, logger()}
                | {error, invalid_facility | invalid_loglevel}.

Equivalent to set(Logger#logger.name, Logger#logger.ident, Logger#logger.priority, Logger#logger.options).

unset/1

unset(Name) -> ok when
      Name :: any().

Removes the logger with the name Name. This function always returns ok, regardless the logger is found or not.

loggers/0

loggers() -> [logger()].

Returns all existing loggers.

logger/1

logger(Name) -> Result when
      Name   :: any(),
      Result :: logger() | not_found.

Returns the logger with the name Name, or not_found if such logger does not exist.

Logging functions

log/1,2,3

log(Message) -> Result when
      Message  :: string(),
      Result   :: ok.

Same as log(Message, []).

log(Format, Args) -> Result when
      Format   :: string(),
      Args     :: list(),
      Result   :: ok.

Same as log(undefined, Format, Args).

log(LogLevel, Format, Args) -> Result when
      LogLevel :: loglevel() | undefined,
      Format   :: string(),
      Args     :: list(),
      Result   :: ok.

Same as log(default, LogLevel, Format, Args).

log(Name, LogLevel, Format, Args) -> Result when
      Name     :: any(),
      LogLevel :: loglevel() | undefined,
      Format   :: string(),
      Args     :: list(),
      Result   :: ok.

Sends a message using the logger with the name Name and the specified LogLevel. If LogLevel is undefined, the minimum log level of the logger will be used (defined during its creation).
This function never fails.

LOGLEVEL_msg/1,2,3

Here LOGLEVEL should be replaced by one of the log levels defined below.

LOGLEVEL_msg(Message) -> Result when
      Message  :: string(),
      Result   :: ok.

Same as LOGLEVEL_msg(Message, []).

LOGLEVEL_msg(Format, Args) -> Result when
      Format   :: string(),
      Args     :: list(),
      Result   :: ok.

Same as LOGLEVEL_msg(default, Format, Args).

LOGLEVEL_msg(Name, Format, Args) -> Result when
      Name     :: any(),
      Format   :: string(),
      Args     :: list(),
      Result   :: ok.

Sends a message using the logger with the name Name and the log level LOGLEVEL.
This function never fails.

1> syslog:error_msg("An error occurred").
ok

Functions to handle #priority{} record

priority/2

priority(Facility, LogLevel) -> Result when
      Facility :: facility() | undefined,
      LogLevel :: loglevel(),
      Result   :: priority()
                | {error, invalid_facility | invalid_loglevel}.

Creates a #priority{} record where the facility is set to Facility and the log level to LogLevel.

2> syslog:priority(user, info).
#priority{facility = user, log_level = info}
3> syslog:priority(daemon, warning).
#priority{facility = daemon, log_level = warning}

set_facility/2

set_facility(Facility, Priority) -> Result when
      Priority :: priority(),
      Facility :: facility(),
      Result   :: priority() | {error, invalid_facility}.

Update the given #priority{} record by setting the facility to Facility.

get_facility/1

get_facility(Priority) -> Facility when
      Priority :: priority(),
      Facility :: facility().

Returns the facility of the priority Priority.

set_loglevel/2

set_loglevel(LogLevel, Priority) -> Result when
      Priority :: priority(),
      LogLevel :: loglevel(),
      Result   :: priority() | {error, invalid_loglevel}.

Update the given #priority{} record by setting the log level to LogLevel.

get_loglevel/1

get_loglevel(Priority) -> LogLevel when
      Priority :: priority(),
      LogLevel :: loglevel().

Returns the log level of the priority Priority.

is_facility_valid/1

is_facility_valid(any()) -> boolean().

Returns true if the parameter is a valid facility. Else it returns false.

is_loglevel_valid/1

is_loglevel_valid(any()) -> boolean().

Returns true if the parameter is a valid log level. Else it returns false.

Convenient routines specifying log levels and facility codes

LOGLEVEL/0

Here LOGLEVEL should be replaced by one of the following log levels.

LOGLEVEL() -> 0.

Returns the code corresponding to the LOGLEVEL log level.

4> syslog:emergency().
0
5> syslog:debug().
7

The log level determines the importance of the message. The levels are, in order of decreasing importance:

  • emergency: System is unusable.
  • alert: Action must be taken immediately.
  • critical: Critical conditions.
  • error: Error conditions.
  • warning: Warning conditions.
  • notive: Normal, but significant, condition.
  • info: Informational message.
  • debug: Debug-level message.

FACILITY/0

Here FACILITY should be replaced by one of the following facilities.

FACILITY() -> 0.

Returns the code corresponding to the FACILITY facility.

6> syslog:daemon().
3
7> syslog:local3().
19

The facility is used to specify what type of program is logging the message. This lets the syslog daemon to specify that messages from different facilities will be handled differently. The facilities are:

  • kern: Kernel messages.
  • user: Generic user-level messages.
  • mail: Mail subsystem.
  • daemon: System daemons without separate facility value.
  • auth: Security/authorization messages.
  • syslog: Messages generated internally by syslogd(8).
  • lpr: Line printer subsystem.
  • news: USENET news subsystem.
  • uucp: UUCP subsystem.
  • cron: Clock daemon (cron and at).
  • authpriv: Security/authorization messages (private).
  • ftp: Ftp daemon.
  • local0-7: Reserved for local use.