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-04-19 09:45:08 0.000000000 secs
#> 4        launch   overhead   <NA> 2025-04-19 09:45:08 0.002168179 secs
#> 2     getWorker   overhead launch 2025-04-19 09:45:08 0.002276421 secs
#> 3   eraseWorker   overhead launch 2025-04-19 09:45:08 0.221534967 secs
#> 7      evaluate evaluation   <NA> 2025-04-19 09:45:09 0.269107580 secs
#> 5 receiveResult   overhead gather 2025-04-19 09:45:10 1.387793779 secs
#> 6        gather   overhead   <NA> 2025-04-19 09:45:10 1.388931036 secs
#> 8       resolve   overhead   <NA> 2025-04-19 09:45:10 1.443564653 secs
#>            duration future_label                         future_uuid
#> 1 1.775980e-03 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 4 2.248182e-01 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 2 2.182391e-01 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 3 5.555153e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 7 1.104215e+00 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 5 1.823902e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 6 7.271767e-05 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#> 8 1.406670e-05 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-17
#>                       session_uuid
#> 1 bdbdfeff674b525d44fe0a1b786d028b
#> 4 bdbdfeff674b525d44fe0a1b786d028b
#> 2 bdbdfeff674b525d44fe0a1b786d028b
#> 3 bdbdfeff674b525d44fe0a1b786d028b
#> 7 bdbdfeff674b525d44fe0a1b786d028b
#> 5 bdbdfeff674b525d44fe0a1b786d028b
#> 6 bdbdfeff674b525d44fe0a1b786d028b
#> 8 bdbdfeff674b525d44fe0a1b786d028b
#> 
#> [[2]]
#>           event   category parent               start               at
#> 1        create   overhead   <NA> 2025-04-19 09:45:09 0.000000000 secs
#> 4        launch   overhead   <NA> 2025-04-19 09:45:09 0.003958941 secs
#> 2     getWorker   overhead launch 2025-04-19 09:45:09 0.004151106 secs
#> 3   eraseWorker   overhead launch 2025-04-19 09:45:09 0.334772110 secs
#> 7      evaluate evaluation   <NA> 2025-04-19 09:45:09 0.382142782 secs
#> 5 receiveResult   overhead gather 2025-04-19 09:45:11 2.537276745 secs
#> 6        gather   overhead   <NA> 2025-04-19 09:45:11 2.539018154 secs
#> 8       resolve   overhead   <NA> 2025-04-19 09:45:11 2.544245481 secs
#>            duration future_label                         future_uuid
#> 1 3.381968e-03 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 4 3.351159e-01 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 2 3.297577e-01 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 3 4.286766e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 7 2.153375e+00 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 5 2.949238e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 6 1.425743e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#> 8 2.932549e-05 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-18
#>                       session_uuid
#> 1 bdbdfeff674b525d44fe0a1b786d028b
#> 4 bdbdfeff674b525d44fe0a1b786d028b
#> 2 bdbdfeff674b525d44fe0a1b786d028b
#> 3 bdbdfeff674b525d44fe0a1b786d028b
#> 7 bdbdfeff674b525d44fe0a1b786d028b
#> 5 bdbdfeff674b525d44fe0a1b786d028b
#> 6 bdbdfeff674b525d44fe0a1b786d028b
#> 8 bdbdfeff674b525d44fe0a1b786d028b
#> 
#> [[3]]
#>           event   category parent               start               at
#> 1        create   overhead   <NA> 2025-04-19 09:45:09 0.000000000 secs
#> 4        launch   overhead   <NA> 2025-04-19 09:45:09 0.002678633 secs
#> 2     getWorker   overhead launch 2025-04-19 09:45:09 0.002816916 secs
#> 3   eraseWorker   overhead launch 2025-04-19 09:45:10 0.871168613 secs
#> 7      evaluate evaluation   <NA> 2025-04-19 09:45:10 0.907482386 secs
#> 5 receiveResult   overhead gather 2025-04-19 09:45:13 3.916936159 secs
#> 6        gather   overhead   <NA> 2025-04-19 09:45:13 3.918665409 secs
#> 8       resolve   overhead   <NA> 2025-04-19 09:45:13 3.924418926 secs
#>            duration future_label                         future_uuid
#> 1 2.311707e-03 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 4 8.717399e-01 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 2 8.678100e-01 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 3 4.348755e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 7 3.007834e+00 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 5 3.004074e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 6 1.378059e-04 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#> 8 3.576279e-05 secs         <NA> bdbdfeff674b525d44fe0a1b786d028b-19
#>                       session_uuid
#> 1 bdbdfeff674b525d44fe0a1b786d028b
#> 4 bdbdfeff674b525d44fe0a1b786d028b
#> 2 bdbdfeff674b525d44fe0a1b786d028b
#> 3 bdbdfeff674b525d44fe0a1b786d028b
#> 7 bdbdfeff674b525d44fe0a1b786d028b
#> 5 bdbdfeff674b525d44fe0a1b786d028b
#> 6 bdbdfeff674b525d44fe0a1b786d028b
#> 8 bdbdfeff674b525d44fe0a1b786d028b
#> 

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