Historic.jl

Historic.@define RecordModule

Define a recorder module named RecordModule with a private event recording buffer.

RecordModule has a macro RecordModule.@record(name, k₁ = v₁, …) that can be used for defining (a pice of code to emit) events. The recorder is disabled by default. It has to be enabled by RecordModule.enable at run-time. Once the recorder is enabled, the events are recorded whenever execution of the program encounter the code path including @record.

RecordModule defines the following functions for manipulating recording:

• RecordModule.enable() enables recording.
• RecordModule.disable() disables recording.
• RecordModule.enable_logging() enables logging.
• RecordModule.disable_logging() disables logging.

RecordModule defines the following overloadable functions:

• RecordModule.defaultdata() returns a named tuple to be included in the event record by default.
• RecordModule.prefix() returns a string to be used asa prefix of the log message.
• RecordModule.isrecording() returns a Bool indicating if the events recorded by RecordModule.@record should be recorded by default.

Historic.Scratch

Pre-defined recorder module generated by Historic.@define Scratch. Historic.@record is an alias of Historic.Scratch.@record.

Scratch.@record($name, $k₁ = $v₁, …, $kₙ = $vₙ)
Scratch.@record($name, $k₁ = $v₁, …, $kₙ = $vₙ, {$a₁ = $b₁, …, $aₙ = $bₙ})

Record event named $name and optional event data (key-value pairs $kᵢ = $vᵢ) with optional control arguments $aᵢ = $bᵢ.

Extended help

Examples

• @record(:n1) records an event named :n1.
• @record(:n2, k1 = 0) records an event named :n2 with optional data key k1 and value 0.
• @record(rand(Bool) ? :n3 : :n4) records either an event named :n3 or an event named :n4.
• @record(:n5, {log = nothing}) records an event without logging it.

Arguments

The first argument $name is an expression evaluates to a Symbol.

If the last argument is wrapped in a pair of { and }, it is treated as a set of control argument (see below).

The rest of the arguments are optional. Each of these argument is either an assignment of form $k = $v or a variable name $k. The latter is equivalent to $k = $k.

Optional control argument

If the last argument is of form {$a₁ = $b₁, …, $aₙ = $bₙ}, each assignment expression $a = $b specifies a (non-data) control option.

• log ($b::Union{Nothing,NamedTuple}): Options to the logger. log = nothing disables logging.
• yield ($b::Bool): Passing yield = false tries to avoid code paths that may yield to the scheduler.

Historic.taskid(task::Task = current_task())

Get a (pseudo) id for a task.

It does not uniquely identify a task (thus "pseudo") when the task is garbage collected and the corresponding memory region is re-used.

Historic.objid(x)

Get a (pseudo) id for arbitrary object x.

It does not uniquely identify an object (thus "pseudo") when the object is garbage collected and the corresponding memory region is re-used.

Historic.uniqueid() -> id::UInt64

Generate a number unique within a julia process.

Scratch.enable()
Scratch.disable()

Enable/disable recording of the events generated by Scratch.@record.

Scratch.enable_logging()
Scratch.disable_logging()

Enable/disable logging of the events generated by Scratch.@record.

Historic.clear()

Remove recorded events in all existing recorder modules.

Historic.events() -> eventtable
Historic.events(recordmodule::Module) -> eventtable

Return a table of events recoded by recordmodule.@record. If used without an argument, return all events in all recorder modules.

Historic.flattable() -> flattable
Historic.flattable(recordmodule::Module) -> flattable
Historic.flattable(eventtable) -> flattable

Return a flatten table of events; i.e., all custom event data key-value pairs passed to @record can accessed as columns.

See also Historic.events.