Start a background thread that periodically writes system usage metrics of the current R process to a log file. See log_read() for explanations of the specific metrics.

log_start(
  path,
  seconds = 1,
  pids = c(local = Sys.getpid()),
  error = getOption("autometric_error", TRUE)
)

Arguments

path

Character string, path to a file to log resource usage. On Windows, the path must point to a physical file on disk. On Unix-like systems, path can be "/dev/stdout" to print to standard output or "/dev/stderr" to print to standard error.

Standard output is the most convenient option for high-performance computing scenarios where worker processes already write to log files. Such workers usually already redirect standard output to a physical file, as with a cluster like SLURM, or capture messages with Amazon CloudWatch.

Normally, standard output and standard error are discouraged because of how they interact with the R API and R console. However, the exported user interface of autometric only ever prints from a detached POSIX thread where it is unsafe to use Rprintf() or REprintf().

seconds

Positive number, number of seconds between writes to the log file. This number should be noticeably large, anywhere between half a second to several seconds or minutes. A low number of seconds could burden the operating system and generate large log files. Because of the way CPU usage measurements work, the first log entry starts only after after the first interval of seconds has passed.

pids

Nonempty vector of non-negative integers of process IDs to monitor. NOTE: On Mac OS, only the currently running process can be monitored. This is due to security restrictions around certain system calls, c.f. https://os-tres.net/blog/2010/02/17/mac-os-x-and-task-for-pid-mach-call/. # nolint If the pids vector is named, then the names will show alongside the process IDs in the log entries.

error

TRUE to throw an error if the thread is not supported on the current platform. (See log_support().)

Value

NULL (invisibly). Called for its side effects.

Details

Only one thread can run at a time. If the thread is already running, then log_start() does not start an additional one. Before creating a new thread, call log_stop() to terminate the first one.

Examples

  path <- tempfile()
  log_start(seconds = 0.5, path = path)
  Sys.sleep(2)
  log_stop()
  Sys.sleep(2)
  log_read(path)
#>      version  pid  name status  time core cpu resident  virtual
#> 1 0.0.5.9000 5812 local      0 0.000    0   0 154.3127 876.6546
#> 2 0.0.5.9000 5812 local      0 0.500    0   0 154.3127 876.6546
#> 3 0.0.5.9000 5812 local      0 1.001    0   0 154.3127 876.6546
#> 4 0.0.5.9000 5812 local      0 1.501    0   0 154.3127 876.6546
  unlink(path)