log_read {autometric} | R Documentation |
Read a log.
Description
Read a log file into R.
Usage
log_read(
path,
units_cpu = c("percentage", "fraction"),
units_memory = c("megabytes", "bytes", "kilobytes", "gigabytes"),
units_time = c("seconds", "minutes", "hours", "days"),
hidden = FALSE
)
Arguments
path |
Character vector of paths to files and/or directories of logs to read. |
units_cpu |
Character string with the units of the |
units_memory |
Character string with the units of the
|
units_time |
Character string, units of the |
|
Details
log_read()
is capable of reading a log file where both
autometric
and other processes have printed. Whenever autometric
writes to a log, it bounds the beginning and end of the text
with the keyword "__AUTOMETRIC__"
.
that way, log_read()
knows to only read and process the correct
lines of the file.
In addition, it automatically converts the log data
into the units units_time
,
units_cpu
, and units_memory
arguments.
Value
A data frame of metrics from the log with one row per log entry
and columns with metadata and resource usage metrics.
log_read()
automatically converts the data into the units
chosen with arguments units_time
, units_cpu
, and units_memory
.
The returned data frame has the following columns:
-
version
: Version of the package used to write the log entry. -
pid
: Process ID monitored. -
status
: A status code for the log entry. Status 0 means logging succeeded. A status code not equal to 0 indicates something went wrong and the metrics should not be trusted. -
time
: numeric time stamp at which the entry was logged.log_read()
automatically recenters this column so that time 0 indicates the first logged entry. Use theunits_time
argument to customize the units of this field. -
core
: CPU load of the process scaled relative to a single CPU core. Measures the amount of time the process spends running during a given interval of elapsed time.On Mac OS, the package uses native system calls to get CPU core usage. On Linux and Windows, the package calculates it manually using. user + kernel clock cycles that ran during a sampling interval. It measures the clock cycles that the process executed during the interval, converts the clock cycles into seconds, then divides the result by the elapsed time of the interval. The length of the sampling interval is the
seconds
argument supplied tolog_start()
, or length of time between calls tolog_print()
. The firstcore
measurement is 0 to reflect that a full sampling interval has not elapsed yet.core
can be read in as a percentage or fraction, depending on theunits_cpu
argument. -
cpu
:core
divided by the number of logical CPU cores. This metric measures the load on the machine as a whole, not just the CPU core it runs on. Use theunits_cpu
argument to customize the units of this field. -
rss
: resident set size, the total amount of memory used by the process at the time of logging. This include the memory unique to the process (unique set size USS) and shared memory. Use theunits_memory
argument to customize the units of this field. -
virtual
: total virtual memory available to the process. The process does not necessarily use all this memory, but it can request more virtual memory throughout its life cycle. Use theunits_memory
argument to customize the units of this field.
Examples
path <- tempfile()
log_start(seconds = 0.5, path = path)
Sys.sleep(2)
log_stop()
Sys.sleep(2)
log_read(path)
unlink(path)