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. Names cannot include the pipe character "|" because it is the delimiter of fields in the log output.

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       phase  pid  name status time core cpu resident virtual
#> 1 0.1.2.9000 __DEFAULT__ 5832 local      0    0    0   0 154.4397 876.843
  unlink(path)