The log4r_step() function can be used as an action in the action_levels()
function (as a list component for the fns list). Place a call to this
function in every failure condition that should produce a log (i.e., warn,
stop, notify). Only the failure condition with the highest severity for a
given validation step will produce a log entry (skipping failure conditions
with lower severity) so long as the call to log4r_step() is present.
Arguments
- x
A reference to the x-list object prepared by the
agent. This version of the x-list is the same as that generated viaget_agent_x_list(<agent>, i = <step>)except this version is internally generated and hence only available in an internal evaluation context.- message
The message to use for the log entry. When not provided, a default glue string is used for the messaging. This is dynamic since the internal
glue::glue()call occurs in the same environment asx, the x-list that's constrained to the validation step. The default message, used whenmessage = NULLis the glue string"Step {x$i} exceeded the {level} failure threshold (f_failed = {x$f_failed}) ['{x$type}']". As can be seen, a custom message can be crafted that uses other elements of the x-list with the{x$<component>}construction.- append_to
The file to which log entries at the warn level are appended. This can alternatively be one or more log4r appenders.
YAML
A pointblank agent can be written to YAML with yaml_write() and the
resulting YAML can be used to regenerate an agent (with yaml_read_agent())
or interrogate the target table (via yaml_agent_interrogate()). Here is an
example of how log4r_step() can be expressed in R code (within
action_levels(), itself inside create_agent()) and in the corresponding
YAML representation.
R statement:
create_agent(
tbl = ~ small_table,
tbl_name = "small_table",
label = "An example.",
actions = action_levels(
warn_at = 1,
fns = list(
warn = ~ log4r_step(
x, append_to = "example_log"
)
)
)
)YAML representation:
type: agent
tbl: ~small_table
tbl_name: small_table
label: An example.
lang: en
locale: en
actions:
warn_count: 1.0
fns:
warn: ~log4r_step(x, append_to = "example_log")
steps: []Should you need to preview the transformation of an agent to YAML (without
any committing anything to disk), use the yaml_agent_string() function. If
you already have a .yml file that holds an agent, you can get a glimpse
of the R expressions that are used to regenerate that agent with
yaml_agent_show_exprs().
Examples
For the example provided here, we'll use the included small_table dataset.
We are also going to create an action_levels() list object since this is
useful for demonstrating a logging scenario. It will have a threshold for
the warn state, and, an associated function that should be invoked
whenever the warn state is entered. Here, the function call with
log4r_step() will be invoked whenever there is one failing test unit.
al <-
action_levels(
warn_at = 1,
fns = list(
warn = ~ log4r_step(
x, append_to = "example_log"
)
)
)Within the action_levels()-produced object, it's important to match things
up: notice that warn_at is given a threshold and the list of functions
given to fns has a warn component.
Printing al will show us the settings for the action_levels object:
al
#> -- The `action_levels` settings
#> WARN failure threshold of 1test units.
#> \fns\ ~ log4r_step(x, append_to = "example_log")
#> ----Let's create an agent with small_table as the target table. We'll apply the
action_levels object created above as al, add two validation steps, and
then interrogate() the data.
agent <-
create_agent(
tbl = ~ small_table,
tbl_name = "small_table",
label = "An example.",
actions = al
) %>%
col_vals_gt(columns = d, 300) %>%
col_vals_in_set(columns = f, c("low", "high")) %>%
interrogate()
agent
From the agent report, we can see that both steps have yielded warnings upon
interrogation (i.e., filled yellow circles in the W column).
What's not immediately apparent is that when entering the warn state
in each validation step during interrogation, the log4r_step() function
call was twice invoked! This generated an "example_log" file in the working
directory (since it was not present before the interrogation) and log entries
were appended to the file. Here are the contents of the file: