R/job.R

In s-fleck/joblog: Log jobs with lgr

#' Log the start or end of a job
#'
#' Log the start or end (either succesfully or not) of a job. Each job has a
#' name (for example `update-prod-database`). Each unique run of a job is
#' identified by its (usually autogenerated `id`).
#'
#' @param name `character` scalar. Name of the job
#' @param status `integer` scalar. Status of the job; `0` = succesfully completed, `1` = started, `2` = failed.
#' @param jobtype `integer` scalar. `1` = scheduled (for example via cron), 2 = triggered, 3 = manually started
#' @param ... added to the resulting `list`
#' @param id a global unique id (such as UUID or ULID) for the job
#' @param repeats `timestamp` when the job is expected to repeat
#' @param path `character` scalar. path to the script that contains the job
#' @param msg `character` scalar. a custom message to add to the job's log
#'   message
#'
#' @section Side Effects:
#'   `job_start()` assigns the variable `.last_job_id` to the environment
#'   `joblog.globals`, which is used by `job_finished()` and `job_failed()`. If
#'   you want to run several jobs concurrently, you need to pass `id` in
#'   manually.
#'
#' @return `job_start()`, `job_finsihed()`, `job_failed()` return a `list()`
#'   that can be passed to `Logger$list_log()`
#' @export
#' @name job
#' @aliases job_start
#'
#' @examples
#' lg <- lgr::get_logger("test")
#' lg$list_log(job_start("update-database"))
#' lg$list_log(job_finished())
#'
#' # run the job again the next day
#' lg$list_log(job_start("update-database"))
#' lg$list_log(job_failed("something went wrong this time"))
#'
#' last_job_id()
job_start <- function(
  name,
  status =  1L,
  jobtype = 1L,
  ...,
  id = ulid::generate(),
  repeats = NULL,
  path = NULL,
  msg = NULL
){
  assert(is_scalar_character(id))
  assert(is_scalar_character(name))
  assert(is_scalar_integerish(status))
  assert(is_scalar_integerish(jobtype))
  assert(is.null(repeats) || is_POSIXct(repeats) || is_Date(repeats))
  assert(is.null(path) || is_scalar_character(path))

  assign(".last_job_id", id, envir = joblog.globals)

  job_msg <- "job started"
  if (!is.null(msg)){
    job_msg <- paste0(job_msg, ": ", msg)
  }

  compact(list(
    level = 400L,
    msg = job_msg,
    type = "job",
    id = id,
    name = name,
    status = status,
    jobtype = jobtype,
    repeats = repeats,
    path = path,
    ...,
    caller = "log_job_start"
  ))
}




#' @export
#' @rdname job
job_finished <- function(
  msg = NULL,
  id = last_job_id()
){
  job_msg <- "job finished successfully"
  if (!is.null(msg)){
    job_msg <- paste0(job_msg, ": ", msg)
  }

  list(level = 400L, msg = job_msg, type = "job",  id = id, status = 0L)
}




#' @export
#' @rdname job
job_failed <- function(
  msg = NULL,
  id = last_job_id()
){
  job_msg <- "job failed"
  if (!is.null(msg)){
    job_msg <- paste0(job_msg, ": ", msg)
  }

  list(level = 200L, msg = job_msg, type = "job", id = id, status = 2L)
}




#' @return `last_job_id()` returns the id (a `character` scalar) of the last
#'   job registered with `job_start()`.
#' @export
#' @rdname job
last_job_id <- function(){
  get(".last_job_id", envir = joblog.globals)
}