log4r: A Fast and Lightweight Logging System for R, Based on 'log4j'

Description

The log4r package is meant to provide a fast, lightweight, object-oriented approach to logging in R based on the widely-emulated 'log4j' system and etymology.

Author(s)

Maintainer: Aaron Jacobs atheriel@gmail.com

Authors:

• John Myles White [copyright holder]

Other contributors:

• Kenton White [contributor]

• Kirill Müller krlmlr+r@mailbox.org [contributor]

See Also

Useful links:

• https://github.com/johnmyleswhite/log4r

• Report bugs at https://github.com/johnmyleswhite/log4r/issues

Appenders

Description

In log4j etymology, Appenders are destinations where messages are written. Depending on the nature of the destination, the format of the messages may be controlled using a Layout.

The most basic appenders log messages to the console or to a file; these are described below.

For implementing your own appenders, see Details.

Usage

console_appender(layout = default_log_layout())

file_appender(file, append = TRUE, layout = default_log_layout())

Arguments

Details

Appenders are implemented as functions with the interface ⁠function(level, ...)⁠. These functions are expected to write their arguments to a destination and return invisible(NULL).

See Also

tcp_appender(), http_appender(), syslog_appender()

Examples

# The behaviour of an appender can be seen by using them directly; the
# following snippet will write the message to the console.
appender <- console_appender()
appender("INFO", "Input has length ", 0, ".")

Creates a logger object.

Description

Creates a logger object.

Usage

create.logger(logfile = "logfile.log", level = "FATAL", logformat = NULL)

Arguments

See Also

loglevel(), level.logger()

Examples

library('log4r')

logger <- create.logger(logfile = 'debugging.log', level = "DEBUG")

Log Messages via HTTP

Description

Send messages in the body of HTTP requests. Responses with status code 400 or above will trigger errors.

Requires the httr package.

Usage

http_appender(url, method = "POST", layout = default_log_layout(), ...)

Arguments

See Also

appenders() for more information on Appenders.

Examples

## Not run: 
# POST messages to localhost.
appender <- http_appender("localhost")
appender("INFO", "Message.")

# POST JSON-encoded messages.
appender <- http_appender(
  "localhost", method = "POST", layout = default_log_layout(),
  httr::content_type_json()
)
appender("INFO", "Message.")

## End(Not run)

Layouts

Description

In log4j etymology, Layouts are how Appenders control the format of messages.

Some general-purpose layouts are described below.

For implementing your own layouts, see Details.

Usage

default_log_layout(time_format = "%Y-%m-%d %H:%M:%S")

simple_log_layout()

bare_log_layout()

logfmt_log_layout()

json_log_layout()

Arguments

Details

Layouts are implemented as functions with the interface ⁠function(level, ...)⁠ and returning a single string.

json_log_layout requires the jsonlite package.

Examples

# The behaviour of a layout can be seen by using them directly:
simple <- simple_log_layout()
simple("INFO", "Input has length ", 0, ".")

with_timestamp <- default_log_layout()
with_timestamp("INFO", "Input has length ", 0, ".")

Set or get the priority level for a logger object.

Description

The priority level can be an integer from the set 1..5 (otherwise it will be modified sensibly to fit in that range), or a named logging level (one of "DEBUG", "INFO", "WARN", "ERROR", or "FATAL"). An object of class loglevel is also accepted; other input will be coerced using as.loglevel().

Usage

level(x)

level(x) <- value

## S3 method for class 'logger'
level(x)

## S3 replacement method for class 'logger'
level(x) <- value

Arguments

See Also

loglevel()

Examples

library('log4r')

logger <- create.logger(logfile = 'debugging.log', level = 1)
level(logger)
level(logger) <- "FATAL"

Write messages to logs at a given priority level.

Description

Write messages to logs at a given priority level.

Usage

levellog(logger, level, ...)

debug(logger, ...)

info(logger, ...)

warn(logger, ...)

error(logger, ...)

fatal(logger, ...)

Arguments

See Also

loglevel()

Examples

library('log4r')

logger <- create.logger(logfile = 'debugging.log', level = "WARN")

