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)
)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().
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.
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.
TRUE to throw an error if the thread is not supported on
the current platform. (See log_support().)
NULL (invisibly). Called for its side effects.
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.
path <- tempfile()
log_start(seconds = 0.5, path = path)
Sys.sleep(2)
log_stop()
Sys.sleep(2)
log_read(path)
#> version phase pid name status time core cpu resident virtual
#> 1 0.1.2.9000 __DEFAULT__ 5832 local 0 0.000 1.999 0.5 154.4397 876.843
#> 2 0.1.2.9000 __DEFAULT__ 5832 local 0 0.500 0.000 0.0 154.4397 876.843
#> 3 0.1.2.9000 __DEFAULT__ 5832 local 0 1.000 0.000 0.0 154.4397 876.843
#> 4 0.1.2.9000 __DEFAULT__ 5832 local 0 1.501 0.000 0.0 154.4397 876.843
unlink(path)