Gets the logged journal of events for a future — journal • future.tools

WARNING: This function is under development. It can change at any time. For now, please, do not depend on this function in a published R package.

Usage

journal(x, ...)

Arguments

x: A Future object.
...: Not used.

Value

A data frame of class FutureJournal with columns:

event (character string) - type of event that took place
category (character string) - the category of the event
parent (character string) - (to be describe)
start (POSIXct) - the timestamp when the event started
at (difftime) - the time when the event started relative to first event
duration (difftime) - the duration of the event
future_label (character string) - the label of the future
future_uuid (character string) - the UUID of the future
session_uuid (character string) - the UUID of the R session where the event took place

The common events are:

create - the future was created (an overhead)
launch - the future was launched (an overhead)
evaluate - the future was evaluated (an evaluation)
resolved - the future was queried (may be occur multiple times) (an overhead)
gather - the results was retrieved (an overhead)

but others may be added by other Future classes.

Common event categories are:

evaluation - processing time is spent on evaluation
overhead - processing time is spent on orchestrating the future
waiting - processing time is spent on waiting to set up or querying the future

but others may be added by other Future classes.

The data frame is sorted by the at time. Note that the timestamps for the evaluate event are based on the local time on the worker. The system clocks on the worker and the calling R system may not be in perfect sync.

Enabling and disabling event logging

To enable logging of events, set option future.journal is TRUE. To disable, set it to FALSE (default).

See also

Use capture_journals() to capture journals from all futures.

Examples

## Enable journaling of futures
oopts <- options(future.journal = TRUE)

plan(multisession, workers = 2L)

t_start <- Sys.time()
fs <- lapply(1:3, FUN = function(x) future({ Sys.sleep(x); sqrt(x) }))
vs <- value(fs)
js <- lapply(fs, FUN = journal, baseline = t_start)
print(js)
#> [[1]]
#>           event   category parent               start               at
#> 1        create   overhead   <NA> 2025-03-28 22:02:38 0.000000000 secs
#> 4        launch   overhead   <NA> 2025-03-28 22:02:38 0.003238678 secs
#> 2     getWorker   overhead launch 2025-03-28 22:02:38 0.003318310 secs
#> 3   eraseWorker   overhead launch 2025-03-28 22:02:38 0.003929377 secs
#> 7      evaluate evaluation   <NA> 2025-03-28 22:02:38 0.068408251 secs
#> 5 receiveResult   overhead gather 2025-03-28 22:02:39 1.121487856 secs
#> 6        gather   overhead   <NA> 2025-03-28 22:02:39 1.123256445 secs
#> 8       resolve   overhead   <NA> 2025-03-28 22:02:39 1.135453701 secs
#>            duration future_label                         future_uuid
#> 1 2.979994e-03 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 4 2.369356e-02 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 2 9.226799e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 3 2.193785e-02 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 7 1.032018e+00 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 5 2.622604e-04 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 6 8.940697e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#> 8 2.717972e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-17
#>                       session_uuid
#> 1 907402de71e8157b729b6b0636699f08
#> 4 907402de71e8157b729b6b0636699f08
#> 2 907402de71e8157b729b6b0636699f08
#> 3 907402de71e8157b729b6b0636699f08
#> 7 907402de71e8157b729b6b0636699f08
#> 5 907402de71e8157b729b6b0636699f08
#> 6 907402de71e8157b729b6b0636699f08
#> 8 907402de71e8157b729b6b0636699f08
#> 
#> [[2]]
#>           event   category parent               start               at
#> 1        create   overhead   <NA> 2025-03-28 22:02:38 0.000000000 secs
#> 4        launch   overhead   <NA> 2025-03-28 22:02:38 0.001740932 secs
#> 2     getWorker   overhead launch 2025-03-28 22:02:38 0.001817226 secs
#> 3   eraseWorker   overhead launch 2025-03-28 22:02:38 0.002372265 secs
#> 7      evaluate evaluation   <NA> 2025-03-28 22:02:38 0.066682816 secs
#> 5 receiveResult   overhead gather 2025-03-28 22:02:40 2.096972942 secs
#> 6        gather   overhead   <NA> 2025-03-28 22:02:40 2.097708702 secs
#> 8       resolve   overhead   <NA> 2025-03-28 22:02:40 2.099483013 secs
#>            duration future_label                         future_uuid
#> 1 1.490831e-03 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 4 2.385545e-02 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 2 8.511543e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 3 2.235723e-02 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 7 2.027905e+00 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 5 1.208782e-04 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 6 3.242493e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#> 8 1.120567e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-18
#>                       session_uuid
#> 1 907402de71e8157b729b6b0636699f08
#> 4 907402de71e8157b729b6b0636699f08
#> 2 907402de71e8157b729b6b0636699f08
#> 3 907402de71e8157b729b6b0636699f08
#> 7 907402de71e8157b729b6b0636699f08
#> 5 907402de71e8157b729b6b0636699f08
#> 6 907402de71e8157b729b6b0636699f08
#> 8 907402de71e8157b729b6b0636699f08
#> 
#> [[3]]
#>           event   category parent               start               at
#> 1        create   overhead   <NA> 2025-03-28 22:02:38 0.000000000 secs
#> 4        launch   overhead   <NA> 2025-03-28 22:02:38 0.001644611 secs
#> 2     getWorker   overhead launch 2025-03-28 22:02:38 0.001718044 secs
#> 3   eraseWorker   overhead launch 2025-03-28 22:02:39 1.076527596 secs
#> 7      evaluate evaluation   <NA> 2025-03-28 22:02:39 1.120307922 secs
#> 5 receiveResult   overhead gather 2025-03-28 22:02:42 4.130041122 secs
#> 6        gather   overhead   <NA> 2025-03-28 22:02:42 4.131712198 secs
#> 8       resolve   overhead   <NA> 2025-03-28 22:02:42 4.136856079 secs
#>            duration future_label                         future_uuid
#> 1 1.399517e-03 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 4 1.077933e+00 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 2 1.073243e+00 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 3 1.040936e-03 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 7 3.007167e+00 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 5 2.737045e-04 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 6 1.001358e-04 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#> 8 4.529953e-05 secs         <NA> 907402de71e8157b729b6b0636699f08-19
#>                       session_uuid
#> 1 907402de71e8157b729b6b0636699f08
#> 4 907402de71e8157b729b6b0636699f08
#> 2 907402de71e8157b729b6b0636699f08
#> 3 907402de71e8157b729b6b0636699f08
#> 7 907402de71e8157b729b6b0636699f08
#> 5 907402de71e8157b729b6b0636699f08
#> 6 907402de71e8157b729b6b0636699f08
#> 8 907402de71e8157b729b6b0636699f08
#> 

## Stop parallel workers and disable journal logging and signaling
plan(sequential)
options(oopts)