Skip to contents

Getting started

NEST CoreDev Team

15.03.2022

teal-logger.Rmd

Introduction

The teal.logger package uses the logger framework to log events in a package. logger is an R package supporting logging namespaces, hierarchical logging, variety of log destinations, vectorization, etc. More information on logger can be found on:

teal.logger’s default logging setup

teal.logger uses a function (register_logger) to instantiate a new logger in a namespace of the user’s choosing. teal.logger comes with a pair of default layout and logging level. Other packages in the teal framework use teal.logger to log the most important events, e.g. setup of teal data, changes in the filter panel, records of merging the data slices inside the modules, etc.

teal.logger’s defaults:

  • logging level: logger.INFO
  • logging layout: [{level}] {format(time, \"%Y-%m-%d %H:%M:%OS4\")} pid:{pid} token:[{token}] {ans} {msg}
  • logs emitted to stdout

Look at the logger documentation for more information on what different logging levels mean and how to interpret the layout.

Customizing the log level

When using register_logger the logging level of the new logger defaults to logger::INFO. You can customize this behavior in 4 different ways:

  1. Using the logger interface.
library(teal.logger)
register_logger("my_namespace")
logger::log_threshold(logger::TRACE, namespace = "my_namespace")

Customizing teal’s logging level:

library(teal.logger)
logger::log_threshold(logger::TRACE, namespace = "teal")
  1. Using the function argument of register_logger.
library(teal.logger)
register_logger("my_namespace", level = logger::TRACE)

Customizing teal’s logging level:

library(teal.logger)
register_logger(namespace = "teal", level = logger::TRACE)
  1. Setting an environment variable.
library(teal.logger)
Sys.setenv(TEAL.LOG_LEVEL = "TRACE")
register_logger("my_namespace")

Customizing teal’s logging level:

Sys.setenv(TEAL.LOG_LEVEL = "TRACE")
library(teal.logger)
  1. Setting an option.
library(teal.logger)
options(teal.log_level = logger::TRACE)
register_logger("my_namespace")

Customizing teal’s logging level:

options(teal.log_level = logger::TRACE)
library(teal.logger)

Please, note that packages in the teal framework register their loggers when loading a library, which means that if you want to change its default logging level via an option or a system environment variable, you should change the variable first, then load the library. Example below:

# library(teal)
# Sys.setenv(TEAL.LOG_LEVEL = "TRACE") # won't change the default
# Sys.setenv(TEAL.LOG_LEVEL = "TRACE")
# library(teal)
# will change the default because teal is attached after changing the variable

Alternatively, you can change the options after loading a package and then call teal.logger::register_logger with the appropriate namespace name to change the default of a single package. E.g. this will change the defaults of teal.logger. Replace teal.logger with the name of the package you want to change.

library(teal.logger)
Sys.setenv(TEAL.LOG_LEVEL = "TRACE")
register_logger('teal.logger')

For more information, have a look at the logger documentation and the documentation for teal.logger::register_logger.

Customizing the log layout

When using register_logger the log layout of the new logger defaults to [{level}] {format(time, \"%Y-%m-%d %H:%M:%OS4\")} pid:{pid} token:[{token}] {ans} {msg}. You can customize this behavior in 4 different ways:

  1. Using the logger interface.
library(teal.logger)
register_logger("my_namespace")
logger::log_layout("{level} {msg}", namespace = "my_namespace")

Customizing teal’s logging layout:

library(teal.logger)
logger::log_layout("{level} {msg}", namespace = "teal")
  1. Using the function argument of register_logger.
library(teal.logger)
register_logger("my_namespace", layout = "{level} {msg}")

Customizing teal’s logging layout:

library(teal.logger)
register_logger(namespace = "teal", layout = "{level} {msg}")
  1. Setting an environment variable.
library(teal.logger)
Sys.setenv(TEAL.LOG_LAYOUT = "{level} {msg}")
register_logger("my_namespace")

Customizing teal’s logging layout:

Sys.setenv(TEAL.LOG_LAYOUT = "{level} {msg}")
library(teal.logger)
  1. Setting an option.
library(teal.logger)
options(teal.log_layout = "{level} {msg}")
register_logger("my_namespace")

Customizing teal’s logging layout:

options(teal.log_layout = "{level} {msg}")
library(teal.logger)

Please, note that teal registers its logger when loading the library, which means that if you want to change its default logging layout via an option or a system environment variable, you should change the variable first, then load the library. Example below:

library(teal.logger)
Sys.setenv(TEAL.LOG_LAYOUT = "{level} {msg}") # won't change the default
Sys.setenv(TEAL.LOG_LAYOUT = "{level} {msg}")
library(teal.logger)
# will change the default because teal is attached after changing the variable

Alternatively, you can change the options after loading a package and then call teal.logger::register_logger with the appropriate namespace name to change the default of a single package. E.g. this will change the defaults of teal.logger. Replace teal.logger with the name of the package you want to change.

library(teal.logger)
Sys.setenv(TEAL.LOG_LAYOUT = "{level} {msg}")
register_logger('teal.logger')

For more information, have a look at the logger documentation and the documentation for teal.logger::register_logger.

Customizing the log destination

teal.logger, by default emits logs to stdout. If you want to change its behavior, you have to use logger’s API.

Example of redirecting teal’s logs to stderr using logger’s API:

library(teal.logger)
logger::log_appender(logger::appender_stderr, namespace = "teal")

Logging in other teal.X packages

The other teal.X packages, like teal.data, use teal.logger::register_logger to register loggers in their namespace. Each package registers a logger in the namespace equal to the package name. E.g. teal.data registers a logger in teal.data namespace. A package instantiates its logger during the package loading and using the default logging settings subject to the modifications described in the sections above.

Example of usage

A minimal working example of logging using teal’s logging setup. By default TEAL.LOG.LEVEL = "INFO" which means that logs of level above level = 400 won’t be passed to the stdout.

library(teal.logger)
register_logger(namespace = "my_module")

logger::log_error("This is an ERROR level log from my module", namespace = "my_module") # 200
logger::log_warn("This is a WARN level log from my module", namespace = "my_module") # 300
logger::log_success("This is a SUCCESS level log from my module", namespace = "my_module") # 350
logger::log_info("This is an INFO level log from my module", namespace = "my_module") # 400
logger::log_info("This is a DEBUG level log from my module", namespace = "my_module") # 500
logger::log_trace("This is a TRACE level log from my module", namespace = "my_module") # 600