Flexible and Customisable Logging System.
stenographer
The stenographer package provides a flexible logging framework with hierarchical logging levels, database integration, and contextual logging capabilities. It includes support for SQLite storage, colour-coded output, and parallel processing support.
The latest version includes support for SQLite database logging and context management.
Installation
You can install the released version of stenographer from CRAN:
install.packages("stenographer")
You can install stenographer from www.github.com/dereckmezquita/stenographer with:
# install.packages("remotes")
remotes::install_github("dereckmezquita/stenographer")
Basic Usage
Here’s a quick example of how to use stenographer:
box::use(stenographer[Stenographer, LogLevel])
# Create a basic logger
steno <- Stenographer$new()
# Log some messages
steno$info("This is an informational message")
#> 2025-01-13T13:55:15.524Z INFO This is an informational message
steno$warn("This is a warning")
#> 2025-01-13T13:55:15.526Z WARNING This is a warning
steno$error("This is an error")
#> 2025-01-13T13:55:15.549Z ERROR This is an error
Features
Customisable Logging
You can customise the stenographer by specifying the minimum log level, output file, and custom print function:
log_file <- tempfile("app_log")
custom_steno <- Stenographer$new(
level = LogLevel$WARNING,
file_path = log_file,
print_fn = message
)
custom_steno$info("This won't be logged")
custom_steno$warn("This will be logged to console and file")
#> 2025-01-13T13:55:15.650Z WARNING This will be logged to console and file
custom_steno$error("This is an error message", error = "Some error")
#> 2025-01-13T13:55:15.651Z ERROR This is an error message
#> Error:
#> "Some error"
Logs are written to the specified file as JSON objects:
cat(readLines(log_file), sep = "\n")
#> {"datetime":"2025-01-13T13:55:15.650Z","level":"WARNING","msg":"This will be logged to console and file","data":{},"error":{},"context":{}}
#> {"datetime":"2025-01-13T13:55:15.651Z","level":"ERROR","msg":"This is an error message","data":{},"error":"[\"Some error\"]","context":{}}
Database Logging
stenographer now supports logging to a SQLite database and context management so you can easily track application events. The context is useful for filtering and querying logs based on specific criteria from SQLite:
box::use(RSQLite[ SQLite ])
box::use(DBI[ dbConnect, dbDisconnect, dbGetQuery ])
# Create a database connection
db <- dbConnect(SQLite(), "log.sqlite")
# Create a stenographer that logs to the database
db_steno <- Stenographer$new(
context = list(app_name = "MyApp", fun = "main"),
db_conn = db,
table_name = "app_logs"
)
# Log some messages
db_steno$info("This is logged to the database")
#> 2025-01-13T13:55:15.772Z INFO This is logged to the database
#> Context:
#> {
#> "app_name": "MyApp",
#> "fun": "main"
#> }
db_steno$warn("This is a warning", data = list(code = 101))
#> 2025-01-13T13:55:15.778Z WARNING This is a warning
#> Data:
#> {
#> "code": 101
#> }
#> Context:
#> {
#> "app_name": "MyApp",
#> "fun": "main"
#> }
db_steno$error("An error occurred", error = "Division by zero")
#> 2025-01-13T13:55:15.844Z ERROR An error occurred
#> Error:
#> "Division by zero"
#> Context:
#> {
#> "app_name": "MyApp",
#> "fun": "main"
#> }
# Example of querying the logs
query <- "SELECT * FROM app_logs WHERE level = 'ERROR'"
result <- dbGetQuery(db, query)
print(result)
#> id datetime level context
#> 1 3 2025-01-12T20:03:40.117Z ERROR {"app_name":["MyApp"],"fun":["main"]}
#> 2 6 2025-01-13T13:54:50.711Z ERROR {"app_name":["MyApp"],"fun":["main"]}
#> 3 9 2025-01-13T13:55:15.844Z ERROR {"app_name":["MyApp"],"fun":["main"]}
#> msg data error
#> 1 An error occurred <NA> ["[\\"Division by zero\\"]"]
#> 2 An error occurred <NA> ["[\\"Division by zero\\"]"]
#> 3 An error occurred <NA> ["[\\"Division by zero\\"]"]
# Don't forget to close the database connection when you're done
dbDisconnect(db)
Helper Functions
Stenographer includes helper functions like valueCoordinates and tableToString to provide detailed context in log messages:
box::use(stenographer[valueCoordinates, tableToString])
# Create a sample dataset with some issues
df <- data.frame(
a = c(1, NA, 3, 4, 5),
b = c(2, 4, NA, 8, 10),
c = c(3, 6, 9, NA, 15)
)
# Find coordinates of NA values
na_coords <- valueCoordinates(df)
if (nrow(na_coords) > 0) {
steno$warn(
"NA values found in the dataset",
data = list(
na_locations = na_coords,
dataset_preview = tableToString(df)
)
)
}
#> 2025-01-13T13:55:15.858Z WARNING NA values found in the dataset
#> Data:
#> {
#> "na_locations": [
#> {
#> "column": 1,
#> "row": 2
#> },
#> {
#> "column": 2,
#> "row": 3
#> },
#> {
#> "column": 3,
#> "row": 4
#> }
#> ],
#> "dataset_preview": " a b c\n1 1 2 3\n2 NA 4 6\n3 3 NA 9\n4 4 8 NA\n5 5 10 15"
#> }
Error Logging with Context
stenographer makes it easy to log errors with context:
process_data <- function(df) {
tryCatch({
result <- df$a / df$b
if (any(is.infinite(result))) {
inf_coords <- valueCoordinates(data.frame(result), Inf)
steno$error(
"Division by zero occurred",
data = list(
infinite_values = inf_coords,
dataset_preview = tableToString(df)
)
)
stop("Division by zero error")
}
return(result)
}, error = function(e) {
steno$error(
paste("An error occurred while processing data:", e$message),
data = list(dataset_preview = tableToString(df)),
error = e
)
stop(e)
})
}
# Test the function with problematic data
df <- data.frame(a = c(1, 2, 3), b = c(0, 2, 0))
process_data(df)
#> 2025-01-13T13:55:15.883Z ERROR Division by zero occurred
#> Data:
#> {
#> "infinite_values": [
#> {
#> "column": 1,
#> "row": 1
#> },
#> {
#> "column": 1,
#> "row": 3
#> }
#> ],
#> "dataset_preview": " a b\n1 1 0\n2 2 2\n3 3 0"
#> }
#> 2025-01-13T13:55:15.884Z ERROR An error occurred while processing data: Division by zero error
#> Data:
#> {
#> "dataset_preview": " a b\n1 1 0\n2 2 2\n3 3 0"
#> }
#> Error:
#> {
#> "name": "simpleError",
#> "message": "Division by zero error",
#> "call": "doTryCatch(return(expr), name, parentenv, handler)"
#> }
#> Error in doTryCatch(return(expr), name, parentenv, handler): Division by zero error
Parallel Processing Support
stenographer provides support for logging in parallel environments:
box::use(future)
box::use(future.apply[future_lapply])
box::use(stenographer[messageParallel])
steno <- Stenographer$new(print_fn = messageParallel)
future::plan(future$multisession, workers = 2)
result <- future_lapply(1:5, function(i) {
messageParallel(sprintf("Processing item %d", i))
if (i == 3) {
steno$warn(sprintf("Warning for item %d", i))
}
return(i * 2)
})
future::plan(future::sequential)
#> Processing item 1
#> Processing item 2
#> Processing item 3
#> 2024-08-03T11:18:03.091Z WARNING Warning for item 3
#> Processing item 4
#> Processing item 5
Contributing
Contributions to stenographer are welcome! Please refer to the CONTRIBUTING.md file for guidelines.
License
This package is licensed under the MIT License.
Citation
If you use this package in your research or work, please cite it as:
Mezquita, D. (2025). stenographer: Flexible and Customisable Logging System. R package version 1.0.0. https://github.com/dereckmezquita/stenographer.