--- title: "How to use azlogr" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{How to use azlogr} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` # Configuration steps Three things you should consider to set up to be able to use this package seamlessly: 1. Configure environment variables to fetch the 'Azure Log Analytics' workspace ID & shared key. a. 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. ```{r environment} Sys.setenv(AZ_LOG_ID = "") Sys.setenv(AZ_LOG_KEY = "") ``` 2. 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. ```{r metadata} 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) ) ``` 3. 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: ```{r setup} 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. ```{r logging} # 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. ```{r threshold} 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. ```{r example, eval = FALSE} # 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 = "") Sys.setenv(AZ_LOG_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 ```