# How to use azlogr

# 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.

   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>")

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.

    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:

    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