How to use azlogr • azlogr

Configuration steps

Three things you should consider to set up to be able to use this package seamlessly:

Configure environment variables to fetch the ‘Azure Log Analytics’ workspace ID & shared key.
1. Ideally, this needs to be done outside ‘R’. But, you may create a .Rprofile file in your project root, and define the environment variable using Sys.setenv function. Example contents of the .Rprofile can be as below. Please note, this is not the suggested way, ideally you should define the environment variables via some secret, that depends on your working environment.

Sys.setenv(AZ_LOG_ID = "<enter-your-Azure-Log-Analytics-workspace-id>")
Sys.setenv(AZ_LOG_KEY = "<enter-your-Azure-Log-Analytics-shared-key>")

Identify any meta-data which needs to be collected and logged. There are some predefined information which are collected by the function logger::get_logger_meta_variables, which are reused in this package. However, by default not all are used while logging. You may also add some other meta-data as per the requirement, which can be be configured in one step using set_log_config function of this package.

library(azlogr)
# Collect some additional meta-data on top of the default selection level, time, msg.
# These are captured from the auto-collected components by logger::get_logger_meta_variables.
set_log_config(log_fields = c("level", "time", "msg", "user", "pid"))

# Some additional meta-data to be collected.
set_log_config(
  log_fields = c("level", "time", "msg"),
  additional_fields = list(country = "in", id = 123)
)

# Change the ordering in which the log message is displayed on console.
# Newly added meta-data can also be added in the log_fields arguments to change display order.
set_log_config(
  log_fields = c("country", "id", "time", "level", "msg"),
  additional_fields = list(country = "in", id = 123)
)

By default, logging to ‘Azure Log Analytics’ is enabled, that can be controlled via log_to_azure argument of set_log_config function. The custom logging table name in Azure Log Analytics workspace can be configured via log_type argument of the same set_log_config function. And finally, the workspace ID, shared key of Azure Log Analytics should be stored in some environment variable, by default which are AZ_LOG_ID & AZ_LOG_KEY. These can be changed by customer_id_env and shared_key_env arguments of the set_log_config function. An example configuration can be done in one-time step as below:

set_log_config(
  log_fields = c("country", "id", "time", "level", "msg"),
  additional_fields = list(country = "in", id = 123),
  log_type = "custom_table_r",
  customer_id_env = "ENV_WORKSPACE_ID",
  shared_key_env = "ENV_SHARED_KEY"
)

All the configurations can be done by doing the one-time step using set_log_config function. And then logging can be done very easily by just using the wrapper functions defined for each log level.

# Add new meta-data as `country = "in"` and `id = 123`.
# Defining the fields to be reported should be: `country`, `id`, `time`,
# `level`, and `msg`. Note that, you may change the order of these fields if
# needed.
set_log_config(
  log_fields = c("country", "id", "time", "level", "msg"),
  additional_fields = list(country = "in", id = 123),
  log_to_azure = FALSE
)

# Once the configuration is done, it is easy to just provide the required
# message using appropriate wrapper functions: logger_info, logger_warn,
# logger_error, etc.
logger_info("log information")
#> {"country":"in","id":123,"time":"2023-01-11 13:15:01","level":"INFO","msg":"log information"}
logger_warn("log warning")
#> {"country":"in","id":123,"time":"2023-01-11 13:15:02","level":"WARN","msg":"log warning"}

Lastly, the logging threshold can be defined to limit the output using the logger::log_threshold function.

logger::log_threshold(logger::WARN)
# Info is not logged when threshold is WARN
logger_info("log information")
logger_warn("log warning")
#> {"country":"in","id":123,"time":"2023-01-11 13:15:03","level":"WARN","msg":"log warning"}

# Change the threshold
logger::log_threshold(logger::INFO)
# Info is logged now when threshold is INFO
logger_info("log information")
#> {"country":"in","id":123,"time":"2023-01-11 13:15:03","level":"INFO","msg":"log information"}

Example use case

Below is an example workflow of configuring the logging mechanism and using logger_* functions to log.

# Azure Log Analytics workspace id and shared key are fetched
# from environment variables.
# `Sys.setenv` is used only for demonstration purpose!!
Sys.setenv(AZ_LOG_ID = "<enter-your-Azure-Log-Analytics-workspace-id>")
Sys.setenv(AZ_LOG_KEY = "<enter-your-Azure-Log-Analytics-shared-key>")

library(azlogr)

# Optionally, add additional meta-data, `country` and `id`, to be collected
# while logging, on top of the default fields - 'level', 'time', 'msg'.
set_log_config(
  log_fields = c("level", "time", "msg"),
  additional_fields = list(country = "in", id = 123)
)

# Use logger_* functions with appropriate logging level to log.
# If POST is successful, then it will be available in custom log table on
# Azure Log Analytics, by default table name will be `log_from_r`_CL (_CL is
# added by Azure for any custom log table)
logger_info("log info sent to Azure")
#> {"level":"INFO","time":"2023-01-11 13:15:04","msg":"log info sent to Azure","country":"in","id":123}

# If the POST request is unsuccessful due to Azure credential issue, then log
# message is displayed on console and a warning is generated with error details.
logger_info("log info sent to Azure")
#> {"level":"INFO","time":"2023-01-11 13:15:04","msg":"log info sent to Azure","country":"in","id":123}
#> Warning message:
#> In logger_level(logger::INFO, ...) :
#>   Some error happened while sending POST request to 'Azure Log Analytics' workspace.
#> Error message: Error in curl::curl_fetch_memory(url, handle = handle) :
#>   Could not resolve host: abcd.ods.opinsights.azure.com