logging/viz: Add docstrings

Author: jpsamaroo

ext/GraphVizExt.jl

@@ -23,6 +23,23 @@ function pretty_time(t; digits=3)
         "$(r(t)) ns"
     end
 end
+
+"""
+    Dagger.render_logs(logs::Dict, ::Val{:graphviz}; disconnected=false,
+                       color_by=:fn, layout_engine="dot",
+                       times::Bool=true, times_digits::Integer=3)
+
+Render a graph of the task dependencies and data dependencies in `logs` using GraphViz.
+
+Requires the following events enabled in `enable_logging!`: `taskdeps`, `tasknames`, `taskargs`, `taskargmoves`
+
+Options:
+- `disconnected`: If `true`, render disconnected vertices (tasks or arguments without upstream/downstream dependencies)
+- `color_by`: How to color tasks; if `:fn`, then color by unique function name, if `:proc`, then color by unique processor
+- `layout_engine`: The layout engine to use for GraphViz
+- `times`: If `true`, annotate each task with its start and finish times
+- `times_digits`: Number of digits to display in the time annotations
+"""
 function Dagger.render_logs(logs::Dict, ::Val{:graphviz}; disconnected=false,
                             color_by=:fn, layout_engine="dot",
                             times::Bool=true, times_digits::Integer=3)

ext/PlotsExt.jl

@@ -67,6 +67,11 @@ end
 
 # Implementation adapted from:
 # https://discourse.julialang.org/t/how-to-make-a-gantt-plot-with-plots-jl/95165/7
+"""
+    Dagger.render_logs(logs::Dict, ::Val{:plots_gantt}; kwargs...)
+
+Render a Gantt chart of task execution in `logs` using Plots. `kwargs` are passed to `plot` directly.
+"""
 function Dagger.render_logs(logs::Dict, ::Val{:plots_gantt}; kwargs...)
     df = logs_to_df(logs)
 

src/utils/logging.jl

@@ -1,5 +1,19 @@
 # Logging utilities
 
+"""
+    enable_logging!(;kwargs...)
+
+Enables logging globally for all workers. Certain core events are always enabled by this call, but additional ones may be specified via `kwargs`.
+
+Extra events:
+- `metrics::Bool`: Enables various utilization and allocation metrics
+- `timeline::Bool`: Enables raw "timeline" values, which are event-specific; not recommended except for debugging
+- `tasknames::Bool`: Enables generating unique task names for each task
+- `taskdeps::Bool`: Enables reporting of upstream task dependencies (as task IDs) for each task argument
+- `taskargs::Bool`: Enables reporting of upstream non-task dependencies (as `objectid` hash) for each task argument
+- `taskargmoves::Bool`: Enables reporting of copies of upstream dependencies (as original and copy `objectid` hashes) for each task argument
+- `profile::Bool`: Enables profiling of task execution; not currently recommended, as it adds significant overhead
+"""
 function enable_logging!(;metrics::Bool=true,
                           timeline::Bool=false,
                           tasknames::Bool=true,
@@ -37,13 +51,30 @@ function enable_logging!(;metrics::Bool=true,
         ml[:psat] = Dagger.Events.ProcessorSaturation()
     end
     Dagger.Sch.eager_context().log_sink = ml
+    return
 end
+
+"""
+    disable_logging!()
+
+Disables logging previously enabled with `enable_logging!`.
+"""
 function disable_logging!()
     Dagger.Sch.eager_context().log_sink = TimespanLogging.NoOpLog()
+    return
 end
-function fetch_logs!()
-    return TimespanLogging.get_logs!(Dagger.Sch.eager_context())
-end
+
+"""
+    fetch_logs!() -> Dict{Int, Dict{Symbol, Vector}}
+
+Fetches and returns the currently-accumulated logs for each worker. Each entry
+of the outer `Dict` is keyed on worker ID, so `logs[1]` are the logs for worker
+`1`.
+
+Consider using `show_logs` or `render_logs` to generate a renderable display of
+these logs.
+"""
+fetch_logs!() = TimespanLogging.get_logs!(Dagger.Sch.eager_context())
 
 function logs_event_pairs(f, logs::Dict)
     running_events = Dict{Tuple,Int}()

src/visualization.jl

@@ -1,19 +1,34 @@
 # Printable representation
 
-show_logs(io::IO, t, vizmode::Symbol; options...) =
-    show_logs(io, t, Val{vizmode}(); options...)
+"""
+    show_logs(io::IO, logs, vizmode::Symbol; options...)
+    show_logs(io::IO, t, logs, vizmode::Symbol; options...)
+
+Displays the logs of a task `t` and/or logs object `logs` using the visualization mode `vizmode`, which is written to the given IO stream `io`. `options` are specific to the visualization mode.
+
+---
+
+    show_logs(logs, vizmode::Symbol; options...)
+    show_logs(t, logs, vizmode::Symbol; options...)
+
+Returns a string representation of the logs of a task `t` and/or logs object `logs` using the visualization mode `vizmode`. `options` are specific to the visualization mode.
+"""
+function show_logs end
+
+show_logs(io::IO, logs, vizmode::Symbol; options...) =
+    show_logs(io, logs, Val{vizmode}(); options...)
 show_logs(io::IO, t, logs, vizmode::Symbol; options...) =
     show_logs(io, t, Val{vizmode}(); options...)
 show_logs(io::IO, ::T, ::Val{vizmode}; options...) where {T,vizmode} =
     throw(ArgumentError("show_logs: Task/logs type `$T` not supported for visualization mode `$(repr(vizmode))`"))
 show_logs(io::IO, ::T, ::Logs, ::Val{vizmode}; options...) where {T,Logs,vizmode} =
     throw(ArgumentError("show_logs: Task type `$T` and logs type `$Logs` not supported for visualization mode `$(repr(vizmode))`"))
 
-show_logs(t, vizmode::Symbol; options...) =
-    show_logs(t, Val{vizmode}(); options...)
+show_logs(logs, vizmode::Symbol; options...) =
+    show_logs(logs, Val{vizmode}(); options...)
 show_logs(t, logs, vizmode::Symbol; options...) =
     show_logs(t, logs, Val{vizmode}(); options...)
-function show_logs(t, ::Val{vizmode}; options...) where vizmode
+function show_logs(logs, ::Val{vizmode}; options...) where vizmode
     iob = IOBuffer()
     show_logs(iob, t, Val{vizmode}(); options...)
     return String(take!(iob))
@@ -26,10 +41,18 @@ end
 
 # Displayable representation
 
-render_logs(t, vizmode::Symbol; options...) =
-    render_logs(t, Val{vizmode}(); options...)
+"""
+    render_logs(logs, vizmode::Symbol; options...)
+    render_logs(t, logs, vizmode::Symbol; options...)
+
+Returns a displayable representation of the logs of a task `t` and/or logs object `logs` using the visualization mode `vizmode`. `options` are specific to the visualization mode.
+"""
+function render_logs end
+
+render_logs(logs, vizmode::Symbol; options...) =
+    render_logs(logs, Val{vizmode}(); options...)
 render_logs(t, logs, vizmode::Symbol; options...) =
-    render_logs(t, Val{vizmode}(); options...)
+    render_logs(t, logs, Val{vizmode}(); options...)
 render_logs(::T, ::Val{vizmode}; options...) where {T,vizmode} =
     throw(ArgumentError("render_logs: Task/logs type `$T` not supported for visualization mode `$(repr(vizmode))`"))
 render_logs(::T, ::Logs, ::Val{vizmode}; options...) where {T,Logs,vizmode} =