---
title: "Levels"
author: Brandon Moretz
date: "`r Sys.Date()`"
output:
  prettydoc::html_pretty:
    theme: architect
    highlight: github
  
vignette: >
  %\VignetteIndexEntry{Levels}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

# Dynamic Log Levels

```{r setup}
library(dyn.log)

init_logger()
```

```{r, comment="", results="asis", echo=F}
options(crayon.enabled=TRUE)
knitr::opts_chunk$set(collapse = TRUE, comment = "")
old.hooks <- fansi::set_knit_hooks(knitr::knit_hooks)
```

## Definitions

One of the main objectives of *dyn.log* is to be as configuration driven as possible, which
allows the logger to conform to the problem - not the other way around. Log levels are fully 
configuration driven, and they are specified in the logger configuration with the following
schema:

```yaml
levels:
- name: DEBUG
  description: This level designates fine-grained informational events that are most useful to debug an application.
  severity: !expr 500L
  log_style: !expr crayon::make_style('deepskyblue2')$bold
  msg_style: !expr crayon::make_style('gray90')
```

The levels node contains the log levels you want available in your environment. When a log level is defined in the configuration, it automatically becomes accessible via a first-class function on the dispatcher, e.g.:

### Attributes

The attributes that define a log level are:

* **name**: what gets displayed as the level when a log message is rendered.
* **description**: a brief description of the log level & limited info on appropriate usage.
* **severity**: log severity is used in determining if a message should get displayed according to the currently set evaluation threshold.
* **log_style**: a [crayon](https://github.com/r-lib/crayon) that will colorize the log level.
* **msg_style**: a [crayon](https://github.com/r-lib/crayon) style that will gray scale the log message, with
  typically inverted strength, according to the severity.

### Invocation

Once you have defined a log level in the logger configuration, the dispatcher will automatically have a method 
corresponding to that level. This enables a fairly intuitive approach to invoking the log dispatcher, e.g., if you
have the previous *debug* level defined in your configuration this is how you would log a message with that level:

```{r, simple_debug_example}
var1 <- "abc"; var2 <- 123; var3 <- round(runif(1), digits = 6)

Logger$debug("my log message - var1: {var1}, var2: {var2}, var3: {var3}")
```

You'll notice that all log messages by default use the standardize [glue](https://github.com/tidyverse/glue) format so local variables are capturable in the log output.

### Localization

You can see what log levels have been specified in your logging configuration by calling *log_levels()*.

```{r, log_levels_ex, eval = F}
log_levels()
```

```{r, echo = F}
pander::pander(level_severities())
```

Which will output only the *names* of the defined levels, not all of the detail that defines them.

### Detail

To get the details about a defined level you can call *level_info()*:

```{r, level_info_ex}
level_info("debug")
```

The detailed information about a log level shows every configurable attribute about the level, and
an example of how the level renders with its associated [crayon](https://github.com/r-lib/crayon) styles
for the level and message. A vanilla log layout consisting of only the level and msg would get rendered
with the look of the example attribute.

## Configuration

### Out of the Box

The default (OTB) logging configuration closely resembles the fairly ubiquitous [log4j](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html) level scheme.

There is a utility method called *display_log_levels()* that will output all loaded log levels from
the configuration rendered with their defined styles & definitions:

```{r, display_log_levels_ex}
display_log_levels()
```

*Note: even through [fansi](https://github.com/brodieG/fansi) is amazing at rendering these in html format, your terminal may look slightly different; expecialy the grayscale colors on log messages.*

### Customizing

To customize the log levels in your environment, please see the configuration vignette.