Gets the logged journal of events for a future

Source: R/100.journal.R

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.

journal(x, ...)

Arguments

x

A Future object.

...

Not used.

Value

A data frame of class FutureJournal with columns:

  1. event (character string) - type of event that took place

  2. category (character string) - the category of the event

  3. parent (character string) - (to be describe)

  4. start (POSIXct) - the timestamp when the event started

  5. at (difftime) - the time when the event started relative to first event

  6. duration (difftime) - the duration of the event

  7. future_label (character string) - the label of the future

  8. future_uuid (character string) - the UUID of the future

  9. 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> 2024-10-26 20:52:23 0.00000000 secs
#> 6         launch   overhead   <NA> 2024-10-26 20:52:23 0.01454687 secs
#> 2      getWorker   overhead launch 2024-10-26 20:52:23 0.01500416 secs
#> 3    eraseWorker   overhead launch 2024-10-26 20:52:23 0.01557612 secs
#> 4 attachPackages   overhead launch 2024-10-26 20:52:23 0.01642632 secs
#> 5  exportGlobals   overhead launch 2024-10-26 20:52:23 0.01682186 secs
#> 9       evaluate evaluation   <NA> 2024-10-26 20:52:23 0.05845833 secs
#> 7  receiveResult   overhead gather 2024-10-26 20:52:24 1.06248045 secs
#> 8         gather   overhead   <NA> 2024-10-26 20:52:24 1.06448340 secs
#>            duration future_label                          future_uuid
#> 1 3.245592e-03 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 6 3.344536e-03 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 2 1.010895e-04 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 3 4.134178e-04 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 4 3.218651e-05 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 5 3.554821e-04 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 9 1.003370e+00 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 7 2.763271e-04 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#> 8 8.177757e-05 secs         <NA> e4578ed9-86f0-fa66-708c-0a34addadf81
#>                           session_uuid
#> 1 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 6 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 2 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 3 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 4 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 5 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 9 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 7 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 8 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 
#> [[2]]
#>            event   category parent               start              at
#> 1         create   overhead   <NA> 2024-10-26 20:52:23 0.00000000 secs
#> 6         launch   overhead   <NA> 2024-10-26 20:52:23 0.01231742 secs
#> 2      getWorker   overhead launch 2024-10-26 20:52:23 0.01275325 secs
#> 3    eraseWorker   overhead launch 2024-10-26 20:52:23 0.01325178 secs
#> 4 attachPackages   overhead launch 2024-10-26 20:52:23 0.03558612 secs
#> 5  exportGlobals   overhead launch 2024-10-26 20:52:23 0.03608370 secs
#> 9       evaluate evaluation   <NA> 2024-10-26 20:52:24 0.07841396 secs
#> 7  receiveResult   overhead gather 2024-10-26 20:52:26 2.11889577 secs
#> 8         gather   overhead   <NA> 2024-10-26 20:52:26 2.12068152 secs
#>            duration future_label                          future_uuid
#> 1 1.499891e-03 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 6 2.493501e-02 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 2 9.179115e-05 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 3 2.172899e-02 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 4 4.124641e-05 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 5 3.929138e-04 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 9 2.040013e+00 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 7 2.691746e-04 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#> 8 7.009506e-05 secs         <NA> 041e3ee7-cb2c-3046-232a-19d90aa16c0f
#>                           session_uuid
#> 1 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 6 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 2 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 3 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 4 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 5 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 9 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 7 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 8 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 
#> [[3]]
#>            event   category parent               start              at
#> 1         create   overhead   <NA> 2024-10-26 20:52:23 0.00000000 secs
#> 6         launch   overhead   <NA> 2024-10-26 20:52:23 0.01262093 secs
#> 2      getWorker   overhead launch 2024-10-26 20:52:23 0.01306319 secs
#> 3    eraseWorker   overhead launch 2024-10-26 20:52:24 1.01451850 secs
#> 4 attachPackages   overhead launch 2024-10-26 20:52:24 1.01665425 secs
#> 5  exportGlobals   overhead launch 2024-10-26 20:52:24 1.01786041 secs
#> 9       evaluate evaluation   <NA> 2024-10-26 20:52:25 1.06166816 secs
#> 7  receiveResult   overhead gather 2024-10-26 20:52:28 4.06833839 secs
#> 8         gather   overhead   <NA> 2024-10-26 20:52:28 4.07013059 secs
#>            duration future_label                          future_uuid
#> 1 1.618624e-03 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 6 1.008293e+00 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 2 1.000290e+00 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 3 8.730888e-04 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 4 8.630753e-05 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 5 8.308887e-04 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 9 3.006144e+00 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 7 2.794266e-04 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#> 8 6.842613e-05 secs         <NA> 406fedf5-b9e1-6270-1ac1-0be295ec881f
#>                           session_uuid
#> 1 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 6 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 2 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 3 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 4 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 5 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 9 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 7 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 8 2a2dfd5d-e029-3e3c-9a92-ddae8df51f33
#> 

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