levellog(logger, 'WARN', 'First warning from our code')
debug(logger, 'Debugging our code')
info(logger, 'Information about our code')
warn(logger, 'Another warning from our code')
error(logger, 'An error from our code')
fatal(logger, "I'm outta here")

Get or set the logfile for a logger object.

Description

Get or set the logfile for a logger object.

Usage

logfile(x)

logfile(x) <- value

## S3 method for class 'logger'
logfile(x)

## S3 replacement method for class 'logger'
logfile(x) <- value

Arguments

Examples

library('log4r')

logger <- create.logger()
print(logfile(logger))
logfile(logger) <- 'debug.log'
debug(logger, 'A Debugging Message')

Get or set the format string for a logger object.

Description

Get or set the format string for a logger object.

Usage

logformat(x)

logformat(x) <- value

## S3 method for class 'logger'
logformat(x)

## S3 replacement method for class 'logger'
logformat(x) <- value

Arguments

Examples

library('log4r')

logger <- create.logger(logfile = 'debugging.log', level = 'DEBUG')
print(logformat(logger))
logformat(logger) <- 'FORMAT STRING'

Create Logger Objects

Description

This is the main interface for configuring logging behaviour. We adopt the well-known log4j etymology: Appenders are destinations (e.g. the console or a file) where messages are written, and the Layout is the format of the messages.

Usage

logger(threshold = "INFO", appenders = console_appender())

Arguments

Value

An object of class "logger".

See Also

Appenders and Layouts for information on controlling the behaviour of the logger object.

Examples

# By default, messages are logged to the console at the
# "INFO" threshold.
logger <- logger()

info(logger, "Located nearest gas station.")
warn(logger, "Ez-Gas sensor network is not available.")
debug(logger, "Debug messages are suppressed by default.")

Logging levels

Description

Functions for handling logging levels. With each log entry, a logging level is associated that indicate its severity – debugging output, informational output, warning message, error message or fatal error. Each logger only prints log entries where the log level is equal or above its threshold.

Usage

loglevel(i)

is.loglevel(x, ...)

as.loglevel(i)

## S3 method for class 'loglevel'
print(x, ...)

## S3 method for class 'loglevel'
as.numeric(x, ...)

## S3 method for class 'loglevel'
as.character(x, ...)

available.loglevels()

verbosity(v)

Arguments

Details

To specify a logging level, use a character value, e.g. "WARN", or an integer between 1 and 5. The function available.levels lists all possible logging levels.

Value

An object of class "loglevel"

Examples

loglevel(2) == loglevel("INFO")
loglevel("WARN") < loglevel("ERROR")
loglevel(-1)
try(loglevel("UNDEFINED"))
is.loglevel("DEBUG")
is.loglevel(loglevel("DEBUG"))
as.numeric(loglevel("FATAL"))
available.loglevels()

## Not run: 
library(optparse)
library(log4r)

optlist <- list(make_option(c('-v', '--verbosity-level'),
  type = "integer",
  dest = "verbosity",
  default = 1,
  help = "Verbosity threshold (5=DEBUG, 4=INFO 3=WARN, 2=ERROR, 1=FATAL)"))

optparser <- OptionParser(option_list=optlist)
opt <- parse_args(optparser)

my.logger <- create.logger(logfile = "", level = verbosity(opt$verbosity))

fatal(my.logger, "Fatal message")
error(my.logger, "Error message")
warn(my.logger, "Warning message")
info(my.logger, "Informational message")
debug(my.logger, "Debugging message")

## End(Not run)

Log Messages to the Local Syslog

Description

Send messages to the local syslog. Requires the rsyslog package.

Usage

syslog_appender(identifier, layout = bare_log_layout(), ...)

Arguments

See Also

appenders() for more information on Appenders.

Log Messages via TCP

Description

Append messages to arbitrary TCP destinations.

Usage

tcp_appender(
  host,
  port,
  layout = default_log_layout(),
  timeout = getOption("timeout")
)

Arguments

See Also

appenders() for more information on Appenders, and base::socketConnection() for the underlying connection object used by tcp_appender.