Print once to the log.

Sample CPU load metrics and print a single line to the log for each process in pids. Used for debugging and testing only. Not for users.

log_print(
  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 to sample CPU load metrics before printing to the log. This number should be at least 1, usually more. A low number of seconds could burden the operating system and generate large log files.

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.

Examples

  path = tempfile()
  log_print(path = path)
  log_read(path)
#>      version  pid  name status time core cpu resident  virtual
#> 1 0.0.5.9000 5812 local      0    0    0   0 154.3127 876.6546
  unlink(path)